xref: /freebsd/share/man/man9/sleep.9 (revision 7bd6fde3) 
1.\"
2.\" Copyright (c) 1996 Joerg Wunsch
3.\"
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd February 27, 2007
29.Os
30.Dt SLEEP 9
31.Sh NAME
32.Nm msleep ,
33.Nm msleep_spin ,
34.Nm pause ,
35.Nm tsleep ,
36.Nm wakeup
37.Nd wait for events
38.Sh SYNOPSIS
39.In sys/param.h
40.In sys/systm.h
41.In sys/proc.h
42.Ft int
43.Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo"
44.Ft int
45.Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo"
46.Ft void
47.Fn pause "const char *wmesg" "int timo"
48.Ft int
49.Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo"
50.Ft void
51.Fn wakeup "void *chan"
52.Ft void
53.Fn wakeup_one "void *chan"
54.Sh DESCRIPTION
55The functions
56.Fn tsleep ,
57.Fn msleep ,
58.Fn msleep_spin ,
59.Fn pause ,
60.Fn wakeup ,
61and
62.Fn wakeup_one
63handle event-based thread blocking.
64If a thread must wait for an
65external event, it is put to sleep by
66.Fn tsleep ,
67.Fn msleep ,
68.Fn msleep_spin ,
69or
70.Fn pause .
71The parameter
72.Fa chan
73is an arbitrary address that uniquely identifies the event on which
74the thread is being put to sleep.
75All threads sleeping on a single
76.Fa chan
77are woken up later by
78.Fn wakeup ,
79often called from inside an interrupt routine, to indicate that the
80resource the thread was blocking on is available now.
81.Pp
82The parameter
83.Fa wmesg
84is a string describing the sleep condition for tools like
85.Xr ps 1 .
86Due to the limited space of those programs to display arbitrary strings,
87this message should not be longer than 6 characters.
88.Pp
89The
90.Fn wakeup_one
91function is used to make the first thread in the queue that is
92sleeping on the parameter
93.Fa chan
94runnable.
95This can prevent the system from becoming saturated
96when a large number of threads are sleeping on the same address,
97but only one of them can actually do any useful work when made
98runnable.
99.Pp
100The
101.Fn wakeup_one
102function does not work reliably if unrelated threads are sleeping on the same
103address.
104In this case, if a wakeup for one group of threads is delivered to a member of
105another group, that thread will ignore the wakeup, and the correct thread will
106never be woken up.
107It is the programmer's responsibility to choose a unique
108.Fa chan
109value.
110In case of doubt, do not use
111.Fn wakeup_one .
112.Pp
113The
114.Fn msleep
115function is the general sleep call.
116It suspends the current thread until a wakeup is
117performed on the specified identifier.
118The
119.Fa mtx
120parameter is a mutex which will be released before sleeping and reacquired
121before
122.Fn msleep
123returns.
124If
125.Fa priority
126includes the
127.Dv PDROP
128flag, the
129.Fa mtx
130parameter will not be reacquired before returning.
131The mutex is used to ensure that a condition can be checked atomically,
132and that the current thread can be suspended without missing a
133change to the condition, or an associated wakeup.
134If
135.Fa priority
136is not 0,
137then the thread will be made
138runnable with the specified
139.Fa priority
140when it resumes.
141If
142.Fa timo
143is not 0,
144then the thread will sleep for at most
145.Fa timo No / Va hz
146seconds.
147If the
148.Va Giant
149lock is not held and
150.Fa mtx
151is
152.Dv NULL ,
153then
154.Fa timo
155must be non-zero.
156If
157.Fa priority
158includes the
159.Dv PCATCH
160flag, signals are checked before and after sleeping, otherwise signals are
161not checked.
162The
163.Fn msleep
164function returns 0 if awakened,
165.Er EWOULDBLOCK
166if the timeout expires.
167If
168.Dv PCATCH
169is set and a signal needs to be delivered,
170.Er ERESTART
171is returned if the current system call should be restarted if
172possible, and
173.Er EINTR
174is returned if the system call should be interrupted by the signal
175(return
176.Er EINTR ) .
177.Pp
178The
179.Fn tsleep
180function is a variation on
181.Fn msleep .
182It is identical to invoking
183.Fn msleep
184with a
185.Dv NULL
186.Fa mtx
187parameter.
188.Pp
189The
190.Fn msleep_spin
191function is another variation on
192.Fn msleep .
193This function accepts a spin mutex rather than a default mutex for its
194.Fa mtx
195parameter.
196It is also more limited in that it does not accept a
197.Fa priority
198parameter.
199Thus, it will not change the priority of a sleeping thread,
200and it does not support the
201.Dv PDROP
202and
203.Dv PCATCH
204flags.
205.Pp
206The
207.Fn pause
208function is a wrapper around
209.Fn tsleep
210that suspends execution of the current thread for the indicated timeout.
211The thread can not be awakened early by signals or calls to
212.Fn wakeup
213or
214.Fn wakeup_one .
215.Sh RETURN VALUES
216See above.
217.Sh SEE ALSO
218.Xr ps 1 ,
219.Xr malloc 9 ,
220.Xr mi_switch 9
221.Sh HISTORY
222The functions
223.Fn sleep
224and
225.Fn wakeup
226were present in
227.At v1 .
228They were probably also present in the preceding
229PDP-7 version of
230.Ux .
231They were the basic process synchronization model.
232.Pp
233The
234.Fn tsleep
235function appeared in
236.Bx 4.4
237and added the parameters
238.Fa wmesg
239and
240.Fa timo .
241The
242.Fn sleep
243function was removed in
244.Fx 2.2 .
245The
246.Fn wakeup_one
247function appeared in
248.Fx 2.2 .
249The
250.Fn msleep
251function appeared in
252.Fx 5.0 ,
253and the
254.Fn msleep_spin
255function appeared in
256.Fx 6.2 .
257The
258.Fn pause
259function appeared in
260.Fx 7.0 .
261.Sh AUTHORS
262.An -nosplit
263This manual page was written by
264.An J\(:org Wunsch Aq joerg@FreeBSD.org .
265