share/man/man9/sleep.9

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