| blob | 6654ae78a10640a65224ba53e8d70cdbb5b6bfb8 |
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 ssleep ,
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 ssleep "void *ident" "struct spinlock *spin" "int flag" "const char *wmesg" "int timo"
80 .Ft int
81 .Fn lksleep "void *ident" "struct lock *lock" "int flag" "const char *wmesg" "int timo"
82 .Ft int
83 .Fn serialize_sleep "void *ident" "struct lwkt_serialize *slz" "int flag" "const char *wmesg" "int timo"
84 .Ft void
85 .Fn wakeup "void *ident"
86 .Ft void
87 .Fn wakeup_one "void *ident"
88 .Sh DESCRIPTION
89 The functions
90 .Fn tsleep ,
91 .Fn ssleep ,
92 .Fn lksleep ,
93 .Fn serialize_sleep ,
94 and
95 .Fn wakeup
96 handle event-based process blocking.
97 If a process must wait for an
98 external event, it is put on sleep by
99 .Fn tsleep ,
100 .Fn ssleep ,
101 .Fn lksleep
102 or
103 .Fn serialize_sleep .
104 The parameter
105 .Ar ident
106 is an arbitrary address that uniquely identifies the event on which
107 the process is being asleep.
108 All processes sleeping on a single
109 .Fa ident
110 are woken up later by
111 .Nm wakeup ,
112 often called from inside an interrupt routine, to indicate that the
113 resource the process/thread was blocking on is available now.
114 .Pp
115 The parameter
116 .Fa wmesg
117 is a string describing the sleep condition for tools like
118 .Xr ps 1 .
119 Due to the limited space of those programs to display arbitrary strings,
120 this message should not be longer than 6 characters.
121 .Pp
122 The
123 .Fn wakeup_one
124 function is used to make the first process/thread in the queue that is
125 sleeping on the parameter
126 .Fa ident
127 runnable.
128 This can prevent the system from becoming saturated
129 when a large number of processes/threads are sleeping on the same address,
130 but only one of them can actually do any useful work when made
131 runnable.
132 .Pp
133 The
134 .Fn tsleep
135 function is general in its use and suspends the current process/thread until a
136 wakeup is performed on the specified identifier.
137 The process/thread will then be made runnable.
138 The process/thread will sleep at most
139 .Fa timo
140 \&/ hz seconds (0 means no timeout).
141 If
142 .Fa flags
143 contains the
144 .Dv PCATCH
145 flag, signals are checked before and after sleeping, else signals are
146 ignored.
147 .Pp
148 The
149 .Fn ssleep
150 function works like
151 .Fn tsleep
152 while at the same time releasing the exclusive (write) spinlock
153 .Fa spin
154 before sleeping and reacquiring it before
155 .Fn ssleep
156 returns.
157 This is an atomic operation, which guarantees that a
158 .Fn wakeup
159 interlocked by
160 .Fa spin
161 will not be missed.
162 .Pp
163 The
164 .Fn lksleep
165 function works like
166 .Fn tsleep
167 while at the same time releasing the exclusive lockmgr lock
168 .Fa lock
169 before sleeping and reacquiring it before
170 .Fn lksleep
171 returns.
172 This is an atomic operation, which guarantees that a
173 .Fn wakeup
174 interlocked by
175 .Fa lock
176 will not be missed.
177 .Pp
178 The
179 .Fn serialize_sleep
180 function works like
181 .Fn tsleep
182 while at the same time releasing the serializer
183 .Fa slz
184 before sleeping and reacquiring it before
185 .Fn serialize_sleep
186 returns.
187 This is an atomic operation, which guarantees that a
188 .Fn wakeup
189 interlocked by
190 .Fa slz
191 will not be missed.
192 .Sh IMPLEMENTATION NOTES
193 Unlike
194 .Fx ,
195 the
196 .Fn tsleep
197 function in
198 .Dx
199 ignores priority information because it is not required by the
200 .Tn LWKT
201 subsystem.
202 Sleeps without the
203 .Dv LWP_SINTR
204 flag set are assumed to be disk-waits, otherwise they are
205 normal sleeps.
206 .Sh RETURN VALUES
207 The
208 .Fn tsleep
209 function returns
210 .Li 0
211 if awakened, otherwise an appropriate error code is returned.
212 .Sh ERRORS
213 .Bl -tag -width Er
214 .It Bq Er EWOULDBLOCK
215 The timeout expired.
216 .It Bq Er ERESTART
217 A signal needs to be delivered and the system call should
218 be restarted if possible.
219 This only happens if
220 .Dv PCATCH
221 was set in
222 .Fa flags .
223 .It Bq Er EINTR
224 The system call needs to be interrupted by the signal.
225 This only happens if
226 .Dv PCATCH
227 was set in
228 .Fa flags .
229 .El
230 .Sh SEE ALSO
231 .Xr ps 1 ,
232 .Xr kmalloc 9 ,
233 .Xr serializer 9
234 .Sh HISTORY
235 The sleep/wakeup process synchronization mechanism is very old.
236 It appeared in a very early version of Unix.
237 .Pp
238 .Nm Tsleep
239 appeared in
240 .Bx 4.4 .
241 .Sh AUTHORS
242 .An -nosplit
243 This manual page was written by
244 .An J\(:org Wunsch
245 and modified for
246 .Dx
247 by
248 .An Hiten Pandya Aq hmp@dragonflybsd.org