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