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