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