Commit | Line | Data |
---|---|---|
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 | .\" |
de02175f | 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 | |
718dcee3 | 79 | .Fn tsleep "const volatile void *ident" "int flags" "const char *wmesg" "int timo" |
a4ef122b | 80 | .Ft int |
718dcee3 | 81 | .Fn ssleep "const volatile void *ident" "struct spinlock *spin" "int flags" "const char *wmesg" "int timo" |
b9356bf6 | 82 | .Ft int |
718dcee3 | 83 | .Fn lksleep "const volatile void *ident" "struct lock *lock" "int flags" "const char *wmesg" "int timo" |
8385f1e9 | 84 | .Ft int |
718dcee3 | 85 | .Fn mtxsleep "const volatile void *ident" "struct mtx *mtx" "int flags" "const char *wmesg" "int timo" |
85869e85 | 86 | .Ft int |
718dcee3 | 87 | .Fn zsleep "const volatile void *ident" "struct lwkt_serialize *slz" "int flags" "const char *wmesg" "int timo" |
85869e85 | 88 | .Ft void |
718dcee3 | 89 | .Fn tsleep_interlock "const volatile void *ident" "int flags" |
984263bc | 90 | .Ft void |
718dcee3 | 91 | .Fn wakeup "const volatile void *ident" |
984263bc | 92 | .Ft void |
718dcee3 | 93 | .Fn wakeup_one "const volatile void *ident" |
984263bc MD |
94 | .Sh DESCRIPTION |
95 | The functions | |
a4ef122b | 96 | .Fn tsleep , |
b9356bf6 AH |
97 | .Fn ssleep , |
98 | .Fn lksleep , | |
85869e85 | 99 | .Fn mtxsleep , |
146c9aa0 | 100 | .Fn zsleep , |
984263bc MD |
101 | and |
102 | .Fn wakeup | |
eff65839 HP |
103 | handle event-based process blocking. |
104 | If a process must wait for an | |
984263bc | 105 | external event, it is put on sleep by |
8385f1e9 | 106 | .Fn tsleep , |
b9356bf6 | 107 | .Fn ssleep , |
85869e85 SW |
108 | .Fn lksleep , |
109 | .Fn mtxsleep , | |
a4ef122b | 110 | or |
146c9aa0 | 111 | .Fn zsleep . |
85869e85 | 112 | .Pp |
984263bc MD |
113 | The parameter |
114 | .Ar ident | |
115 | is an arbitrary address that uniquely identifies the event on which | |
eff65839 HP |
116 | the process is being asleep. |
117 | All processes sleeping on a single | |
118 | .Fa ident | |
984263bc | 119 | are woken up later by |
58578425 | 120 | .Fn wakeup , |
984263bc | 121 | often called from inside an interrupt routine, to indicate that the |
eff65839 | 122 | resource the process/thread was blocking on is available now. |
984263bc MD |
123 | .Pp |
124 | The parameter | |
eff65839 | 125 | .Fa wmesg |
984263bc MD |
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 | |
984263bc | 132 | .Fn tsleep |
eff65839 HP |
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). | |
984263bc | 139 | If |
eff65839 HP |
140 | .Fa flags |
141 | contains the | |
142 | .Dv PCATCH | |
143 | flag, signals are checked before and after sleeping, else signals are | |
144 | ignored. | |
a4ef122b | 145 | .Pp |
03f0dd11 NA |
146 | The |
147 | .Fn tsleep_interlock | |
148 | function is similar to | |
85869e85 SW |
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) | |
11a137b0 | 159 | tsleep(..., flags | PINTERLOCKED, ...) |
85869e85 SW |
160 | .Ed |
161 | .Pp | |
162 | For example, to implement | |
58578425 | 163 | .Fn ssleep : |
85869e85 | 164 | .Bd -literal |
03f0dd11 | 165 | spin_lock(&important_lock); |
85869e85 SW |
166 | if (important_condition == 0) { |
167 | tsleep_interlock(ident, flags); | |
03f0dd11 | 168 | spin_unlock(&important_lock); |
11a137b0 | 169 | tsleep(..., flags | PINTERLOCKED, ...); |
85869e85 SW |
170 | } |
171 | .Ed | |
172 | .Pp | |
a4ef122b | 173 | The |
b9356bf6 | 174 | .Fn ssleep |
a4ef122b SS |
175 | function works like |
176 | .Fn tsleep | |
03f0dd11 | 177 | while at the same time releasing the exclusive spinlock |
a4ef122b SS |
178 | .Fa spin |
179 | before sleeping and reacquiring it before | |
b9356bf6 | 180 | .Fn ssleep |
a4ef122b SS |
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. | |
8385f1e9 SZ |
187 | .Pp |
188 | The | |
b9356bf6 AH |
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 | |
85869e85 SW |
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 | |
146c9aa0 | 214 | .Fn zsleep |
8385f1e9 SZ |
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 | |
146c9aa0 | 220 | .Fn zsleep |
8385f1e9 SZ |
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. | |
85869e85 SW |
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. | |
eff65839 HP |
238 | .Sh IMPLEMENTATION NOTES |
239 | Unlike | |
240 | .Fx , | |
984263bc | 241 | the |
eff65839 HP |
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 | |
9a379a4a | 249 | .Dv LWP_SINTR |
eff65839 HP |
250 | flag set are assumed to be disk-waits, otherwise they are |
251 | normal sleeps. | |
984263bc | 252 | .Sh RETURN VALUES |
eff65839 HP |
253 | The |
254 | .Fn tsleep | |
255 | function returns | |
256 | .Li 0 | |
257 | if awakened, otherwise an appropriate error code is returned. | |
85869e85 SW |
258 | .Sh FILES |
259 | The 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 | 264 | The timeout expired. |
4a865848 | 265 | .It Bq Er ERESTART |
df7fa753 SW |
266 | A signal needs to be delivered and the system call should |
267 | be restarted if possible. | |
eff65839 HP |
268 | This only happens if |
269 | .Dv PCATCH | |
270 | was set in | |
271 | .Fa flags . | |
4a865848 | 272 | .It Bq Er EINTR |
df7fa753 | 273 | The system call needs to be interrupted by the signal. |
eff65839 HP |
274 | This only happens if |
275 | .Dv PCATCH | |
276 | was 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 |
284 | The sleep/wakeup process synchronization mechanism is very old. |
285 | It appeared in a very early version of Unix. | |
984263bc | 286 | .Pp |
58578425 | 287 | .Fn tsleep |
984263bc MD |
288 | appeared in |
289 | .Bx 4.4 . | |
85869e85 | 290 | .Pp |
58578425 | 291 | .Fn ssleep |
85869e85 SW |
292 | appeared in |
293 | .Dx 1.6 , | |
58578425 | 294 | .Fn zsleep |
85869e85 SW |
295 | in |
296 | .Dx 2.0 , | |
297 | and | |
58578425 | 298 | .Fn lksleep |
85869e85 | 299 | and |
58578425 | 300 | .Fn mtxsleep |
85869e85 SW |
301 | in |
302 | .Dx 2.3 . | |
984263bc MD |
303 | .Sh AUTHORS |
304 | .An -nosplit | |
eff65839 HP |
305 | This manual page was written by |
306 | .An J\(:org Wunsch | |
307 | and modified for | |
308 | .Dx | |
309 | by | |
c616d378 | 310 | .An Hiten Pandya Aq Mt hmp@dragonflybsd.org . |