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 17, 2006
  29 .Os
  30 .Dt SLEEP 9
  31 .Sh NAME
  32 .Nm msleep ,
  33 .Nm msleep_spin ,
  34 .Nm tsleep ,
  35 .Nm wakeup
  36 .Nd wait for events
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/systm.h
  40 .In sys/proc.h
  41 .Ft int
  42 .Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo"
  43 .Ft int
  44 .Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo"
  45 .Ft int
  46 .Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo"
  47 .Ft void
  48 .Fn wakeup "void *chan"
  49 .Ft void
  50 .Fn wakeup_one "void *chan"
  51 .Sh DESCRIPTION
  52 The functions
  53 .Fn tsleep ,
  54 .Fn msleep ,
  55 .Fn msleep_spin ,
  56 .Fn wakeup ,
  57 and
  58 .Fn wakeup_one
  59 handle event-based thread blocking.
  60 If a thread must wait for an
  61 external event, it is put to sleep by
  62 .Fn tsleep ,
  63 .Fn msleep ,
  64 or
  65 .Fn msleep_spin .
  66 The parameter
  67 .Fa chan
  68 is an arbitrary address that uniquely identifies the event on which
  69 the thread is being asleep.
  70 All threads sleeping on a single
  71 .Fa chan
  72 are woken up later by
  73 .Fn wakeup ,
  74 often called from inside an interrupt routine, to indicate that the
  75 resource the thread was blocking on is available now.
  76 .Pp
  77 The parameter
  78 .Fa wmesg
  79 is a string describing the sleep condition for tools like
  80 .Xr ps 1 .
  81 Due to the limited space of those programs to display arbitrary strings,
  82 this message should not be longer than 6 characters.
  83 .Pp
  84 The
  85 .Fn wakeup_one
  86 function is used to make the first thread in the queue that is
  87 sleeping on the parameter
  88 .Fa chan
  89 runnable.
  90 This can prevent the system from becoming saturated
  91 when a large number of threads are sleeping on the same address,
  92 but only one of them can actually do any useful work when made
  93 runnable.
  94 .Pp
  95 The
  96 .Fn msleep
  97 function is the general sleep call.
  98 It suspends the current thread until a wakeup is
  99 performed on the specified identifier.
 100 The
 101 .Fa mtx
 102 parameter is a mutex which will be released before sleeping and reacquired
 103 before
 104 .Fn msleep
 105 returns.
 106 If
 107 .Fa priority
 108 includes the
 109 .Dv PDROP
 110 flag, the
 111 .Fa mtx
 112 parameter will not be reacquired before returning.
 113 The mutex is used to ensure that a condition can be checked atomically,
 114 and that the current thread can be suspended without missing a
 115 change to the condition, or an associated wakeup.
 116 If
 117 .Fa priority
 118 is not 0,
 119 then the thread will be made
 120 runnable with the specified
 121 .Fa priority
 122 when it resumes.
 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
 130 .Va Giant
 131 lock is not held and
 132 .Fa mtx
 133 is
 134 .Dv NULL ,
 135 then
 136 .Fa timo
 137 must be non-zero.
 138 If
 139 .Fa priority
 140 includes the
 141 .Dv PCATCH
 142 flag, signals are checked before and after sleeping, otherwise signals are
 143 not checked.
 144 The
 145 .Fn msleep
 146 function returns 0 if awakened,
 147 .Er EWOULDBLOCK
 148 if the timeout expires.
 149 If
 150 .Dv PCATCH
 151 is set and a signal needs to be delivered,
 152 .Er ERESTART
 153 is returned if the current system call should be restarted if
 154 possible, and
 155 .Er EINTR
 156 is returned if the system call should be interrupted by the signal
 157 (return
 158 .Er EINTR ) .
 159 .Pp
 160 The
 161 .Fn tsleep
 162 function is a variation on
 163 .Fn msleep .
 164 It is identical to invoking
 165 .Fn msleep
 166 with a
 167 .Dv NULL
 168 .Fa mtx
 169 parameter.
 170 .Pp
 171 The
 172 .Fn msleep_spin
 173 function is another variation on
 174 .Fn msleep .
 175 This function accepts a spin mutex rather than a default mutex for its
 176 .Fa mtx
 177 parameter.
 178 It is also more limited in that it does not accept a
 179 .Fa priority
 180 parameter.
 181 Thus, it will not change the priority of a sleeping thread,
 182 and it does not support the
 183 .Dv PDROP
 184 and
 185 .Dv PCATCH
 186 flags.
 187 .Sh RETURN VALUES
 188 See above.
 189 .Sh SEE ALSO
 190 .Xr ps 1 ,
 191 .Xr malloc 9 ,
 192 .Xr mi_switch 9
 193 .Sh HISTORY
 194 The sleep/wakeup thread synchronization mechanism is very old.
 195 It
 196 appeared in a very early version of
 197 .Ux .
 198 .Pp
 199 The
 200 .Fn tsleep
 201 function appeared in
 202 .Bx 4.4 .
 203 The
 204 .Fn wakeup_one
 205 function appeared in
 206 .Fx 2.2 .
 207 The
 208 .Fn msleep
 209 function appeared in
 210 .Fx 5.0 ,
 211 and the
 212 .Fn msleep_spin
 213 function appeared in
 214 .Fx 7.0 .
 215 .Pp
 216 The
 217 .Fn sleep
 218 function used to be the traditional form.
 219 It did not let you specify a timeout or a
 220 .Fa wmesg ,
 221 hence it was discontinued.
 222 .Sh AUTHORS
 223 .An -nosplit
 224 This manual page was written by
 225 .An J\(:org Wunsch Aq joerg@FreeBSD.org .