xref: /freebsd/share/man/man9/condvar.9 (revision 7aa383846770374466b1dcb2cefd71bde9acf463)
1.\"
2.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
14.\"
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
25.\" DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd June 5, 2007
30.Dt CONDVAR 9
31.Os
32.Sh NAME
33.Nm condvar ,
34.Nm cv_init ,
35.Nm cv_destroy ,
36.Nm cv_wait ,
37.Nm cv_wait_sig ,
38.Nm cv_wait_unlock ,
39.Nm cv_timedwait ,
40.Nm cv_timedwait_sig ,
41.Nm cv_signal ,
42.Nm cv_broadcast ,
43.Nm cv_broadcastpri ,
44.Nm cv_wmesg
45.Nd kernel condition variable
46.Sh SYNOPSIS
47.In sys/param.h
48.In sys/proc.h
49.In sys/condvar.h
50.Ft void
51.Fn cv_init "struct cv *cvp" "const char *desc"
52.Ft void
53.Fn cv_destroy "struct cv *cvp"
54.Ft void
55.Fn cv_wait "struct cv *cvp" "lock"
56.Ft int
57.Fn cv_wait_sig "struct cv *cvp" "lock"
58.Ft void
59.Fn cv_wait_unlock "struct cv *cvp" "lock"
60.Ft int
61.Fn cv_timedwait "struct cv *cvp" "lock" "int timo"
62.Ft int
63.Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo"
64.Ft void
65.Fn cv_signal "struct cv *cvp"
66.Ft void
67.Fn cv_broadcast "struct cv *cvp"
68.Ft void
69.Fn cv_broadcastpri "struct cv *cvp" "int pri"
70.Ft const char *
71.Fn cv_wmesg "struct cv *cvp"
72.Sh DESCRIPTION
73Condition variables are used in conjunction with mutexes to wait for conditions
74to occur.
75Condition variables are created with
76.Fn cv_init ,
77where
78.Fa cvp
79is a pointer to space for a
80.Vt struct cv ,
81and
82.Fa desc
83is a pointer to a null-terminated character string that describes the condition
84variable.
85Condition variables are destroyed with
86.Fn cv_destroy .
87Threads wait on condition variables by calling
88.Fn cv_wait ,
89.Fn cv_wait_sig ,
90.Fn cv_wait_unlock ,
91.Fn cv_timedwait ,
92or
93.Fn cv_timedwait_sig .
94Threads unblock waiters by calling
95.Fn cv_signal
96to unblock one waiter, or
97.Fn cv_broadcast
98or
99.Fn cv_broadcastpri
100to unblock all waiters.
101In addition to waking waiters,
102.Fn cv_broadcastpri
103ensures that all of the waiters have a priority of at least
104.Fa pri
105by raising the priority of any threads that do not.
106.Fn cv_wmesg
107returns the description string of
108.Fa cvp ,
109as set by the initial call to
110.Fn cv_init .
111.Pp
112The
113.Fa lock
114argument is a pointer to either a
115.Xr mutex 9 ,
116.Xr rwlock 9 ,
117or
118.Xr sx 9
119lock.
120A
121.Xr mutex 9
122argument must be initialized with
123.Dv MTX_DEF
124and not
125.Dv MTX_SPIN .
126A thread must hold
127.Fa lock
128before calling
129.Fn cv_wait ,
130.Fn cv_wait_sig ,
131.Fn cv_wait_unlock ,
132.Fn cv_timedwait ,
133or
134.Fn cv_timedwait_sig .
135When a thread waits on a condition,
136.Fa lock
137is atomically released before the thread is blocked, then reacquired
138before the function call returns.
139In addition, the thread will fully drop the
140.Va Giant
141mutex
142(even if recursed)
143while the it is suspended and will reacquire the
144.Va Giant
145mutex before the function returns.
146The
147.Fn cv_wait_unlock
148function does not reacquire the lock before returning.
149Note that the
150.Va Giant
151mutex may be specified as
152.Fa lock .
153However,
154.Va Giant
155may not be used as
156.Fa lock
157for the
158.Fn cv_wait_unlock
159function.
160All waiters must pass the same
161.Fa lock
162in conjunction with
163.Fa cvp .
164.Pp
165When
166.Fn cv_wait ,
167.Fn cv_wait_sig ,
168.Fn cv_wait_unlock ,
169.Fn cv_timedwait ,
170and
171.Fn cv_timedwait_sig
172unblock, their calling threads are made runnable.
173.Fn cv_timedwait
174and
175.Fn cv_timedwait_sig
176wait for at most
177.Fa timo
178/
179.Dv HZ
180seconds before being unblocked and returning
181.Er EWOULDBLOCK ;
182otherwise, they return 0.
183.Fn cv_wait_sig
184and
185.Fn cv_timedwait_sig
186return prematurely with a value of
187.Er EINTR
188or
189.Er ERESTART
190if a signal is caught, or 0 if signaled via
191.Fn cv_signal
192or
193.Fn cv_broadcast .
194.Sh RETURN VALUES
195If successful,
196.Fn cv_wait_sig ,
197.Fn cv_timedwait ,
198and
199.Fn cv_timedwait_sig
200return 0.
201Otherwise, a non-zero error code is returned.
202.Pp
203.Fn cv_wmesg
204returns the description string that was passed to
205.Fn cv_init .
206.Sh ERRORS
207.Fn cv_wait_sig
208and
209.Fn cv_timedwait_sig
210will fail if:
211.Bl -tag -width Er
212.It Bq Er EINTR
213A signal was caught and the system call should be interrupted.
214.It Bq Er ERESTART
215A signal was caught and the system call should be restarted.
216.El
217.Pp
218.Fn cv_timedwait
219and
220.Fn cv_timedwait_sig
221will fail if:
222.Bl -tag -width Er
223.It Bq Er EWOULDBLOCK
224Timeout expired.
225.El
226.Sh SEE ALSO
227.Xr locking 9 ,
228.Xr mtx_pool 9 ,
229.Xr mutex 9 ,
230.Xr rwlock 9 ,
231.Xr sema 9 ,
232.Xr sleep 9 ,
233.Xr sx 9
234