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 258If the thread is awakened by a call to 259.Fn wakeup 260or 261.Fn wakeup_one , 262the 263.Fn msleep , 264.Fn msleep_spin , 265.Fn tsleep , 266and locking primitive sleep functions return 0. 267Otherwise, a non-zero error code is returned. 268.Sh ERRORS 269.Fn msleep , 270.Fn msleep_spin , 271.Fn tsleep , 272and the locking primitive sleep functions will fail if: 273.Bl -tag -width Er 274.It Bq Er EINTR 275The 276.Dv PCATCH 277flag was specified, a signal was caught, and the system call should be 278interrupted. 279.It Bq Er ERESTART 280The 281.Dv PCATCH 282flag was specified, a signal was caught, and the system call should be 283restarted. 284.It Bq Er EWOULDBLOCK 285A non-zero timeout was specified and the timeout expired. 286.El 287.Sh SEE ALSO 288.Xr ps 1 , 289.Xr locking 9 , 290.Xr malloc 9 , 291.Xr mi_switch 9 , 292.Xr mtx_sleep 9 , 293.Xr rw_sleep 9 , 294.Xr sx_sleep 9 295.Sh HISTORY 296The functions 297.Fn sleep 298and 299.Fn wakeup 300were present in 301.At v1 . 302They were probably also present in the preceding 303PDP-7 version of 304.Ux . 305They were the basic process synchronization model. 306.Pp 307The 308.Fn tsleep 309function appeared in 310.Bx 4.4 311and added the parameters 312.Fa wmesg 313and 314.Fa timo . 315The 316.Fn sleep 317function was removed in 318.Fx 2.2 . 319The 320.Fn wakeup_one 321function appeared in 322.Fx 2.2 . 323The 324.Fn msleep 325function appeared in 326.Fx 5.0 , 327and the 328.Fn msleep_spin 329function appeared in 330.Fx 6.2 . 331The 332.Fn pause 333function appeared in 334.Fx 7.0 . 335.Sh AUTHORS 336.An -nosplit 337This manual page was written by 338.An J\(:org Wunsch Aq joerg@FreeBSD.org . 339