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