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