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 December 12, 2009 29.Dt SLEEP 9 30.Os 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. 100.Pp 101If 102.Fa priority 103includes the 104.Dv PCATCH 105flag, pending 106signals are checked before and after sleeping, otherwise signals are 107not checked. 108If 109.Dv PCATCH 110is set and a signal needs to be delivered, 111.Er ERESTART 112is returned if the current system call should be restarted if 113possible, and 114.Er EINTR 115is returned if the system call should be interrupted by the signal 116(return 117.Er EINTR ) . 118If the 119.Dv PBDRY 120flag is specified in addition to 121.Dv PCATCH , 122then the sleeping thread is not stopped upon delivery of 123.Dv SIGSTOP 124or other stop action while it is sleeping. 125Instead, it is woken up, with the assumption 126that the stop will occur on reaching a stop 127point when returning to usermode. 128The flag should be used when the sleeping thread owns resources, for instance 129vnode locks, that should be released in a timely fashion. 130.Pp 131The parameter 132.Fa wmesg 133is a string describing the sleep condition for tools like 134.Xr ps 1 . 135Due to the limited space of those programs to display arbitrary strings, 136this message should not be longer than 6 characters. 137.Pp 138The parameter 139.Fa timo 140specifies a timeout for the sleep. 141If 142.Fa timo 143is not 0, 144then the thread will sleep for at most 145.Fa timo No / Va hz 146seconds. 147If the timeout expires, 148then the sleep function will return 149.Er EWOULDBLOCK . 150.Pp 151Several of the sleep functions including 152.Fn msleep , 153.Fn msleep_spin , 154and the locking primitive sleep routines specify an additional lock 155parameter. 156The lock will be released before sleeping and reacquired 157before the sleep routine returns. 158If 159.Fa priority 160includes the 161.Dv PDROP 162flag, then 163the lock will not be reacquired before returning. 164The lock is used to ensure that a condition can be checked atomically, 165and that the current thread can be suspended without missing a 166change to the condition, or an associated wakeup. 167In addition, all of the sleep routines will fully drop the 168.Va Giant 169mutex 170(even if recursed) 171while the thread is suspended and will reacquire the 172.Va Giant 173mutex before the function returns. 174Note that the 175.Va Giant 176mutex may be specified as the lock to drop. 177In that case, however, the 178.Dv PDROP 179flag is not allowed. 180.Pp 181To avoid lost wakeups, 182either a lock should be used to protect against races, 183or a timeout should be specified to place an upper bound on the delay due 184to a lost wakeup. 185As a result, 186the 187.Fn tsleep 188function should only be invoked with a timeout of 0 when the 189.Va Giant 190mutex is held. 191.Pp 192The 193.Fn msleep 194function requires that 195.Fa mtx 196reference a default, i.e. non-spin, mutex. 197Its use is deprecated in favor of 198.Xr mtx_sleep 9 199which provides identical behavior. 200.Pp 201The 202.Fn msleep_spin 203function requires that 204.Fa mtx 205reference a spin mutex. 206The 207.Fn msleep_spin 208function does not accept a 209.Fa priority 210parameter and thus does not support changing the current thread's priority, 211the 212.Dv PDROP 213flag, 214or catching signals via the 215.Dv PCATCH 216flag. 217.Pp 218The 219.Fn pause 220function is a wrapper around 221.Fn tsleep 222that suspends execution of the current thread for the indicated timeout. 223The thread can not be awakened early by signals or calls to 224.Fn wakeup 225or 226.Fn wakeup_one . 227.Pp 228The 229.Fn wakeup_one 230function makes the first thread in the queue that is sleeping on the 231parameter 232.Fa chan 233runnable. 234This reduces the load when a large number of threads are sleeping on 235the same address, but only one of them can actually do any useful work 236when made runnable. 237.Pp 238Due to the way it works, the 239.Fn wakeup_one 240function requires that only related threads sleep on a specific 241.Fa chan 242address. 243It is the programmer's responsibility to choose a unique 244.Fa chan 245value. 246The older 247.Fn wakeup 248function did not require this, though it was never good practice 249for threads to share a 250.Fa chan 251value. 252When converting from 253.Fn wakeup 254to 255.Fn wakeup_one , 256pay particular attention to ensure that no other threads wait on the 257same 258.Fa chan . 259.Sh RETURN VALUES 260When awakened by a call to 261.Fn wakeup 262or 263.Fn wakeup_one , 264if a signal is pending and 265.Dv PCATCH 266is specified, 267a non-zero error code is returned. 268If the thread is awakened by a call to 269.Fn wakeup 270or 271.Fn wakeup_one , 272the 273.Fn msleep , 274.Fn msleep_spin , 275.Fn tsleep , 276and locking primitive sleep functions return 0. 277Otherwise, a non-zero error code is returned. 278.Sh ERRORS 279.Fn msleep , 280.Fn msleep_spin , 281.Fn tsleep , 282and the locking primitive sleep functions will fail if: 283.Bl -tag -width Er 284.It Bq Er EINTR 285The 286.Dv PCATCH 287flag was specified, a signal was caught, and the system call should be 288interrupted. 289.It Bq Er ERESTART 290The 291.Dv PCATCH 292flag was specified, a signal was caught, and the system call should be 293restarted. 294.It Bq Er EWOULDBLOCK 295A non-zero timeout was specified and the timeout expired. 296.El 297.Sh SEE ALSO 298.Xr ps 1 , 299.Xr locking 9 , 300.Xr malloc 9 , 301.Xr mi_switch 9 , 302.Xr mtx_sleep 9 , 303.Xr rw_sleep 9 , 304.Xr sx_sleep 9 305.Sh HISTORY 306The functions 307.Fn sleep 308and 309.Fn wakeup 310were present in 311.At v1 . 312They were probably also present in the preceding 313PDP-7 version of 314.Ux . 315They were the basic process synchronization model. 316.Pp 317The 318.Fn tsleep 319function appeared in 320.Bx 4.4 321and added the parameters 322.Fa wmesg 323and 324.Fa timo . 325The 326.Fn sleep 327function was removed in 328.Fx 2.2 . 329The 330.Fn wakeup_one 331function appeared in 332.Fx 2.2 . 333The 334.Fn msleep 335function appeared in 336.Fx 5.0 , 337and the 338.Fn msleep_spin 339function appeared in 340.Fx 6.2 . 341The 342.Fn pause 343function appeared in 344.Fx 7.0 . 345.Sh AUTHORS 346.An -nosplit 347This manual page was written by 348.An J\(:org Wunsch Aq joerg@FreeBSD.org . 349