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 February 19, 2013 29.Dt SLEEP 9 30.Os 31.Sh NAME 32.Nm msleep , 33.Nm msleep_sbt , 34.Nm msleep_spin , 35.Nm msleep_spin_sbt , 36.Nm pause , 37.Nm pause_sbt , 38.Nm tsleep , 39.Nm tsleep_sbt , 40.Nm wakeup 41.Nd wait for events 42.Sh SYNOPSIS 43.In sys/param.h 44.In sys/systm.h 45.In sys/proc.h 46.Ft int 47.Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" 48.Ft int 49.Fn msleep_sbt "void *chan" "struct mtx *mtx" "int priority" \ 50"const char *wmesg" "sbintime_t sbt" "sbintime_t pr" "int flags" 51.Ft int 52.Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" 53.Ft int 54.Fn msleep_spin_sbt "void *chan" "struct mtx *mtx" "const char *wmesg" \ 55"sbintime_t sbt" "sbintime_t pr" "int flags" 56.Ft void 57.Fn pause "const char *wmesg" "int timo" 58.Ft void 59.Fn pause_sbt "const char *wmesg" "sbintime_t sbt" "sbintime_t pr" \ 60 "int flags" 61.Ft int 62.Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo" 63.Ft int 64.Fn tsleep_sbt "void *chan" "int priority" "const char *wmesg" \ 65"sbintime_t sbt" "sbintime_t pr" "int flags" 66.Ft void 67.Fn wakeup "void *chan" 68.Ft void 69.Fn wakeup_one "void *chan" 70.Sh DESCRIPTION 71The functions 72.Fn tsleep , 73.Fn msleep , 74.Fn msleep_spin , 75.Fn pause , 76.Fn wakeup , 77and 78.Fn wakeup_one 79handle event-based thread blocking. 80If a thread must wait for an 81external event, it is put to sleep by 82.Fn tsleep , 83.Fn msleep , 84.Fn msleep_spin , 85or 86.Fn pause . 87Threads may also wait using one of the locking primitive sleep routines 88.Xr mtx_sleep 9 , 89.Xr rw_sleep 9 , 90or 91.Xr sx_sleep 9 . 92.Pp 93The parameter 94.Fa chan 95is an arbitrary address that uniquely identifies the event on which 96the thread is being put to sleep. 97All threads sleeping on a single 98.Fa chan 99are woken up later by 100.Fn wakeup , 101often called from inside an interrupt routine, to indicate that the 102resource the thread was blocking on is available now. 103.Pp 104The parameter 105.Fa priority 106specifies a new priority for the thread as well as some optional flags. 107If the new priority is not 0, 108then the thread will be made 109runnable with the specified 110.Fa priority 111when it resumes. 112.Dv PZERO 113should never be used, as it is for compatibility only. 114A new priority of 0 means to use the thread's current priority when 115it is made runnable again. 116.Pp 117If 118.Fa priority 119includes the 120.Dv PCATCH 121flag, pending signals are allowed to interrupt the sleep, otherwise 122pending signals are ignored during the sleep. 123If 124.Dv PCATCH 125is set and a signal becomes pending, 126.Er ERESTART 127is returned if the current system call should be restarted if 128possible, and 129.Er EINTR 130is returned if the system call should be interrupted by the signal 131(return 132.Er EINTR ) . 133If the 134.Dv PBDRY 135flag is specified in addition to 136.Dv PCATCH , 137then the sleeping thread is not stopped when 138.Dv SIGSTOP 139becomes pending 140or some other stop action occurs while it is sleeping. 141Instead, it is woken up, with the assumption 142that the stop will occur on reaching a stop 143point when returning to usermode. 144The flag should be used when the sleeping thread owns resources, for instance 145vnode locks, that should be released in a timely fashion. 146.Pp 147The parameter 148.Fa wmesg 149is a string describing the sleep condition for tools like 150.Xr ps 1 . 151Due to the limited space of those programs to display arbitrary strings, 152this message should not be longer than 6 characters. 153.Pp 154The parameter 155.Fa timo 156specifies a timeout for the sleep. 157If 158.Fa timo 159is not 0, 160then the thread will sleep for at most 161.Fa timo No / Va hz 162seconds. 163If the timeout expires, 164then the sleep function will return 165.Er EWOULDBLOCK . 166.Pp 167.Fn msleep_sbt , 168.Fn msleep_spin_sbt , 169.Fn pause_sbt 170and 171.Fn tsleep_sbt 172functions take 173.Fa sbt 174parameter instead of 175.Fa timo . 176It allows the caller to specify relative or absolute wakeup time with higher resolution 177in form of 178.Vt sbintime_t . 179The parameter 180.Fa pr 181allows the caller to specify wanted absolute event precision. 182The parameter 183.Fa flags 184allows the caller to pass additional 185.Fn callout_reset_sbt 186flags. 187.Pp 188Several of the sleep functions including 189.Fn msleep , 190.Fn msleep_spin , 191and the locking primitive sleep routines specify an additional lock 192parameter. 193The lock will be released before sleeping and reacquired 194before the sleep routine returns. 195If 196.Fa priority 197includes the 198.Dv PDROP 199flag, then 200the lock will not be reacquired before returning. 201The lock is used to ensure that a condition can be checked atomically, 202and that the current thread can be suspended without missing a 203change to the condition, or an associated wakeup. 204In addition, all of the sleep routines will fully drop the 205.Va Giant 206mutex 207(even if recursed) 208while the thread is suspended and will reacquire the 209.Va Giant 210mutex before the function returns. 211Note that the 212.Va Giant 213mutex may be specified as the lock to drop. 214In that case, however, the 215.Dv PDROP 216flag is not allowed. 217.Pp 218To avoid lost wakeups, 219either a lock should be used to protect against races, 220or a timeout should be specified to place an upper bound on the delay due 221to a lost wakeup. 222As a result, 223the 224.Fn tsleep 225function should only be invoked with a timeout of 0 when the 226.Va Giant 227mutex is held. 228.Pp 229The 230.Fn msleep 231function requires that 232.Fa mtx 233reference a default, i.e. non-spin, mutex. 234Its use is deprecated in favor of 235.Xr mtx_sleep 9 236which provides identical behavior. 237.Pp 238The 239.Fn msleep_spin 240function requires that 241.Fa mtx 242reference a spin mutex. 243The 244.Fn msleep_spin 245function does not accept a 246.Fa priority 247parameter and thus does not support changing the current thread's priority, 248the 249.Dv PDROP 250flag, 251or catching signals via the 252.Dv PCATCH 253flag. 254.Pp 255The 256.Fn pause 257function is a wrapper around 258.Fn tsleep 259that suspends execution of the current thread for the indicated timeout. 260The thread can not be awakened early by signals or calls to 261.Fn wakeup 262or 263.Fn wakeup_one . 264.Pp 265The 266.Fn wakeup_one 267function makes the first thread in the queue that is sleeping on the 268parameter 269.Fa chan 270runnable. 271This reduces the load when a large number of threads are sleeping on 272the same address, but only one of them can actually do any useful work 273when made runnable. 274.Pp 275Due to the way it works, the 276.Fn wakeup_one 277function requires that only related threads sleep on a specific 278.Fa chan 279address. 280It is the programmer's responsibility to choose a unique 281.Fa chan 282value. 283The older 284.Fn wakeup 285function did not require this, though it was never good practice 286for threads to share a 287.Fa chan 288value. 289When converting from 290.Fn wakeup 291to 292.Fn wakeup_one , 293pay particular attention to ensure that no other threads wait on the 294same 295.Fa chan . 296.Sh RETURN VALUES 297When awakened by a call to 298.Fn wakeup 299or 300.Fn wakeup_one , 301if a signal is pending and 302.Dv PCATCH 303is specified, 304a non-zero error code is returned. 305If the thread is awakened by a call to 306.Fn wakeup 307or 308.Fn wakeup_one , 309the 310.Fn msleep , 311.Fn msleep_spin , 312.Fn tsleep , 313and locking primitive sleep functions return 0. 314Otherwise, a non-zero error code is returned. 315.Sh ERRORS 316.Fn msleep , 317.Fn msleep_spin , 318.Fn tsleep , 319and the locking primitive sleep functions will fail if: 320.Bl -tag -width Er 321.It Bq Er EINTR 322The 323.Dv PCATCH 324flag was specified, a signal was caught, and the system call should be 325interrupted. 326.It Bq Er ERESTART 327The 328.Dv PCATCH 329flag was specified, a signal was caught, and the system call should be 330restarted. 331.It Bq Er EWOULDBLOCK 332A non-zero timeout was specified and the timeout expired. 333.El 334.Sh SEE ALSO 335.Xr ps 1 , 336.Xr locking 9 , 337.Xr malloc 9 , 338.Xr mi_switch 9 , 339.Xr mtx_sleep 9 , 340.Xr rw_sleep 9 , 341.Xr sx_sleep 9 , 342.Xr timeout 9 343.Sh HISTORY 344The functions 345.Fn sleep 346and 347.Fn wakeup 348were present in 349.At v1 . 350They were probably also present in the preceding 351PDP-7 version of 352.Ux . 353They were the basic process synchronization model. 354.Pp 355The 356.Fn tsleep 357function appeared in 358.Bx 4.4 359and added the parameters 360.Fa wmesg 361and 362.Fa timo . 363The 364.Fn sleep 365function was removed in 366.Fx 2.2 . 367The 368.Fn wakeup_one 369function appeared in 370.Fx 2.2 . 371The 372.Fn msleep 373function appeared in 374.Fx 5.0 , 375and the 376.Fn msleep_spin 377function appeared in 378.Fx 6.2 . 379The 380.Fn pause 381function appeared in 382.Fx 7.0 . 383.Sh AUTHORS 384.An -nosplit 385This manual page was written by 386.An J\(:org Wunsch Aq joerg@FreeBSD.org . 387