share/man/man9/sleep.9

   1 .\"
   2 .\" Copyright (c) 2004 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 .\" $DragonFly: src/share/man/man9/sleep.9,v 1.10 2008/03/05 13:19:23 sephe Exp $
  60 .\" "
  61 .Dd March 5, 2008
  62 .Os
  63 .Dt SLEEP 9
  64 .Sh NAME
  65 .Nm tsleep ,
  66 .Nm msleep ,
  67 .Nm serialize_sleep ,
  68 .Nm wakeup ,
  69 .Nm wakeup_one
  70 .Nd wait/sleep/block for events
  71 .Sh SYNOPSIS
  72 .In sys/param.h
  73 .In sys/systm.h
  74 .In sys/proc.h
  75 .Ft int
  76 .Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo"
  77 .Ft int
  78 .Fn msleep "void *ident" "struct spinlock *spin" "int flag" "const char *wmesg" "int timo"
  79 .Ft int
  80 .Fn serialize_sleep "void *ident" "struct lwkt_serialize *slz" "int flag" "const char *wmesg" "int timo"
  81 .Ft void
  82 .Fn wakeup "void *ident"
  83 .Ft void
  84 .Fn wakeup_one "void *ident"
  85 .Sh DESCRIPTION
  86 The functions
  87 .Fn tsleep ,
  88 .Fn msleep ,
  89 .Fn serialize_sleep ,
  90 and
  91 .Fn wakeup
  92 handle event-based process blocking.
  93 If a process must wait for an
  94 external event, it is put on sleep by
  95 .Fn tsleep ,
  96 .Fn msleep
  97 or
  98 .Fn serialize_sleep .
  99 The parameter
 100 .Ar ident
 101 is an arbitrary address that uniquely identifies the event on which
 102 the process is being asleep.
 103 All processes sleeping on a single
 104 .Fa ident
 105 are woken up later by
 106 .Nm wakeup ,
 107 often called from inside an interrupt routine, to indicate that the
 108 resource the process/thread was blocking on is available now.
 109 .Pp
 110 The parameter
 111 .Fa wmesg
 112 is a string describing the sleep condition for tools like
 113 .Xr ps 1 .
 114 Due to the limited space of those programs to display arbitrary strings,
 115 this message should not be longer than 6 characters.
 116 .Pp
 117 The
 118 .Fn wakeup_one
 119 function is used to make the first process/thread in the queue that is
 120 sleeping on the parameter
 121 .Fa ident
 122 runnable.
 123 This can prevent the system from becoming saturated
 124 when a large number of processes/threads are sleeping on the same address,
 125 but only one of them can actually do any useful work when made
 126 runnable.
 127 .Pp
 128 The
 129 .Fn tsleep
 130 function is general in its use and suspends the current process/thread until a
 131 wakeup is performed on the specified identifier.
 132 The process/thread will then be made runnable.
 133 The process/thread will sleep at most
 134 .Fa timo
 135 \&/ hz seconds (0 means no timeout).
 136 If
 137 .Fa flags
 138 contains the
 139 .Dv PCATCH
 140 flag, signals are checked before and after sleeping, else signals are
 141 ignored.
 142 .Pp
 143 The
 144 .Fn msleep
 145 function works like
 146 .Fn tsleep
 147 while at the same time releasing the exclusive (write) spinlock
 148 .Fa spin
 149 before sleeping and reacquiring it before
 150 .Fn msleep
 151 returns.
 152 This is an atomic operation, which guarantees that a
 153 .Fn wakeup
 154 interlocked by
 155 .Fa spin
 156 will not be missed.
 157 .Pp
 158 The
 159 .Fn serialize_sleep
 160 function works like
 161 .Fn tsleep
 162 while at the same time releasing the serializer
 163 .Fa slz
 164 before sleeping and reacquiring it before
 165 .Fn serialize_sleep
 166 returns.
 167 This is an atomic operation, which guarantees that a
 168 .Fn wakeup
 169 interlocked by
 170 .Fa slz
 171 will not be missed.
 172 .Sh IMPLEMENTATION NOTES
 173 Unlike
 174 .Fx ,
 175 the
 176 .Fn tsleep
 177 function in
 178 .Dx
 179 ignores priority information because it is not required by the
 180 .Tn LWKT
 181 subsystem.
 182 Sleeps without the
 183 .Dv LWP_SINTR
 184 flag set are assumed to be disk-waits, otherwise they are
 185 normal sleeps.
 186 .Sh RETURN VALUES
 187 The
 188 .Fn tsleep
 189 function returns
 190 .Li 0
 191 if awakened, otherwise an appropriate error code is returned.
 192 .Sh ERRORS
 193 .Bl -tag -width Er
 194 .It Bq Er EWOULDBLOCK
 195 The timeout expired.
 196 .It Bq Er ERESTART
 197 A signal needs to be delivered and the system call should
 198 be restarted if possible.
 199 This only happens if
 200 .Dv PCATCH
 201 was set in
 202 .Fa flags .
 203 .It Bq Er EINTR
 204 The system call needs to be interrupted by the signal.
 205 This only happens if
 206 .Dv PCATCH
 207 was set in
 208 .Fa flags .
 209 .El
 210 .Sh SEE ALSO
 211 .Xr ps 1 ,
 212 .Xr kmalloc 9 ,
 213 .Xr serializer 9
 214 .Sh HISTORY
 215 The sleep/wakeup process synchronization mechanism is very old.
 216 It appeared in a very early version of Unix.
 217 .Pp
 218 .Nm Tsleep
 219 appeared in
 220 .Bx 4.4 .
 221 .Sh AUTHORS
 222 .An -nosplit
 223 This manual page was written by
 224 .An J\(:org Wunsch
 225 and modified for
 226 .Dx
 227 by
 228 .An Hiten Pandya Aq hmp@dragonflybsd.org