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