1.\" 2.\" Copyright (c) 1996 Joerg Wunsch 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd April 4, 2008 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm msleep , 33.Nm msleep_spin , 34.Nm pause , 35.Nm tsleep , 36.Nm wakeup 37.Nd wait for events 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/systm.h 41.In sys/proc.h 42.Ft int 43.Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" 44.Ft int 45.Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" 46.Ft void 47.Fn pause "const char *wmesg" "int timo" 48.Ft int 49.Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo" 50.Ft void 51.Fn wakeup "void *chan" 52.Ft void 53.Fn wakeup_one "void *chan" 54.Sh DESCRIPTION 55The functions 56.Fn tsleep , 57.Fn msleep , 58.Fn msleep_spin , 59.Fn pause , 60.Fn wakeup , 61and 62.Fn wakeup_one 63handle event-based thread blocking. 64If a thread must wait for an 65external event, it is put to sleep by 66.Fn tsleep , 67.Fn msleep , 68.Fn msleep_spin , 69or 70.Fn pause . 71Threads may also wait using one of the locking primitive sleep routines 72.Xr mtx_sleep 9 , 73.Xr rw_sleep 9 , 74or 75.Xr sx_sleep 9 . 76.Pp 77The parameter 78.Fa chan 79is an arbitrary address that uniquely identifies the event on which 80the thread is being put to sleep. 81All threads sleeping on a single 82.Fa chan 83are woken up later by 84.Fn wakeup , 85often called from inside an interrupt routine, to indicate that the 86resource the thread was blocking on is available now. 87.Pp 88The parameter 89.Fa priority 90specifies a new priority for the thread as well as some optional flags. 91If the new priority is not 0, 92then the thread will be made 93runnable with the specified 94.Fa priority 95when it resumes. 96.Dv PZERO 97should never be used, as it is for compatibility only. 98A new priority of 0 means to use the thread's current priority when 99it is made runnable again. 100If 101.Fa priority 102includes the 103.Dv PCATCH 104flag, signals are checked before and after sleeping, otherwise signals are 105not checked. 106If 107.Dv PCATCH 108is set and a signal needs to be delivered, 109.Er ERESTART 110is returned if the current system call should be restarted if 111possible, and 112.Er EINTR 113is returned if the system call should be interrupted by the signal 114(return 115.Er EINTR ) . 116.Pp 117The parameter 118.Fa wmesg 119is a string describing the sleep condition for tools like 120.Xr ps 1 . 121Due to the limited space of those programs to display arbitrary strings, 122this message should not be longer than 6 characters. 123.Pp 124The parameter 125.Fa timo 126specifies a timeout for the sleep. 127If 128.Fa timo 129is not 0, 130then the thread will sleep for at most 131.Fa timo No / Va hz 132seconds. 133If the timeout expires, 134then the sleep function will return 135.Er EWOULDBLOCK . 136.Pp 137Several of the sleep functions including 138.Fn msleep , 139.Fn msleep_spin , 140and the locking primitive sleep routines specify an additional lock 141parameter. 142The lock will be released before sleeping and reacquired 143before the sleep routine returns. 144If 145.Fa priority 146includes the 147.Dv PDROP 148flag, then 149the lock will not be reacquired before returning. 150The lock is used to ensure that a condition can be checked atomically, 151and that the current thread can be suspended without missing a 152change to the condition, or an associated wakeup. 153In addition, all of the sleep routines will fully drop the 154.Va Giant 155mutex 156(even if recursed) 157while the thread is suspended and will reacquire the 158.Va Giant 159mutex before the function returns. 160Note that the 161.Va Giant 162mutex may be specified as the lock to drop. 163In that case, however, the 164.Dv PDROP 165flag is not allowed. 166.Pp 167To avoid lost wakeups, 168either a lock should be used to protect against races, 169or a timeout should be specified to place an upper bound on the delay due 170to a lost wakeup. 171As a result, 172the 173.Fn tsleep 174function should only be invoked with a timeout of 0 when the 175.Va Giant 176mutex is held. 177.Pp 178The 179.Fn msleep 180function requires that 181.Fa mtx 182reference a default, i.e. non-spin, mutex. 183Its use is deprecated in favor of 184.Xr mtx_sleep 9 185which provides identical behavior. 186.Pp 187The 188.Fn msleep_spin 189function requires that 190.Fa mtx 191reference a spin mutex. 192The 193.Fn msleep_spin 194function does not accept a 195.Fa priority 196parameter and thus does not support changing the current thread's priority, 197the 198.Dv PDROP 199flag, 200or catching signals via the 201.Dv PCATCH 202flag. 203.Pp 204The 205.Fn pause 206function is a wrapper around 207.Fn tsleep 208that suspends execution of the current thread for the indicated timeout. 209The thread can not be awakened early by signals or calls to 210.Fn wakeup 211or 212.Fn wakeup_one . 213.Pp 214The 215.Fn wakeup_one 216function makes the first thread in the queue that is sleeping on the 217parameter 218.Fa chan 219runnable. 220This reduces the load when a large number of threads are sleeping on 221the same address, but only one of them can actually do any useful work 222when made runnable. 223.Pp 224Due to the way it works, the 225.Fn wakeup_one 226function requires that only related threads sleep on a specific 227.Fa chan 228address. 229It is the programmer's responsibility to choose a unique 230.Fa chan 231value. 232The older 233.Fn wakeup 234function did not require this, though it was never good practice 235for threads to share a 236.Fa chan 237value. 238When converting from 239.Fn wakeup 240to 241.Fn wakeup_one , 242pay particular attention to ensure that no other threads wait on the 243same 244.Fa chan . 245.Sh RETURN VALUES 246If the thread is awakened by a call to 247.Fn wakeup 248or 249.Fn wakeup_one , 250the 251.Fn msleep , 252.Fn msleep_spin , 253.Fn tsleep , 254and locking primitive sleep functions return 0. 255Otherwise, a non-zero error code is returned. 256.Sh ERRORS 257.Fn msleep , 258.Fn msleep_spin , 259.Fn tsleep , 260and the locking primitive sleep functions will fail if: 261.Bl -tag -width Er 262.It Bq Er EINTR 263The 264.Dv PCATCH 265flag was specified, a signal was caught, and the system call should be 266interrupted. 267.It Bq Er ERESTART 268The 269.Dv PCATCH 270flag was specified, a signal was caught, and the system call should be 271restarted. 272.It Bq Er EWOULDBLOCK 273A non-zero timeout was specified and the timeout expired. 274.El 275.Sh SEE ALSO 276.Xr ps 1 , 277.Xr locking 9 , 278.Xr malloc 9 , 279.Xr mi_switch 9 , 280.Xr mtx_sleep 9 , 281.Xr rw_sleep 9 , 282.Xr sx_sleep 9 283.Sh HISTORY 284The functions 285.Fn sleep 286and 287.Fn wakeup 288were present in 289.At v1 . 290They were probably also present in the preceding 291PDP-7 version of 292.Ux . 293They were the basic process synchronization model. 294.Pp 295The 296.Fn tsleep 297function appeared in 298.Bx 4.4 299and added the parameters 300.Fa wmesg 301and 302.Fa timo . 303The 304.Fn sleep 305function was removed in 306.Fx 2.2 . 307The 308.Fn wakeup_one 309function appeared in 310.Fx 2.2 . 311The 312.Fn msleep 313function appeared in 314.Fx 5.0 , 315and the 316.Fn msleep_spin 317function appeared in 318.Fx 6.2 . 319The 320.Fn pause 321function appeared in 322.Fx 7.0 . 323.Sh AUTHORS 324.An -nosplit 325This manual page was written by 326.An J\(:org Wunsch Aq joerg@FreeBSD.org . 327