| blob | ba3dfefd626840d6944bfb9240a67a6d51947400 |
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