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.
50 .Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo"
52 .Fn msleep_sbt "void *chan" "struct mtx *mtx" "int priority" \
53 "const char *wmesg" "sbintime_t sbt" "sbintime_t pr" "int flags"
55 .Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo"
57 .Fn msleep_spin_sbt "void *chan" "struct mtx *mtx" "const char *wmesg" \
58 "sbintime_t sbt" "sbintime_t pr" "int flags"
60 .Fn pause "const char *wmesg" "int timo"
62 .Fn pause_sig "const char *wmesg" "int timo"
64 .Fn pause_sbt "const char *wmesg" "sbintime_t sbt" "sbintime_t pr" \
67 .Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo"
69 .Fn tsleep_sbt "void *chan" "int priority" "const char *wmesg" \
70 "sbintime_t sbt" "sbintime_t pr" "int flags"
72 .Fn wakeup "void *chan"
74 .Fn wakeup_one "void *chan"
76 .Fn wakeup_any "void *chan"
89 handle event-based thread blocking.
90 If a thread must wait for an
91 external event, it is put to sleep by
99 Threads may also wait using one of the locking primitive sleep routines
107 is an arbitrary address that uniquely identifies the event on which
108 the thread is being put to sleep.
109 All threads sleeping on a single
111 are woken up later by
113 often called from inside an interrupt routine, to indicate that the
114 resource the thread was blocking on is available now.
118 specifies a new priority for the thread as well as some optional flags.
119 If the new priority is not 0,
120 then the thread will be made
121 runnable with the specified
125 should never be used, as it is for compatibility only.
126 A new priority of 0 means to use the thread's current priority when
127 it is made runnable again.
133 flag, pending signals are allowed to interrupt the sleep, otherwise
134 pending signals are ignored during the sleep.
137 is set and a signal becomes pending,
139 is returned if the current system call should be restarted if
142 is returned if the system call should be interrupted by the signal
148 is a string describing the sleep condition for tools like
150 Due to the limited space of those programs to display arbitrary strings,
151 this message should not be longer than 6 characters.
155 specifies a timeout for the sleep.
159 then the thread will sleep for at most
162 If the timeout expires,
163 then the sleep function will return
167 .Fn msleep_spin_sbt ,
175 It allows the caller to specify relative or absolute wakeup time with higher resolution
180 allows the caller to specify wanted absolute event precision.
183 allows the caller to pass additional
184 .Fn callout_reset_sbt
187 Several of the sleep functions including
190 and the locking primitive sleep routines specify an additional lock
192 The lock will be released before sleeping and reacquired
193 before the sleep routine returns.
199 the lock will not be reacquired before returning.
200 The lock is used to ensure that a condition can be checked atomically,
201 and that the current thread can be suspended without missing a
202 change to the condition, or an associated wakeup.
203 In addition, all of the sleep routines will fully drop the
207 while the thread is suspended and will reacquire the
209 mutex before the function returns.
212 mutex may be specified as the lock to drop.
213 In that case, however, the
217 To avoid lost wakeups,
218 either a lock should be used to protect against races,
219 or a timeout should be specified to place an upper bound on the delay due
224 function should only be invoked with a timeout of 0 when the
230 function requires that
232 reference a default, i.e. non-spin, mutex.
233 Its use is deprecated in favor of
235 which provides identical behavior.
239 function requires that
241 reference a spin mutex.
244 function does not accept a
246 parameter and thus does not support changing the current thread's priority,
250 or catching signals via the
256 function is a wrapper around
258 that suspends execution of the current thread for the indicated timeout.
259 The thread can not be awakened early by signals or calls to
266 function is a variant of
268 which can be awakened early by signals.
272 function makes the first highest priority thread in the queue that is
273 sleeping on the parameter
276 This reduces the load when a large number of threads are sleeping on
277 the same address, but only one of them can actually do any useful work
280 Due to the way it works, the
282 function requires that only related threads sleep on a specific
285 It is the programmer's responsibility to choose a unique
290 function did not require this, though it was never good practice
291 for threads to share a
298 pay particular attention to ensure that no other threads wait on the
304 function is similar to
306 except that it makes runnable last thread on the queue (sleeping less),
308 It can be used when threads sleeping on the
310 are known to be identical and there is no reason to be fair.
312 If the timeout given by
316 is based on an absolute real-time clock value,
317 then the thread should copy the global
321 member before reading the RTC.
322 If the real-time clock is adjusted, these functions will set
324 to zero and return zero.
325 The caller should reconsider its orientation with the new RTC value.
327 When awakened by a call to
331 if a signal is pending and
334 a non-zero error code is returned.
335 If the thread is awakened by a call to
343 and locking primitive sleep functions return 0.
344 Zero can also be returned when the real-time clock is adjusted;
347 Otherwise, a non-zero error code is returned.
352 and the locking primitive sleep functions will fail if:
357 flag was specified, a signal was caught, and the system call should be
362 flag was specified, a signal was caught, and the system call should be
364 .It Bq Er EWOULDBLOCK
365 A non-zero timeout was specified and the timeout expired.
383 They were probably also present in the preceding
386 They were the basic process synchronization model.
392 and added the parameters
398 function was removed in
422 This manual page was written by
423 .An J\(:org Wunsch Aq Mt joerg@FreeBSD.org .