27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH COND_INIT 3C "Jun 5, 2007"
48 .SH NAME
49 cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal,
50 cond_broadcast, cond_destroy \- condition variables
51 .SH SYNOPSIS
52 .LP
53 .nf
54 cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
55 #include <thread.h>
56 #include <synch.h>
57
58 \fBint\fR \fBcond_init\fR(\fBcond_t *\fR\fIcvp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
59 .fi
60
61 .LP
62 .nf
63 \fBint\fR \fBcond_wait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR);
64 .fi
65
66 .LP
67 .nf
68 \fBint\fR \fBcond_timedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR,
69 \fBtimestruc_t *\fR\fIabstime\fR);
70 .fi
71
72 .LP
75 \fBtimestruc_t *\fR\fIreltime\fR);
76 .fi
77
78 .LP
79 .nf
80 \fBint\fR \fBcond_signal\fR(\fBcond_t *\fR\fIcvp\fR);
81 .fi
82
83 .LP
84 .nf
85 \fBint\fR \fBcond_broadcast\fR(\fBcond_t *\fR\fIcvp\fR);
86 .fi
87
88 .LP
89 .nf
90 \fBint\fR \fBcond_destroy\fR(\fBcond_t *\fR\fIcvp\fR);
91 .fi
92
93 .SH DESCRIPTION
94 .SS "Initialize"
95 .sp
96 .LP
97 Condition variables and mutexes should be global. Condition variables that are
98 allocated in writable memory can synchronize threads among processes if they
99 are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized
100 for this purpose.
101 .sp
102 .LP
103 The scope of a condition variable is either intra-process or inter-process.
104 This is dependent upon whether the argument is passed implicitly or explicitly
105 to the initialization of that condition variable. A condition variable does not
106 need to be explicitly initialized. A condition variable is initialized with all
107 zeros, by default, and its scope is set to within the calling process. For
108 inter-process synchronization, a condition variable must be initialized once,
109 and only once, before use.
110 .sp
111 .LP
112 A condition variable must not be simultaneously initialized by multiple threads
113 or re-initialized while in use by other threads.
114 .sp
115 .LP
116 Attributes of condition variables can be set to the default or customized at
182 or
183 .sp
184 .in +2
185 .nf
186 cond_t cond = DEFAULTCV;
187 .fi
188 .in -2
189
190 .sp
191 .LP
192 Customized condition variable initialization (inter-process):
193 .sp
194 .in +2
195 .nf
196 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
197 inter-process scope */
198 .fi
199 .in -2
200
201 .SS "Condition Wait"
202 .sp
203 .LP
204 The condition wait interface allows a thread to wait for a condition and
205 atomically release the associated mutex that it needs to hold to check the
206 condition. The thread waits for another thread to make the condition true and
207 that thread's resulting call to signal and wakeup the waiting thread.
208 .sp
209 .LP
210 The \fBcond_wait()\fR function atomically releases the mutex pointed to by
211 \fImp\fR and causes the calling thread to block on the condition variable
212 pointed to by \fIcvp\fR. The blocked thread may be awakened by
213 \fBcond_signal()\fR, \fBcond_broadcast()\fR, or when interrupted by delivery of
214 a \fBUNIX\fR signal or a \fBfork()\fR.
215 .sp
216 .LP
217 The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
218 functions always return with the mutex locked and owned by the calling thread
219 even when returning an error, except when the mutex has the \fBLOCK_ROBUST\fR
220 attribute and has been left irrecoverable by the mutex's last owner. The
221 \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
222 functions return the appropriate error value if they fail to internally
223 reacquire the mutex.
224 .SS "Condition Signaling"
225 .sp
226 .LP
227 A condition signal allows a thread to unblock a single thread waiting on the
228 condition variable, whereas a condition broadcast allows a thread to unblock
229 all threads waiting on the condition variable.
230 .sp
231 .LP
232 The \fBcond_signal()\fR function unblocks one thread that is blocked on the
233 condition variable pointed to by \fIcvp\fR.
234 .sp
235 .LP
236 The \fBcond_broadcast()\fR function unblocks all threads that are blocked on
237 the condition variable pointed to by \fIcvp\fR.
238 .sp
239 .LP
240 If no threads are blocked on the condition variable, then \fBcond_signal()\fR
241 and \fBcond_broadcast()\fR have no effect.
242 .sp
243 .LP
244 The \fBcond_signal()\fR or \fBcond_broadcast()\fR functions can be called by a
245 thread whether or not it currently owns the mutex that threads calling
246 \fBcond_wait()\fR, \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR have
247 associated with the condition variable during their waits. If, however,
248 predictable scheduling behavior is required, then that mutex should be locked
249 by the thread prior to calling \fBcond_signal()\fR or \fBcond_broadcast()\fR.
250 .SS "Destroy"
251 .sp
252 .LP
253 The condition destroy functions destroy any state, but not the space,
254 associated with the condition variable.
255 .sp
256 .LP
257 The \fBcond_destroy()\fR function destroys any state associated with the
258 condition variable pointed to by \fIcvp\fR. The space for storing the condition
259 variable is not freed.
260 .SH RETURN VALUES
261 .sp
262 .LP
263 Upon successful completion, these functions return \fB0\fR. Otherwise, a
264 non-zero value is returned to indicate the error.
265 .SH ERRORS
266 .sp
267 .LP
268 The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions will fail
269 if:
270 .sp
271 .ne 2
272 .na
273 \fB\fBETIME\fR\fR
274 .ad
275 .RS 9n
276 The time specified by \fIabstime\fR or \fIreltime\fR has passed.
277 .RE
278
279 .sp
280 .LP
281 The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
282 functions will fail if:
283 .sp
284 .ne 2
285 .na
286 \fB\fBEINTR\fR\fR
287 .ad
325 .na
326 \fB\fBEFAULT\fR\fR
327 .ad
328 .RS 10n
329 The \fIcond\fR, \fIattr\fR, \fIcvp\fR, \fIarg\fR, \fIabstime\fR, or \fImutex\fR
330 argument points to an illegal address.
331 .RE
332
333 .sp
334 .ne 2
335 .na
336 \fB\fBEINVAL\fR\fR
337 .ad
338 .RS 10n
339 Invalid argument. For \fBcond_init()\fR, \fItype\fR is not a recognized type.
340 For \fBcond_timedwait()\fR, the number of nanoseconds is greater than or equal
341 to 1,000,000,000.
342 .RE
343
344 .SH EXAMPLES
345 .LP
346 \fBExample 1 \fRUse \fBcond_wait()\fR in a loop to test some condition.
347 .sp
348 .LP
349 The \fBcond_wait()\fR functin is normally used in a loop testing some
350 condition, as follows:
351
352 .sp
353 .in +2
354 .nf
355 (void) mutex_lock(mp);
356 while (cond == FALSE) {
357 (void) cond_wait(cvp, mp);
358 }
359 (void) mutex_unlock(mp);
360 .fi
361 .in -2
362
363 .LP
364 \fBExample 2 \fRUse \fBcond_timedwait()\fR in a loop to test some condition.
365 .sp
366 .LP
367 The \fBcond_timedwait()\fR function is normally used in a loop testing some
368 condition. It uses an absolute timeout value as follows:
369
396 .sp
397 .in +2
398 .nf
399 timestruc_t to;
400 \&...
401 (void) mutex_lock(mp);
402 while (cond == FALSE) {
403 to.tv_sec = TIMEOUT;
404 to.tv_nsec = 0;
405 err = cond_reltimedwait(cvp, mp, &to);
406 if (err == ETIME) {
407 /* timeout, do something */
408 break;
409 }
410 }
411 (void) mutex_unlock(mp);
412 .fi
413 .in -2
414
415 .SH ATTRIBUTES
416 .sp
417 .LP
418 See \fBattributes\fR(5) for descriptions of the following attributes:
419 .sp
420
421 .sp
422 .TS
423 box;
424 c | c
425 l | l .
426 ATTRIBUTE TYPE ATTRIBUTE VALUE
427 _
428 MT-Level MT-Safe
429 .TE
430
431 .SH SEE ALSO
432 .sp
433 .LP
434 \fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2),
435 \fBmutex_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5),
436 \fBcondition\fR(5), \fBmutex\fR(5), \fBstandards\fR(5)
437 .SH NOTES
438 .sp
439 .LP
440 If more than one thread is blocked on a condition variable, the order in which
441 threads are unblocked is determined by the scheduling policy. When each thread,
442 unblocked as a result of a \fBcond_signal()\fR or \fBcond_broadcast()\fR,
443 returns from its call to \fBcond_wait()\fR or \fBcond_timedwait()\fR , the
444 thread owns the mutex with which it called \fBcond_wait()\fR,
445 \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR. The thread(s) that are
446 unblocked compete for the mutex according to the scheduling policy and as if
447 each had called \fBmutex_lock\fR(3C).
448 .sp
449 .LP
450 When \fBcond_wait()\fR returns the value of the condition is indeterminate and
451 must be reevaluated.
452 .sp
453 .LP
454 The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions are similar
455 to \fBcond_wait()\fR, except that the calling thread will not wait for the
456 condition to become true past the absolute time specified by \fIabstime\fR or
457 the relative time specified by \fIreltime\fR. Note that \fBcond_timedwait()\fR
458 or \fBcond_reltimedwait()\fR might continue to block as it trys to reacquire
459 the mutex pointed to by \fImp\fR, which may be locked by another thread. If
|
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH COND_INIT 3C "February 15, 2020"
48 .SH NAME
49 cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal,
50 cond_broadcast, cond_destroy \- condition variables
51 .SH SYNOPSIS
52 .nf
53 cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
54 #include <thread.h>
55 #include <synch.h>
56
57 \fBint\fR \fBcond_init\fR(\fBcond_t *\fR\fIcvp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
58 .fi
59
60 .LP
61 .nf
62 \fBint\fR \fBcond_wait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR);
63 .fi
64
65 .LP
66 .nf
67 \fBint\fR \fBcond_timedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR,
68 \fBtimestruc_t *\fR\fIabstime\fR);
69 .fi
70
71 .LP
74 \fBtimestruc_t *\fR\fIreltime\fR);
75 .fi
76
77 .LP
78 .nf
79 \fBint\fR \fBcond_signal\fR(\fBcond_t *\fR\fIcvp\fR);
80 .fi
81
82 .LP
83 .nf
84 \fBint\fR \fBcond_broadcast\fR(\fBcond_t *\fR\fIcvp\fR);
85 .fi
86
87 .LP
88 .nf
89 \fBint\fR \fBcond_destroy\fR(\fBcond_t *\fR\fIcvp\fR);
90 .fi
91
92 .SH DESCRIPTION
93 .SS "Initialize"
94 Condition variables and mutexes should be global. Condition variables that are
95 allocated in writable memory can synchronize threads among processes if they
96 are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized
97 for this purpose.
98 .sp
99 .LP
100 The scope of a condition variable is either intra-process or inter-process.
101 This is dependent upon whether the argument is passed implicitly or explicitly
102 to the initialization of that condition variable. A condition variable does not
103 need to be explicitly initialized. A condition variable is initialized with all
104 zeros, by default, and its scope is set to within the calling process. For
105 inter-process synchronization, a condition variable must be initialized once,
106 and only once, before use.
107 .sp
108 .LP
109 A condition variable must not be simultaneously initialized by multiple threads
110 or re-initialized while in use by other threads.
111 .sp
112 .LP
113 Attributes of condition variables can be set to the default or customized at
179 or
180 .sp
181 .in +2
182 .nf
183 cond_t cond = DEFAULTCV;
184 .fi
185 .in -2
186
187 .sp
188 .LP
189 Customized condition variable initialization (inter-process):
190 .sp
191 .in +2
192 .nf
193 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
194 inter-process scope */
195 .fi
196 .in -2
197
198 .SS "Condition Wait"
199 The condition wait interface allows a thread to wait for a condition and
200 atomically release the associated mutex that it needs to hold to check the
201 condition. The thread waits for another thread to make the condition true and
202 that thread's resulting call to signal and wakeup the waiting thread.
203 .sp
204 .LP
205 The \fBcond_wait()\fR function atomically releases the mutex pointed to by
206 \fImp\fR and causes the calling thread to block on the condition variable
207 pointed to by \fIcvp\fR. The blocked thread may be awakened by
208 \fBcond_signal()\fR, \fBcond_broadcast()\fR, or when interrupted by delivery of
209 a \fBUNIX\fR signal or a \fBfork()\fR.
210 .sp
211 .LP
212 The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
213 functions always return with the mutex locked and owned by the calling thread
214 even when returning an error, except when the mutex has the \fBLOCK_ROBUST\fR
215 attribute and has been left irrecoverable by the mutex's last owner. The
216 \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
217 functions return the appropriate error value if they fail to internally
218 reacquire the mutex.
219 .SS "Condition Signaling"
220 A condition signal allows a thread to unblock a single thread waiting on the
221 condition variable, whereas a condition broadcast allows a thread to unblock
222 all threads waiting on the condition variable.
223 .sp
224 .LP
225 The \fBcond_signal()\fR function unblocks one thread that is blocked on the
226 condition variable pointed to by \fIcvp\fR.
227 .sp
228 .LP
229 The \fBcond_broadcast()\fR function unblocks all threads that are blocked on
230 the condition variable pointed to by \fIcvp\fR.
231 .sp
232 .LP
233 If no threads are blocked on the condition variable, then \fBcond_signal()\fR
234 and \fBcond_broadcast()\fR have no effect.
235 .sp
236 .LP
237 The \fBcond_signal()\fR or \fBcond_broadcast()\fR functions can be called by a
238 thread whether or not it currently owns the mutex that threads calling
239 \fBcond_wait()\fR, \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR have
240 associated with the condition variable during their waits. If, however,
241 predictable scheduling behavior is required, then that mutex should be locked
242 by the thread prior to calling \fBcond_signal()\fR or \fBcond_broadcast()\fR.
243 .SS "Destroy"
244 The condition destroy functions destroy any state, but not the space,
245 associated with the condition variable.
246 .sp
247 .LP
248 The \fBcond_destroy()\fR function destroys any state associated with the
249 condition variable pointed to by \fIcvp\fR. The space for storing the condition
250 variable is not freed.
251 .SH RETURN VALUES
252 Upon successful completion, these functions return \fB0\fR. Otherwise, a
253 non-zero value is returned to indicate the error.
254 .SH ERRORS
255 The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions will fail
256 if:
257 .sp
258 .ne 2
259 .na
260 \fB\fBETIME\fR\fR
261 .ad
262 .RS 9n
263 The time specified by \fIabstime\fR or \fIreltime\fR has passed.
264 .RE
265
266 .sp
267 .LP
268 The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR
269 functions will fail if:
270 .sp
271 .ne 2
272 .na
273 \fB\fBEINTR\fR\fR
274 .ad
312 .na
313 \fB\fBEFAULT\fR\fR
314 .ad
315 .RS 10n
316 The \fIcond\fR, \fIattr\fR, \fIcvp\fR, \fIarg\fR, \fIabstime\fR, or \fImutex\fR
317 argument points to an illegal address.
318 .RE
319
320 .sp
321 .ne 2
322 .na
323 \fB\fBEINVAL\fR\fR
324 .ad
325 .RS 10n
326 Invalid argument. For \fBcond_init()\fR, \fItype\fR is not a recognized type.
327 For \fBcond_timedwait()\fR, the number of nanoseconds is greater than or equal
328 to 1,000,000,000.
329 .RE
330
331 .SH EXAMPLES
332 \fBExample 1 \fRUse \fBcond_wait()\fR in a loop to test some condition.
333 .sp
334 .LP
335 The \fBcond_wait()\fR function is normally used in a loop testing some
336 condition, as follows:
337
338 .sp
339 .in +2
340 .nf
341 (void) mutex_lock(mp);
342 while (cond == FALSE) {
343 (void) cond_wait(cvp, mp);
344 }
345 (void) mutex_unlock(mp);
346 .fi
347 .in -2
348
349 .LP
350 \fBExample 2 \fRUse \fBcond_timedwait()\fR in a loop to test some condition.
351 .sp
352 .LP
353 The \fBcond_timedwait()\fR function is normally used in a loop testing some
354 condition. It uses an absolute timeout value as follows:
355
382 .sp
383 .in +2
384 .nf
385 timestruc_t to;
386 \&...
387 (void) mutex_lock(mp);
388 while (cond == FALSE) {
389 to.tv_sec = TIMEOUT;
390 to.tv_nsec = 0;
391 err = cond_reltimedwait(cvp, mp, &to);
392 if (err == ETIME) {
393 /* timeout, do something */
394 break;
395 }
396 }
397 (void) mutex_unlock(mp);
398 .fi
399 .in -2
400
401 .SH ATTRIBUTES
402 See \fBattributes\fR(5) for descriptions of the following attributes:
403 .sp
404
405 .sp
406 .TS
407 box;
408 c | c
409 l | l .
410 ATTRIBUTE TYPE ATTRIBUTE VALUE
411 _
412 MT-Level MT-Safe
413 .TE
414
415 .SH SEE ALSO
416 \fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2),
417 \fBmutex_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5),
418 \fBcondition\fR(5), \fBmutex\fR(5), \fBstandards\fR(5)
419 .SH NOTES
420 If more than one thread is blocked on a condition variable, the order in which
421 threads are unblocked is determined by the scheduling policy. When each thread,
422 unblocked as a result of a \fBcond_signal()\fR or \fBcond_broadcast()\fR,
423 returns from its call to \fBcond_wait()\fR or \fBcond_timedwait()\fR , the
424 thread owns the mutex with which it called \fBcond_wait()\fR,
425 \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR. The thread(s) that are
426 unblocked compete for the mutex according to the scheduling policy and as if
427 each had called \fBmutex_lock\fR(3C).
428 .sp
429 .LP
430 When \fBcond_wait()\fR returns the value of the condition is indeterminate and
431 must be reevaluated.
432 .sp
433 .LP
434 The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions are similar
435 to \fBcond_wait()\fR, except that the calling thread will not wait for the
436 condition to become true past the absolute time specified by \fIabstime\fR or
437 the relative time specified by \fIreltime\fR. Note that \fBcond_timedwait()\fR
438 or \fBcond_reltimedwait()\fR might continue to block as it trys to reacquire
439 the mutex pointed to by \fImp\fR, which may be locked by another thread. If
|