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