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