2 .\" Copyright (c) 1996 Joerg Wunsch
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
43 .Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo"
45 .Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo"
47 .Fn pause "const char *wmesg" "int timo"
49 .Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo"
51 .Fn wakeup "void *chan"
53 .Fn wakeup_one "void *chan"
63 handle event-based thread blocking.
64 If a thread must wait for an
65 external event, it is put to sleep by
71 Threads may also wait using one of the locking primitive sleep routines
79 is an arbitrary address that uniquely identifies the event on which
80 the thread is being put to sleep.
81 All threads sleeping on a single
85 often called from inside an interrupt routine, to indicate that the
86 resource the thread was blocking on is available now.
90 specifies a new priority for the thread as well as some optional flags.
91 If the new priority is not 0,
92 then the thread will be made
93 runnable with the specified
97 should never be used, as it is for compatibility only.
98 A new priority of 0 means to use the thread's current priority when
99 it is made runnable again.
105 flag, signals are checked before and after sleeping, otherwise signals are
109 is set and a signal needs to be delivered,
111 is returned if the current system call should be restarted if
114 is returned if the system call should be interrupted by the signal
119 flag is specified in addition to
121 then the sleeping thread is not stopped while sleeping upon delivery of
123 or other stop action.
124 Instead, it is waken up, assuming that stop occurs on reaching a stop
125 point when returning to usermode.
126 The flag should be used when sleeping thread owns resources, for instance
127 vnode locks, that should be freed timely.
131 is a string describing the sleep condition for tools like
133 Due to the limited space of those programs to display arbitrary strings,
134 this message should not be longer than 6 characters.
138 specifies a timeout for the sleep.
142 then the thread will sleep for at most
145 If the timeout expires,
146 then the sleep function will return
149 Several of the sleep functions including
152 and the locking primitive sleep routines specify an additional lock
154 The lock will be released before sleeping and reacquired
155 before the sleep routine returns.
161 the lock will not be reacquired before returning.
162 The lock is used to ensure that a condition can be checked atomically,
163 and that the current thread can be suspended without missing a
164 change to the condition, or an associated wakeup.
165 In addition, all of the sleep routines will fully drop the
169 while the thread is suspended and will reacquire the
171 mutex before the function returns.
174 mutex may be specified as the lock to drop.
175 In that case, however, the
179 To avoid lost wakeups,
180 either a lock should be used to protect against races,
181 or a timeout should be specified to place an upper bound on the delay due
186 function should only be invoked with a timeout of 0 when the
192 function requires that
194 reference a default, i.e. non-spin, mutex.
195 Its use is deprecated in favor of
197 which provides identical behavior.
201 function requires that
203 reference a spin mutex.
206 function does not accept a
208 parameter and thus does not support changing the current thread's priority,
212 or catching signals via the
218 function is a wrapper around
220 that suspends execution of the current thread for the indicated timeout.
221 The thread can not be awakened early by signals or calls to
228 function makes the first thread in the queue that is sleeping on the
232 This reduces the load when a large number of threads are sleeping on
233 the same address, but only one of them can actually do any useful work
236 Due to the way it works, the
238 function requires that only related threads sleep on a specific
241 It is the programmer's responsibility to choose a unique
246 function did not require this, though it was never good practice
247 for threads to share a
254 pay particular attention to ensure that no other threads wait on the
258 If the thread is awakened by a call to
266 and locking primitive sleep functions return 0.
267 Otherwise, a non-zero error code is returned.
272 and the locking primitive sleep functions will fail if:
277 flag was specified, a signal was caught, and the system call should be
282 flag was specified, a signal was caught, and the system call should be
284 .It Bq Er EWOULDBLOCK
285 A non-zero timeout was specified and the timeout expired.
302 They were probably also present in the preceding
305 They were the basic process synchronization model.
311 and added the parameters
317 function was removed in
337 This manual page was written by
338 .An J\(:org Wunsch Aq joerg@FreeBSD.org .