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 April 4, 2008
  29 .Os
  30 .Dt SLEEP 9
  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 If
 101 .Fa priority
 102 includes the
 103 .Dv PCATCH
 104 flag, signals are checked before and after sleeping, otherwise signals are
 105 not checked.
 106 If
 107 .Dv PCATCH
 108 is set and a signal needs to be delivered,
 109 .Er ERESTART
 110 is returned if the current system call should be restarted if
 111 possible, and
 112 .Er EINTR
 113 is returned if the system call should be interrupted by the signal
 114 (return
 115 .Er EINTR ) .
 116 .Pp
 117 The parameter
 118 .Fa wmesg
 119 is a string describing the sleep condition for tools like
 120 .Xr ps 1 .
 121 Due to the limited space of those programs to display arbitrary strings,
 122 this message should not be longer than 6 characters.
 123 .Pp
 124 The parameter
 125 .Fa timo
 126 specifies a timeout for the sleep.
 127 If
 128 .Fa timo
 129 is not 0,
 130 then the thread will sleep for at most
 131 .Fa timo No / Va hz
 132 seconds.
 133 If the timeout expires,
 134 then the sleep function will return
 135 .Er EWOULDBLOCK .
 136 .Pp
 137 Several of the sleep functions including
 138 .Fn msleep ,
 139 .Fn msleep_spin ,
 140 and the locking primitive sleep routines specify an additional lock
 141 parameter.
 142 The lock will be released before sleeping and reacquired
 143 before the sleep routine returns.
 144 If
 145 .Fa priority
 146 includes the
 147 .Dv PDROP
 148 flag, then
 149 the lock will not be reacquired before returning.
 150 The lock is used to ensure that a condition can be checked atomically,
 151 and that the current thread can be suspended without missing a
 152 change to the condition, or an associated wakeup.
 153 In addition, all of the sleep routines will fully drop the
 154 .Va Giant
 155 mutex
 156 (even if recursed)
 157 while the thread is suspended and will reacquire the
 158 .Va Giant
 159 mutex before the function returns.
 160 Note that the
 161 .Va Giant
 162 mutex may be specified as the lock to drop.
 163 In that case, however, the
 164 .Dv PDROP
 165 flag is not allowed.
 166 .Pp
 167 To avoid lost wakeups,
 168 either a lock should be used to protect against races,
 169 or a timeout should be specified to place an upper bound on the delay due
 170 to a lost wakeup.
 171 As a result,
 172 the
 173 .Fn tsleep
 174 function should only be invoked with a timeout of 0 when the
 175 .Va Giant
 176 mutex is held.
 177 .Pp
 178 The
 179 .Fn msleep
 180 function requires that
 181 .Fa mtx
 182 reference a default, i.e. non-spin, mutex.
 183 Its use is deprecated in favor of
 184 .Xr mtx_sleep 9
 185 which provides identical behavior.
 186 .Pp
 187 The
 188 .Fn msleep_spin
 189 function requires that
 190 .Fa mtx
 191 reference a spin mutex.
 192 The
 193 .Fn msleep_spin
 194 function does not accept a
 195 .Fa priority
 196 parameter and thus does not support changing the current thread's priority,
 197 the
 198 .Dv PDROP
 199 flag,
 200 or catching signals via the
 201 .Dv PCATCH
 202 flag.
 203 .Pp
 204 The
 205 .Fn pause
 206 function is a wrapper around
 207 .Fn tsleep
 208 that suspends execution of the current thread for the indicated timeout.
 209 The thread can not be awakened early by signals or calls to
 210 .Fn wakeup
 211 or
 212 .Fn wakeup_one .
 213 .Pp
 214 The
 215 .Fn wakeup_one
 216 function makes the first thread in the queue that is sleeping on the
 217 parameter
 218 .Fa chan
 219 runnable.
 220 This reduces the load when a large number of threads are sleeping on
 221 the same address, but only one of them can actually do any useful work
 222 when made runnable.
 223 .Pp
 224 Due to the way it works, the
 225 .Fn wakeup_one
 226 function requires that only related threads sleep on a specific
 227 .Fa chan
 228 address.
 229 It is the programmer's responsibility to choose a unique
 230 .Fa chan
 231 value.
 232 The older
 233 .Fn wakeup
 234 function did not require this, though it was never good practice
 235 for threads to share a
 236 .Fa chan
 237 value.
 238 When converting from
 239 .Fn wakeup
 240 to
 241 .Fn wakeup_one ,
 242 pay particular attention to ensure that no other threads wait on the
 243 same
 244 .Fa chan .
 245 .Sh RETURN VALUES
 246 If the thread is awakened by a call to
 247 .Fn wakeup
 248 or
 249 .Fn wakeup_one ,
 250 the
 251 .Fn msleep ,
 252 .Fn msleep_spin ,
 253 .Fn tsleep ,
 254 and locking primitive sleep functions return 0.
 255 Otherwise, a non-zero error code is returned.
 256 .Sh ERRORS
 257 .Fn msleep ,
 258 .Fn msleep_spin ,
 259 .Fn tsleep ,
 260 and the locking primitive sleep functions will fail if:
 261 .Bl -tag -width Er
 262 .It Bq Er EINTR
 263 The
 264 .Dv PCATCH
 265 flag was specified, a signal was caught, and the system call should be
 266 interrupted.
 267 .It Bq Er ERESTART
 268 The
 269 .Dv PCATCH
 270 flag was specified, a signal was caught, and the system call should be
 271 restarted.
 272 .It Bq Er EWOULDBLOCK
 273 A non-zero timeout was specified and the timeout expired.
 274 .El
 275 .Sh SEE ALSO
 276 .Xr ps 1 ,
 277 .Xr locking 9 ,
 278 .Xr malloc 9 ,
 279 .Xr mi_switch 9 ,
 280 .Xr mtx_sleep 9 ,
 281 .Xr rw_sleep 9 ,
 282 .Xr sx_sleep 9
 283 .Sh HISTORY
 284 The functions
 285 .Fn sleep
 286 and
 287 .Fn wakeup
 288 were present in
 289 .At v1 .
 290 They were probably also present in the preceding
 291 PDP-7 version of
 292 .Ux .
 293 They were the basic process synchronization model.
 294 .Pp
 295 The
 296 .Fn tsleep
 297 function appeared in
 298 .Bx 4.4
 299 and added the parameters
 300 .Fa wmesg
 301 and
 302 .Fa timo .
 303 The
 304 .Fn sleep
 305 function was removed in
 306 .Fx 2.2 .
 307 The
 308 .Fn wakeup_one
 309 function appeared in
 310 .Fx 2.2 .
 311 The
 312 .Fn msleep
 313 function appeared in
 314 .Fx 5.0 ,
 315 and the
 316 .Fn msleep_spin
 317 function appeared in
 318 .Fx 6.2 .
 319 The
 320 .Fn pause
 321 function appeared in
 322 .Fx 7.0 .
 323 .Sh AUTHORS
 324 .An -nosplit
 325 This manual page was written by
 326 .An J\(:org Wunsch Aq joerg@FreeBSD.org .