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