xref: /dragonfly/share/man/man9/sleep.9 (revision 6e278935) 
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
95The functions
96.Fn tsleep ,
97.Fn ssleep ,
98.Fn lksleep ,
99.Fn mtxsleep ,
100.Fn zsleep ,
101and
102.Fn wakeup
103handle event-based process blocking.
104If a process must wait for an
105external event, it is put on sleep by
106.Fn tsleep ,
107.Fn ssleep ,
108.Fn lksleep ,
109.Fn mtxsleep ,
110or
111.Fn zsleep .
112.Pp
113The parameter
114.Ar ident
115is an arbitrary address that uniquely identifies the event on which
116the process is being asleep.
117All processes sleeping on a single
118.Fa ident
119are woken up later by
120.Fn wakeup ,
121often called from inside an interrupt routine, to indicate that the
122resource the process/thread was blocking on is available now.
123.Pp
124The parameter
125.Fa wmesg
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
132.Fn tsleep
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).
139If
140.Fa flags
141contains the
142.Dv PCATCH
143flag, signals are checked before and after sleeping, else signals are
144ignored.
145.Pp
146.Fn Tsleep_interlock
147is similar to
148.Fn tsleep ,
149in that it queues a thread on a sleep queue, but it does not actually put the
150thread to sleep.
151This allows coupling tsleep with higher-level synchronization primitives.
152The pattern is:
153.Bd -literal
154(acquire high level synchronization primitive)
155(test condition of interest)
156tsleep_interlock(ident, flags)
157(release high level synchronization primitive)
158tsleep(..., PINTERLOCK)
159.Ed
160.Pp
161For example, to implement
162.Fn ssleep :
163.Bd -literal
164spin_lock_wr(&important_lock);
165if (important_condition == 0) {
166	tsleep_interlock(ident, flags);
167	spin_unlock_wr(&important_lock);
168	tsleep(..., PINTERLOCK);
169}
170.Ed
171.Pp
172The
173.Fn ssleep
174function works like
175.Fn tsleep
176while at the same time releasing the exclusive (write) spinlock
177.Fa spin
178before sleeping and reacquiring it before
179.Fn ssleep
180returns.
181This is an atomic operation, which guarantees that a
182.Fn wakeup
183interlocked by
184.Fa spin
185will not be missed.
186.Pp
187The
188.Fn lksleep
189function works like
190.Fn tsleep
191while at the same time releasing the exclusive lockmgr lock
192.Fa lock
193before sleeping and reacquiring it before
194.Fn lksleep
195returns.
196This is an atomic operation, which guarantees that a
197.Fn wakeup
198interlocked by
199.Fa lock
200will not be missed.
201.Pp
202The
203.Fn mtxsleep
204function works like
205.Fn tsleep
206while at the same time atomically releasing the mutex
207.Fa mtx
208before sleeping and reacquiring it in exclusive state before
209.Fn mtxsleep
210returns.
211.Pp
212The
213.Fn zsleep
214function works like
215.Fn tsleep
216while at the same time releasing the serializer
217.Fa slz
218before sleeping and reacquiring it before
219.Fn zsleep
220returns.
221This is an atomic operation, which guarantees that a
222.Fn wakeup
223interlocked by
224.Fa slz
225will not be missed.
226.Pp
227The
228.Fn wakeup_one
229function is used to make the first process/thread in the queue that is
230sleeping on the parameter
231.Fa ident
232runnable.
233This can prevent the system from becoming saturated
234when a large number of processes/threads are sleeping on the same address,
235but only one of them can actually do any useful work when made
236runnable.
237.Sh IMPLEMENTATION NOTES
238Unlike
239.Fx ,
240the
241.Fn tsleep
242function in
243.Dx
244ignores priority information because it is not required by the
245.Tn LWKT
246subsystem.
247Sleeps without the
248.Dv LWP_SINTR
249flag set are assumed to be disk-waits, otherwise they are
250normal sleeps.
251.Sh RETURN VALUES
252The
253.Fn tsleep
254function returns
255.Li 0
256if awakened, otherwise an appropriate error code is returned.
257.Sh FILES
258The 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
263The timeout expired.
264.It Bq Er ERESTART
265A signal needs to be delivered and the system call should
266be restarted if possible.
267This only happens if
268.Dv PCATCH
269was set in
270.Fa flags .
271.It Bq Er EINTR
272The system call needs to be interrupted by the signal.
273This only happens if
274.Dv PCATCH
275was 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
283The sleep/wakeup process synchronization mechanism is very old.
284It appeared in a very early version of Unix.
285.Pp
286.Fn tsleep
287appeared in
288.Bx 4.4 .
289.Pp
290.Fn ssleep
291appeared in
292.Dx 1.6 ,
293.Fn zsleep
294in
295.Dx 2.0 ,
296and
297.Fn lksleep
298and
299.Fn mtxsleep
300in
301.Dx 2.3 .
302.Sh AUTHORS
303.An -nosplit
304This manual page was written by
305.An J\(:org Wunsch
306and modified for
307.Dx
308by
309.An Hiten Pandya Aq hmp@dragonflybsd.org
310