a07f8ceab6b8aa1e87591f203b2203a64747d2dd
[dragonfly.git] / 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 The
147 .Fn tsleep_interlock
148 function is similar to
149 .Fn tsleep ,
150 in that it queues a thread on a sleep queue, but it does not actually put the
151 thread to sleep.
152 This allows coupling tsleep with higher-level synchronization primitives.
153 The pattern is:
154 .Bd -literal
155 (acquire high level synchronization primitive)
156 (test condition of interest)
157 tsleep_interlock(ident, flags)
158 (release high level synchronization primitive)
159 tsleep(..., PINTERLOCK)
160 .Ed
161 .Pp
162 For example, to implement
163 .Fn ssleep :
164 .Bd -literal
165 spin_lock(&important_lock);
166 if (important_condition == 0) {
167         tsleep_interlock(ident, flags);
168         spin_unlock(&important_lock);
169         tsleep(..., PINTERLOCK);
170 }
171 .Ed
172 .Pp
173 The
174 .Fn ssleep
175 function works like
176 .Fn tsleep
177 while at the same time releasing the exclusive spinlock
178 .Fa spin
179 before sleeping and reacquiring it before
180 .Fn ssleep
181 returns.
182 This is an atomic operation, which guarantees that a
183 .Fn wakeup
184 interlocked by
185 .Fa spin
186 will not be missed.
187 .Pp
188 The
189 .Fn lksleep
190 function works like
191 .Fn tsleep
192 while at the same time releasing the exclusive lockmgr lock
193 .Fa lock
194 before sleeping and reacquiring it before
195 .Fn lksleep
196 returns.
197 This is an atomic operation, which guarantees that a
198 .Fn wakeup
199 interlocked by
200 .Fa lock
201 will not be missed.
202 .Pp
203 The
204 .Fn mtxsleep
205 function works like
206 .Fn tsleep
207 while at the same time atomically releasing the mutex
208 .Fa mtx
209 before sleeping and reacquiring it in exclusive state before
210 .Fn mtxsleep
211 returns.
212 .Pp
213 The
214 .Fn zsleep
215 function works like
216 .Fn tsleep
217 while at the same time releasing the serializer
218 .Fa slz
219 before sleeping and reacquiring it before
220 .Fn zsleep
221 returns.
222 This is an atomic operation, which guarantees that a
223 .Fn wakeup
224 interlocked by
225 .Fa slz
226 will not be missed.
227 .Pp
228 The
229 .Fn wakeup_one
230 function is used to make the first process/thread in the queue that is
231 sleeping on the parameter
232 .Fa ident
233 runnable.
234 This can prevent the system from becoming saturated
235 when a large number of processes/threads are sleeping on the same address,
236 but only one of them can actually do any useful work when made
237 runnable.
238 .Sh IMPLEMENTATION NOTES
239 Unlike
240 .Fx ,
241 the
242 .Fn tsleep
243 function in
244 .Dx
245 ignores priority information because it is not required by the
246 .Tn LWKT
247 subsystem.
248 Sleeps without the
249 .Dv LWP_SINTR
250 flag set are assumed to be disk-waits, otherwise they are
251 normal sleeps.
252 .Sh RETURN VALUES
253 The
254 .Fn tsleep
255 function returns
256 .Li 0
257 if awakened, otherwise an appropriate error code is returned.
258 .Sh FILES
259 The various sleep functions are in
260 .Pa /sys/kern/kern_synch.c .
261 .Sh ERRORS
262 .Bl -tag -width Er
263 .It Bq Er EWOULDBLOCK
264 The timeout expired.
265 .It Bq Er ERESTART
266 A signal needs to be delivered and the system call should
267 be restarted if possible.
268 This only happens if
269 .Dv PCATCH
270 was set in
271 .Fa flags .
272 .It Bq Er EINTR
273 The system call needs to be interrupted by the signal.
274 This only happens if
275 .Dv PCATCH
276 was set in
277 .Fa flags .
278 .El
279 .Sh SEE ALSO
280 .Xr ps 1 ,
281 .Xr kmalloc 9 ,
282 .Xr serializer 9
283 .Sh HISTORY
284 The sleep/wakeup process synchronization mechanism is very old.
285 It appeared in a very early version of Unix.
286 .Pp
287 .Fn tsleep
288 appeared in
289 .Bx 4.4 .
290 .Pp
291 .Fn ssleep
292 appeared in
293 .Dx 1.6 ,
294 .Fn zsleep
295 in
296 .Dx 2.0 ,
297 and
298 .Fn lksleep
299 and
300 .Fn mtxsleep
301 in
302 .Dx 2.3 .
303 .Sh AUTHORS
304 .An -nosplit
305 This manual page was written by
306 .An J\(:org Wunsch
307 and modified for
308 .Dx
309 by
310 .An Hiten Pandya Aq hmp@dragonflybsd.org