2 .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice(s), this list of conditions and the following disclaimer as
9 .\" the first lines of this file unmodified other than the possible
10 .\" addition of one or more copyright notices.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice(s), 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 COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
40 .Nm cv_timedwait_sbt ,
41 .Nm cv_timedwait_sig ,
42 .Nm cv_timedwait_sig_sbt ,
47 .Nd kernel condition variable
53 .Fn cv_init "struct cv *cvp" "const char *desc"
55 .Fn cv_destroy "struct cv *cvp"
57 .Fn cv_wait "struct cv *cvp" "lock"
59 .Fn cv_wait_sig "struct cv *cvp" "lock"
61 .Fn cv_wait_unlock "struct cv *cvp" "lock"
63 .Fn cv_timedwait "struct cv *cvp" "lock" "int timo"
65 .Fn cv_timedwait_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \
66 "sbintime_t pr" "int flags"
68 .Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo"
70 .Fn cv_timedwait_sig_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \
71 "sbintime_t pr" "int flags"
73 .Fn cv_signal "struct cv *cvp"
75 .Fn cv_broadcast "struct cv *cvp"
77 .Fn cv_broadcastpri "struct cv *cvp" "int pri"
79 .Fn cv_wmesg "struct cv *cvp"
81 Condition variables are used in conjunction with mutexes to wait for conditions
83 Condition variables are created with
87 is a pointer to space for a
91 is a pointer to a null-terminated character string that describes the condition
93 Condition variables are destroyed with
95 Threads wait on condition variables by calling
101 .Fn cv_timedwait_sig .
102 Threads unblock waiters by calling
104 to unblock one waiter, or
108 to unblock all waiters.
109 In addition to waking waiters,
111 ensures that all of the waiters have a priority of at least
113 by raising the priority of any threads that do not.
115 returns the description string of
117 as set by the initial call to
122 argument is a pointer to either a
130 argument must be initialized with
142 .Fn cv_timedwait_sig .
143 When a thread waits on a condition,
145 is atomically released before the thread is blocked, then reacquired
146 before the function call returns.
147 In addition, the thread will fully drop the
151 while the it is suspended and will reacquire the
153 mutex before the function returns.
156 function does not reacquire the lock before returning.
159 mutex may be specified as
168 All waiters must pass the same
180 unblock, their calling threads are made runnable.
188 seconds before being unblocked and returning
190 otherwise, they return 0.
194 return prematurely with a value of
198 if a signal is caught, or 0 if signaled via
205 .Fn cv_timedwait_sig_sbt
210 It allows to specify relative or absolute unblock time with higher resolution
215 allows to specify wanted absolute event precision.
218 allows to pass additional
219 .Fn callout_reset_sbt
228 Otherwise, a non-zero error code is returned.
231 returns the description string that was passed to
240 A signal was caught and the system call should be interrupted.
242 A signal was caught and the system call should be restarted.
250 .It Bq Er EWOULDBLOCK