sleep.9: s/PINTERLOCK/PINTERLOCKED/
[dragonfly.git] / share / man / man9 / sleep.9
CommitLineData
984263bc 1.\"
85869e85 2.\" Copyright (c) 2004,2010 The DragonFly Project. All rights reserved.
9cca02b8
HP
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.\"
984263bc
MD
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 $
fb5b3747 59.\"
3663d84a 60.Dd October 12, 2012
984263bc 61.Dt SLEEP 9
fb5b3747 62.Os
984263bc 63.Sh NAME
984263bc 64.Nm tsleep ,
b9356bf6 65.Nm ssleep ,
146c9aa0 66.Nm lksleep ,
85869e85 67.Nm mtxsleep ,
146c9aa0 68.Nm zsleep ,
85869e85 69.Nm tsleep_interlock ,
eff65839
HP
70.Nm wakeup ,
71.Nm wakeup_one
72.Nd wait/sleep/block for events
984263bc
MD
73.Sh SYNOPSIS
74.In sys/param.h
7845a2b6 75.In sys/serialize.h
984263bc
MD
76.In sys/systm.h
77.In sys/proc.h
78.Ft int
85869e85 79.Fn tsleep "void *ident" "int flags" "const char *wmesg" "int timo"
a4ef122b 80.Ft int
85869e85 81.Fn ssleep "void *ident" "struct spinlock *spin" "int flags" "const char *wmesg" "int timo"
b9356bf6 82.Ft int
85869e85 83.Fn lksleep "void *ident" "struct lock *lock" "int flags" "const char *wmesg" "int timo"
8385f1e9 84.Ft int
85869e85
SW
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"
984263bc
MD
90.Ft void
91.Fn wakeup "void *ident"
92.Ft void
93.Fn wakeup_one "void *ident"
94.Sh DESCRIPTION
95The functions
a4ef122b 96.Fn tsleep ,
b9356bf6
AH
97.Fn ssleep ,
98.Fn lksleep ,
85869e85 99.Fn mtxsleep ,
146c9aa0 100.Fn zsleep ,
984263bc
MD
101and
102.Fn wakeup
eff65839
HP
103handle event-based process blocking.
104If a process must wait for an
984263bc 105external event, it is put on sleep by
8385f1e9 106.Fn tsleep ,
b9356bf6 107.Fn ssleep ,
85869e85
SW
108.Fn lksleep ,
109.Fn mtxsleep ,
a4ef122b 110or
146c9aa0 111.Fn zsleep .
85869e85 112.Pp
984263bc
MD
113The parameter
114.Ar ident
115is an arbitrary address that uniquely identifies the event on which
eff65839
HP
116the process is being asleep.
117All processes sleeping on a single
118.Fa ident
984263bc 119are woken up later by
58578425 120.Fn wakeup ,
984263bc 121often called from inside an interrupt routine, to indicate that the
eff65839 122resource the process/thread was blocking on is available now.
984263bc
MD
123.Pp
124The parameter
eff65839 125.Fa wmesg
984263bc
MD
126is a string describing the sleep condition for tools like
127.Xr ps 1 .
128Due to the limited space of those programs to display arbitrary strings,
129this message should not be longer than 6 characters.
130.Pp
131The
984263bc 132.Fn tsleep
eff65839
HP
133function is general in its use and suspends the current process/thread until a
134wakeup is performed on the specified identifier.
135The process/thread will then be made runnable.
136The process/thread will sleep at most
137.Fa timo
138\&/ hz seconds (0 means no timeout).
984263bc 139If
eff65839
HP
140.Fa flags
141contains the
142.Dv PCATCH
143flag, signals are checked before and after sleeping, else signals are
144ignored.
a4ef122b 145.Pp
03f0dd11
NA
146The
147.Fn tsleep_interlock
148function is similar to
85869e85
SW
149.Fn tsleep ,
150in that it queues a thread on a sleep queue, but it does not actually put the
151thread to sleep.
152This allows coupling tsleep with higher-level synchronization primitives.
153The pattern is:
154.Bd -literal
155(acquire high level synchronization primitive)
156(test condition of interest)
157tsleep_interlock(ident, flags)
158(release high level synchronization primitive)
3663d84a 159tsleep(..., PINTERLOCKED, ...)
85869e85
SW
160.Ed
161.Pp
162For example, to implement
58578425 163.Fn ssleep :
85869e85 164.Bd -literal
03f0dd11 165spin_lock(&important_lock);
85869e85
SW
166if (important_condition == 0) {
167 tsleep_interlock(ident, flags);
03f0dd11 168 spin_unlock(&important_lock);
3663d84a 169 tsleep(..., PINTERLOCK, ...);
85869e85
SW
170}
171.Ed
172.Pp
a4ef122b 173The
b9356bf6 174.Fn ssleep
a4ef122b
SS
175function works like
176.Fn tsleep
03f0dd11 177while at the same time releasing the exclusive spinlock
a4ef122b
SS
178.Fa spin
179before sleeping and reacquiring it before
b9356bf6 180.Fn ssleep
a4ef122b
SS
181returns.
182This is an atomic operation, which guarantees that a
183.Fn wakeup
184interlocked by
185.Fa spin
186will not be missed.
8385f1e9
SZ
187.Pp
188The
b9356bf6
AH
189.Fn lksleep
190function works like
191.Fn tsleep
192while at the same time releasing the exclusive lockmgr lock
193.Fa lock
194before sleeping and reacquiring it before
195.Fn lksleep
196returns.
197This is an atomic operation, which guarantees that a
198.Fn wakeup
199interlocked by
200.Fa lock
201will not be missed.
202.Pp
203The
85869e85
SW
204.Fn mtxsleep
205function works like
206.Fn tsleep
207while at the same time atomically releasing the mutex
208.Fa mtx
209before sleeping and reacquiring it in exclusive state before
210.Fn mtxsleep
211returns.
212.Pp
213The
146c9aa0 214.Fn zsleep
8385f1e9
SZ
215function works like
216.Fn tsleep
217while at the same time releasing the serializer
218.Fa slz
219before sleeping and reacquiring it before
146c9aa0 220.Fn zsleep
8385f1e9
SZ
221returns.
222This is an atomic operation, which guarantees that a
223.Fn wakeup
224interlocked by
225.Fa slz
226will not be missed.
85869e85
SW
227.Pp
228The
229.Fn wakeup_one
230function is used to make the first process/thread in the queue that is
231sleeping on the parameter
232.Fa ident
233runnable.
234This can prevent the system from becoming saturated
235when a large number of processes/threads are sleeping on the same address,
236but only one of them can actually do any useful work when made
237runnable.
eff65839
HP
238.Sh IMPLEMENTATION NOTES
239Unlike
240.Fx ,
984263bc 241the
eff65839
HP
242.Fn tsleep
243function in
244.Dx
245ignores priority information because it is not required by the
246.Tn LWKT
247subsystem.
248Sleeps without the
9a379a4a 249.Dv LWP_SINTR
eff65839
HP
250flag set are assumed to be disk-waits, otherwise they are
251normal sleeps.
984263bc 252.Sh RETURN VALUES
eff65839
HP
253The
254.Fn tsleep
255function returns
256.Li 0
257if awakened, otherwise an appropriate error code is returned.
85869e85
SW
258.Sh FILES
259The various sleep functions are in
260.Pa /sys/kern/kern_synch.c .
eff65839
HP
261.Sh ERRORS
262.Bl -tag -width Er
4a865848 263.It Bq Er EWOULDBLOCK
df7fa753 264The timeout expired.
4a865848 265.It Bq Er ERESTART
df7fa753
SW
266A signal needs to be delivered and the system call should
267be restarted if possible.
eff65839
HP
268This only happens if
269.Dv PCATCH
270was set in
271.Fa flags .
4a865848 272.It Bq Er EINTR
df7fa753 273The system call needs to be interrupted by the signal.
eff65839
HP
274This only happens if
275.Dv PCATCH
276was set in
277.Fa flags .
278.El
984263bc
MD
279.Sh SEE ALSO
280.Xr ps 1 ,
8385f1e9
SZ
281.Xr kmalloc 9 ,
282.Xr serializer 9
984263bc 283.Sh HISTORY
eff65839
HP
284The sleep/wakeup process synchronization mechanism is very old.
285It appeared in a very early version of Unix.
984263bc 286.Pp
58578425 287.Fn tsleep
984263bc
MD
288appeared in
289.Bx 4.4 .
85869e85 290.Pp
58578425 291.Fn ssleep
85869e85
SW
292appeared in
293.Dx 1.6 ,
58578425 294.Fn zsleep
85869e85
SW
295in
296.Dx 2.0 ,
297and
58578425 298.Fn lksleep
85869e85 299and
58578425 300.Fn mtxsleep
85869e85
SW
301in
302.Dx 2.3 .
984263bc
MD
303.Sh AUTHORS
304.An -nosplit
eff65839
HP
305This manual page was written by
306.An J\(:org Wunsch
307and modified for
308.Dx
309by
310.An Hiten Pandya Aq hmp@dragonflybsd.org