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