| blob | e97c52fc3df2136fc3e2241866675ca9657225b4 |
1 '\" te
2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 2016 Joyent, Inc.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH CONDVAR 9F "Mar 29, 2016"
8 .SH NAME
9 condvar, cv_init, cv_destroy, cv_wait, cv_signal, cv_broadcast, cv_wait_sig,
10 cv_timedwait, cv_timedwait_sig, cv_reltimedwait, cv_reltimedwait_sig \-
11 condition variable routines
12 .SH SYNOPSIS
13 .LP
14 .nf
15 #include <sys/ksynch.h>
19 \fBvoid\fR \fBcv_init\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBchar *\fR\fIname\fR, \fBkcv_type_t\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
20 .fi
22 .LP
23 .nf
24 \fBvoid\fR \fBcv_destroy\fR(\fBkcondvar_t *\fR\fIcvp\fR);
25 .fi
27 .LP
28 .nf
29 \fBvoid\fR \fBcv_wait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR);
30 .fi
32 .LP
33 .nf
34 \fBvoid\fR \fBcv_signal\fR(\fBkcondvar_t *\fR\fIcvp\fR);
35 .fi
37 .LP
38 .nf
39 \fBvoid\fR \fBcv_broadcast\fR(\fBkcondvar_t *\fR\fIcvp\fR);
40 .fi
42 .LP
43 .nf
44 \fBint\fR \fBcv_wait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR);
45 .fi
47 .LP
48 .nf
49 \fBclock_t\fR \fBcv_timedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR);
50 .fi
52 .LP
53 .nf
54 \fBclock_t\fR \fBcv_timedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR);
55 .fi
57 .LP
58 .nf
59 \fBclock_t\fR \fBcv_reltimedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fIdelta\fR,
60 \fBtime_res_t\fR \fIres\fR);
61 .fi
63 .LP
64 .nf
65 \fBclock_t\fR \fBcv_reltimedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fIdelta\fR,
66 \fBtime_res_t\fR \fIres\fR);
67 .fi
69 .SH INTERFACE LEVEL
70 .LP
71 Solaris DDI specific (Solaris DDI).
72 .SH PARAMETERS
73 .ne 2
74 .na
75 \fB\fIcvp\fR\fR
76 .ad
77 .RS 11n
78 A pointer to an abstract data type \fBkcondvar_t\fR.
79 .RE
81 .sp
82 .ne 2
83 .na
84 \fB\fImp\fR\fR
85 .ad
86 .RS 11n
87 A pointer to a mutual exclusion lock (\fBkmutex_t\fR), initialized by
88 \fBmutex_init\fR(9F) and held by the caller.
89 .RE
91 .sp
92 .ne 2
93 .na
94 \fB\fIname\fR\fR
95 .ad
96 .RS 11n
97 Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR
98 strings are legal, but they're a waste of kernel memory.)
99 .RE
101 .sp
102 .ne 2
103 .na
104 \fB\fItype\fR\fR
105 .ad
106 .RS 11n
107 The constant \fBCV_DRIVER\fR.
108 .RE
110 .sp
111 .ne 2
112 .na
113 \fB\fIarg\fR\fR
114 .ad
115 .RS 11n
116 A type-specific argument, drivers should pass arg as \fINULL\fR.
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fB\fItimeout\fR\fR
123 .ad
124 .RS 11n
125 A time, in absolute ticks since boot, when \fBcv_timedwait()\fR or
126 \fBcv_timedwait_sig()\fR should return.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fIdelta\fR\fR
133 .ad
134 .RS 11n
135 A time, in ticks, to indicate how long \fBcv_reltimedwait()\fR or
136 \fBcv_reltimedwait_sig()\fR should wait before returning. Drivers should use
137 \fBdrv_usectohz\fR(9F) to determine this value.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fIres\fR\fR
144 .ad
145 .RS 11n
146 A value which describes the requested accuracy of the timeout argument.
147 The system may anticipate or defer the timeout based on the requested
148 accuracy to prevent unnecessary wakeups. The following identifiers are
149 valid arguments for this type:
150 .LP
151 .RS 4n
152 .B TR_NANOSEC
153 .RS 16n
154 Nanosecond granularity
155 .RE
156 .RE
157 .RS 4n
158 .B TR_MICROSEC
159 .RS 16n
160 Microsecond granularity
161 .RE
162 .RE
163 .RS 4n
164 .B TR_MILLISEC
165 .RS 16n
166 Millisecond granularity
167 .RE
168 .RE
169 .RS 4n
170 .B TR_SEC
171 .RS 16n
172 Second granularity
173 .RE
174 .RE
175 .RS 4n
176 .B TR_CLOCK_TICK
177 .RS 16n
178 Granularity of a kernel clock tick, commonly 100 or 1000 Hz.
179 .RE
180 .RE
181 .LP
182 Note that the granularity of these functions is in clock ticks,
183 therefore the only values which will have an effect are:
184 .B TR_SEC
185 and
186 .B TR_CLOCK_TICK .
187 .RE
189 .SH DESCRIPTION
190 .LP
191 Condition variables are a standard form of thread synchronization. They are
192 designed to be used with mutual exclusion locks (mutexes). The associated mutex
193 is used to ensure that a condition can be checked atomically and that the
194 thread can block on the associated condition variable without missing either a
195 change to the condition or a signal that the condition has changed. Condition
196 variables must be initialized by calling \fBcv_init()\fR, and must be
197 deallocated by calling \fBcv_destroy()\fR.
198 .sp
199 .LP
200 The usual use of condition variables is to check a condition (for example,
201 device state, data structure reference count, etc.) while holding a mutex which
202 keeps other threads from changing the condition. If the condition is such that
203 the thread should block, \fBcv_wait()\fR is called with a related condition
204 variable and the mutex. At some later point in time, another thread would
205 acquire the mutex, set the condition such that the previous thread can be
206 unblocked, unblock the previous thread with \fBcv_signal()\fR or
207 \fBcv_broadcast()\fR, and then release the mutex.
208 .sp
209 .LP
210 \fBcv_wait()\fR suspends the calling thread and exits the mutex atomically so
211 that another thread which holds the mutex cannot signal on the condition
212 variable until the blocking thread is blocked. Before returning, the mutex is
213 reacquired.
214 .sp
215 .LP
216 \fBcv_signal()\fR signals the condition and wakes one blocked thread. All
217 blocked threads can be unblocked by calling \fBcv_broadcast()\fR.
218 \fBcv_signal()\fR and \fBcv_broadcast()\fR can be called by a thread even if it
219 does not hold the mutex passed into \fBcv_wait()\fR, though holding the mutex
220 is necessary to ensure predictable scheduling.
221 .sp
222 .LP
223 The function \fBcv_wait_sig()\fR is similar to \fBcv_wait()\fR but returns
224 \fB0\fR if a signal (for example, by \fBkill\fR(2)) is sent to the thread. In
225 any case, the mutex is reacquired before returning.
226 .sp
227 .LP
228 The function \fBcv_timedwait()\fR is similar to \fBcv_wait()\fR, except that it
229 returns \fB\(mi1\fR without the condition being signaled after the timeout time
230 has been reached.
231 .sp
232 .LP
233 The function \fBcv_timedwait_sig()\fR is similar to \fBcv_timedwait()\fR and
234 \fBcv_wait_sig()\fR, except that it returns \fB\(mi1\fR without the condition
235 being signaled after the timeout time has been reached, or \fB0\fR if a signal
236 (for example, by \fBkill\fR(2)) is sent to the thread.
237 .sp
238 .LP
239 For both \fBcv_timedwait()\fR and \fBcv_timedwait_sig()\fR, time is in absolute
240 clock ticks since the last system reboot. The current time may be found by
241 calling \fBddi_get_lbolt\fR(9F).
242 .sp
243 .LP
244 The functions
245 .B cv_reltimedwait()
246 and
247 .B cv_reltimedwait_sig()
248 behave similarly to
249 .B cv_timedwait() and
250 .B cv_timedwait_sig()
251 respectively, except instead of taking a time in absolute clock ticks,
252 they take a relative number of clock ticks to wait. In addition, both
253 functions take an additional argument
254 .I res,
255 which specifies the desired granularity that the system should default
256 to, generally the value
257 .B TR_CLOCK_TICK .
258 .SH RETURN VALUES
259 .ne 2
260 .na
261 \fB\fB0\fR\fR
262 .ad
263 .RS 9n
264 For \fBcv_wait_sig()\fR, \fBcv_timedwait_sig()\fR, and
265 \fBcv_reltimedwait_sig()\fR indicates that the condition was not necessarily
266 signaled and the function returned because a signal (as in \fBkill\fR(2)) was
267 pending.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fB\(mi1\fR\fR
274 .ad
275 .RS 9n
276 For \fBcv_timedwait()\fR, \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
277 \fBcv_reltimedwait_sig()\fR, indicates that the condition was not necessarily
278 signaled and the function returned because the timeout time was reached.
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fB\fB>0\fR\fR
285 .ad
286 .RS 9n
287 For \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR, \fBcv_timedwait_sig()\fR,
288 \fBcv_reltimedwait()\fR, and \fBcv_reltimedwait_sig()\fR, indicates that the
289 condition was met and the function returned due to a call to \fBcv_signal()\fR
290 or \fBcv_broadcast()\fR, or due to a premature wakeup (see NOTES).
291 .RE
293 .SH CONTEXT
294 .LP
295 These functions can be called from user, kernel or interrupt context. In most
296 cases, however, \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR,
297 \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
298 \fBcv_reltimedwait_sig()\fR, should not be called from interrupt context, and
299 cannot be called from a high-level interrupt context.
300 .sp
301 .LP
302 If \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR,
303 \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, or
304 \fBcv_reltimedwait_sig()\fR, are used from interrupt context, lower-priority
305 interrupts will not be serviced during the wait. This means that if the thread
306 that will eventually perform the wakeup becomes blocked on anything that
307 requires the lower-priority interrupt, the system will hang.
308 .sp
309 .LP
310 For example, the thread that will perform the wakeup may need to first allocate
311 memory. This memory allocation may require waiting for paging \fBI/O\fR to
312 complete, which may require a lower-priority disk or network interrupt to be
313 serviced. In general, situations like this are hard to predict, so it is
314 advisable to avoid waiting on condition variables or semaphores in an interrupt
315 context.
316 .SH EXAMPLES
317 .LP
318 \fBExample 1 \fRWaiting for a Flag Value in a Driver's Unit
319 .sp
320 .LP
321 Here the condition being waited for is a flag value in a driver's unit
322 structure. The condition variable is also in the unit structure, and the flag
323 word is protected by a mutex in the unit structure.
325 .sp
326 .in +2
327 .nf
328 mutex_enter(&un->un_lock);
329 while (un->un_flag & UNIT_BUSY)
330 cv_wait(&un->un_cv, &un->un_lock);
331 un->un_flag |= UNIT_BUSY;
332 mutex_exit(&un->un_lock);
333 .fi
334 .in -2
336 .LP
337 \fBExample 2 \fRUnblocking Threads Blocked by the Code in Example 1
338 .sp
339 .LP
340 At some later point in time, another thread would execute the following to
341 unblock any threads blocked by the above code.
343 .sp
344 .in +2
345 .nf
347 mutex_enter(&un->un_lock);
348 un->un_flag &= ~UNIT_BUSY;
349 cv_broadcast(&un->un_cv);
350 mutex_exit(&un->un_lock);
351 .fi
352 .in -2
354 .SH NOTES
355 .LP
356 It is possible for \fBcv_wait()\fR, \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR,
357 \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
358 \fBcv_reltimedwait_sig()\fR to return prematurely, that is, not due to a call to
359 \fBcv_signal()\fR or \fBcv_broadcast()\fR. This occurs most commonly in the case
360 of \fBcv_wait_sig()\fR and \fBcv_timedwait_sig()\fR when the thread is stopped
361 and restarted by job control signals or by a debugger, but can happen in other
362 cases as well, even for \fBcv_wait()\fR. Code that calls these functions must
363 always recheck the reason for blocking and call again if the reason for blocking
364 is still true.
365 .sp
366 .LP
367 If your driver needs to wait on behalf of processes that have real-time
368 constraints, use \fBcv_timedwait()\fR rather than \fBdelay\fR(9F). The
369 \fBdelay()\fR function calls \fBtimeout\fR(9F), which can be subject to
370 priority inversions.
371 .sp
372 .LP
373 Not all threads can receive signals from user level processes. In cases where
374 such reception is impossible (such as during execution of \fBclose\fR(9E) due
375 to \fBexit\fR(2)), \fBcv_wait_sig()\fR behaves as \fBcv_wait()\fR,
376 \fBcv_timedwait_sig()\fR behaves as \fBcv_timedwait()\fR, and
377 \fBcv_reltimedwait_sig()\fR behaves as \fBcv_reltimedwait()\fR. To avoid unkillable
378 processes, users of these functions may need to protect against waiting
379 indefinitely for events that might not occur. The \fBddi_can_receive_sig\fR(9F)
380 function is provided to detect when signal reception is possible.
381 .SH SEE ALSO
382 .LP
383 \fBkill\fR(2), \fBddi_can_receive_sig\fR(9F), \fBddi_get_lbolt\fR(9F),
384 \fBdrv_usectohz\fR(9F) \fBmutex\fR(9F), \fBmutex_init\fR(9F),
385 .sp
386 .LP
387 \fIWriting Device Drivers\fR