share/man/man9/sleep.9

   1 .\"
   2 .\" Copyright (c) 2004,2010 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to The DragonFly Project
   5 .\" by Hiten Pandya <hmp@backplane.com>.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in
  15 .\"    the documentation and/or other materials provided with the
  16 .\"    distribution.
  17 .\" 3. Neither the name of The DragonFly Project nor the names of its
  18 .\"    contributors may be used to endorse or promote products derived
  19 .\"    from this software without specific, prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" Copyright (c) 1996 Joerg Wunsch
  35 .\"
  36 .\" All rights reserved.
  37 .\"
  38 .\" Redistribution and use in source and binary forms, with or without
  39 .\" modification, are permitted provided that the following conditions
  40 .\" are met:
  41 .\" 1. Redistributions of source code must retain the above copyright
  42 .\"    notice, this list of conditions and the following disclaimer.
  43 .\" 2. Redistributions in binary form must reproduce the above copyright
  44 .\"    notice, this list of conditions and the following disclaimer in the
  45 .\"    documentation and/or other materials provided with the distribution.
  46 .\"
  47 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  48 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  49 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  50 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  51 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  52 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  53 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  54 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  55 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  56 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  57 .\"
  58 .\" $FreeBSD: src/share/man/man9/sleep.9,v 1.18.2.5 2001/12/17 11:30:19 ru Exp $
  59 .\"
  60 .Dd April 12, 2010
  61 .Dt SLEEP 9
  62 .Os
  63 .Sh NAME
  64 .Nm tsleep ,
  65 .Nm ssleep ,
  66 .Nm lksleep ,
  67 .Nm mtxsleep ,
  68 .Nm zsleep ,
  69 .Nm tsleep_interlock ,
  70 .Nm wakeup ,
  71 .Nm wakeup_one
  72 .Nd wait/sleep/block for events
  73 .Sh SYNOPSIS
  74 .In sys/param.h
  75 .In sys/serialize.h
  76 .In sys/systm.h
  77 .In sys/proc.h
  78 .Ft int
  79 .Fn tsleep "void *ident" "int flags" "const char *wmesg" "int timo"
  80 .Ft int
  81 .Fn ssleep "void *ident" "struct spinlock *spin" "int flags" "const char *wmesg" "int timo"
  82 .Ft int
  83 .Fn lksleep "void *ident" "struct lock *lock" "int flags" "const char *wmesg" "int timo"
  84 .Ft int
  85 .Fn mtxsleep "void *ident" "struct mtx *mtx" "int flags" "const char *wmesg" "int timo"
  86 .Ft int
  87 .Fn zsleep "void *ident" "struct lwkt_serialize *slz" "int flags" "const char *wmesg" "int timo"
  88 .Ft void
  89 .Fn tsleep_interlock "void *ident" "int flags"
  90 .Ft void
  91 .Fn wakeup "void *ident"
  92 .Ft void
  93 .Fn wakeup_one "void *ident"
  94 .Sh DESCRIPTION
  95 The functions
  96 .Fn tsleep ,
  97 .Fn ssleep ,
  98 .Fn lksleep ,
  99 .Fn mtxsleep ,
 100 .Fn zsleep ,
 101 and
 102 .Fn wakeup
 103 handle event-based process blocking.
 104 If a process must wait for an
 105 external event, it is put on sleep by
 106 .Fn tsleep ,
 107 .Fn ssleep ,
 108 .Fn lksleep ,
 109 .Fn mtxsleep ,
 110 or
 111 .Fn zsleep .
 112 .Pp
 113 The parameter
 114 .Ar ident
 115 is an arbitrary address that uniquely identifies the event on which
 116 the process is being asleep.
 117 All processes sleeping on a single
 118 .Fa ident
 119 are woken up later by
 120 .Fn wakeup ,
 121 often called from inside an interrupt routine, to indicate that the
 122 resource the process/thread was blocking on is available now.
 123 .Pp
 124 The parameter
 125 .Fa wmesg
 126 is a string describing the sleep condition for tools like
 127 .Xr ps 1 .
 128 Due to the limited space of those programs to display arbitrary strings,
 129 this message should not be longer than 6 characters.
 130 .Pp
 131 The
 132 .Fn tsleep
 133 function is general in its use and suspends the current process/thread until a
 134 wakeup is performed on the specified identifier.
 135 The process/thread will then be made runnable.
 136 The process/thread will sleep at most
 137 .Fa timo
 138 \&/ hz seconds (0 means no timeout).
 139 If
 140 .Fa flags
 141 contains the
 142 .Dv PCATCH
 143 flag, signals are checked before and after sleeping, else signals are
 144 ignored.
 145 .Pp
 146 .Fn Tsleep_interlock
 147 is similar to
 148 .Fn tsleep ,
 149 in that it queues a thread on a sleep queue, but it does not actually put the
 150 thread to sleep.
 151 This allows coupling tsleep with higher-level synchronization primitives.
 152 The pattern is:
 153 .Bd -literal
 154 (acquire high level synchronization primitive)
 155 (test condition of interest)
 156 tsleep_interlock(ident, flags)
 157 (release high level synchronization primitive)
 158 tsleep(..., PINTERLOCK)
 159 .Ed
 160 .Pp
 161 For example, to implement
 162 .Fn ssleep :
 163 .Bd -literal
 164 spin_lock_wr(&important_lock);
 165 if (important_condition == 0) {
 166         tsleep_interlock(ident, flags);
 167         spin_unlock_wr(&important_lock);
 168         tsleep(..., PINTERLOCK);
 169 }
 170 .Ed
 171 .Pp
 172 The
 173 .Fn ssleep
 174 function works like
 175 .Fn tsleep
 176 while at the same time releasing the exclusive (write) spinlock
 177 .Fa spin
 178 before sleeping and reacquiring it before
 179 .Fn ssleep
 180 returns.
 181 This is an atomic operation, which guarantees that a
 182 .Fn wakeup
 183 interlocked by
 184 .Fa spin
 185 will not be missed.
 186 .Pp
 187 The
 188 .Fn lksleep
 189 function works like
 190 .Fn tsleep
 191 while at the same time releasing the exclusive lockmgr lock
 192 .Fa lock
 193 before sleeping and reacquiring it before
 194 .Fn lksleep
 195 returns.
 196 This is an atomic operation, which guarantees that a
 197 .Fn wakeup
 198 interlocked by
 199 .Fa lock
 200 will not be missed.
 201 .Pp
 202 The
 203 .Fn mtxsleep
 204 function works like
 205 .Fn tsleep
 206 while at the same time atomically releasing the mutex
 207 .Fa mtx
 208 before sleeping and reacquiring it in exclusive state before
 209 .Fn mtxsleep
 210 returns.
 211 .Pp
 212 The
 213 .Fn zsleep
 214 function works like
 215 .Fn tsleep
 216 while at the same time releasing the serializer
 217 .Fa slz
 218 before sleeping and reacquiring it before
 219 .Fn zsleep
 220 returns.
 221 This is an atomic operation, which guarantees that a
 222 .Fn wakeup
 223 interlocked by
 224 .Fa slz
 225 will not be missed.
 226 .Pp
 227 The
 228 .Fn wakeup_one
 229 function is used to make the first process/thread in the queue that is
 230 sleeping on the parameter
 231 .Fa ident
 232 runnable.
 233 This can prevent the system from becoming saturated
 234 when a large number of processes/threads are sleeping on the same address,
 235 but only one of them can actually do any useful work when made
 236 runnable.
 237 .Sh IMPLEMENTATION NOTES
 238 Unlike
 239 .Fx ,
 240 the
 241 .Fn tsleep
 242 function in
 243 .Dx
 244 ignores priority information because it is not required by the
 245 .Tn LWKT
 246 subsystem.
 247 Sleeps without the
 248 .Dv LWP_SINTR
 249 flag set are assumed to be disk-waits, otherwise they are
 250 normal sleeps.
 251 .Sh RETURN VALUES
 252 The
 253 .Fn tsleep
 254 function returns
 255 .Li 0
 256 if awakened, otherwise an appropriate error code is returned.
 257 .Sh FILES
 258 The various sleep functions are in
 259 .Pa /sys/kern/kern_synch.c .
 260 .Sh ERRORS
 261 .Bl -tag -width Er
 262 .It Bq Er EWOULDBLOCK
 263 The timeout expired.
 264 .It Bq Er ERESTART
 265 A signal needs to be delivered and the system call should
 266 be restarted if possible.
 267 This only happens if
 268 .Dv PCATCH
 269 was set in
 270 .Fa flags .
 271 .It Bq Er EINTR
 272 The system call needs to be interrupted by the signal.
 273 This only happens if
 274 .Dv PCATCH
 275 was set in
 276 .Fa flags .
 277 .El
 278 .Sh SEE ALSO
 279 .Xr ps 1 ,
 280 .Xr kmalloc 9 ,
 281 .Xr serializer 9
 282 .Sh HISTORY
 283 The sleep/wakeup process synchronization mechanism is very old.
 284 It appeared in a very early version of Unix.
 285 .Pp
 286 .Fn tsleep
 287 appeared in
 288 .Bx 4.4 .
 289 .Pp
 290 .Fn ssleep
 291 appeared in
 292 .Dx 1.6 ,
 293 .Fn zsleep
 294 in
 295 .Dx 2.0 ,
 296 and
 297 .Fn lksleep
 298 and
 299 .Fn mtxsleep
 300 in
 301 .Dx 2.3 .
 302 .Sh AUTHORS
 303 .An -nosplit
 304 This manual page was written by
 305 .An J\(:org Wunsch
 306 and modified for
 307 .Dx
 308 by
 309 .An Hiten Pandya Aq hmp@dragonflybsd.org