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