1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
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
73 .nf
74 \fBint\fR \fBcond_reltimedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR,
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
117 initialization.
118 .sp
119 .LP
120 The \fBcond_init()\fR function initializes the condition variable pointed to by
121 \fIcvp\fR. A condition variable can have several different types of behavior,
122 specified by \fItype\fR. No current type uses \fIarg\fR although a future type
123 may specify additional behavior parameters with \fIarg\fR. The \fItype\fR
124 argument c take one of the following values:
125 .sp
126 .ne 2
127 .na
128 \fB\fBUSYNC_THREAD\fR\fR
129 .ad
130 .RS 17n
131 The condition variable can synchronize threads only in this process. This is
132 the default.
133 .RE
134
135 .sp
136 .ne 2
137 .na
138 \fB\fBUSYNC_PROCESS\fR\fR
139 .ad
140 .RS 17n
141 The condition variable can synchronize threads in this process and other
142 processes. Only one process should initialize the condition variable. The
143 object initialized with this attribute must be allocated in memory shared
144 between processes, either in System V shared memory (see \fBshmop\fR(2)) or in
145 memory mapped to a file (see \fBmmap\fR(2)). It is illegal to initialize the
146 object this way and to not allocate it in such shared memory.
147 .RE
148
149 .sp
150 .LP
151 Initializing condition variables can also be accomplished by allocating in
152 zeroed memory, in which case, a \fItype\fR of \fBUSYNC_THREAD\fR is assumed.
153 .sp
154 .LP
155 If default condition variable attributes are used, statically allocated
156 condition variables can be initialized by the macro \fBDEFAULTCV\fR.
157 .sp
158 .LP
159 Default condition variable initialization (intra-process):
160 .sp
161 .in +2
162 .nf
163 cond_t cvp;
164
165 cond_init(&cvp, NULL, NULL); /*initialize condition variable
166 with default*/
167 .fi
168 .in -2
169
170 .sp
171 .LP
172 or
173 .sp
174 .in +2
175 .nf
176 cond_init(&cvp, USYNC_THREAD, NULL);
177 .fi
178 .in -2
179
180 .sp
181 .LP
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
288 .RS 9n
289 Interrupted. The calling thread was awakened by the delivery of a UNIX signal.
290 .RE
291
292 .sp
293 .LP
294 If the mutex pointed to by \fImp\fR is a robust mutex (initialized with the
295 \fBLOCK_ROBUST\fR attribute), the \fBcond_wait()\fR, \fBcond_timedwait()\fR and
296 \fBcond_reltimedwait()\fR functions will, under the specified conditions,
297 return the following error values. For complete information, see the
298 description of the \fBmutex_lock()\fR function on the \fBmutex_init\fR(3C)
299 manual page.
300 .sp
301 .ne 2
302 .na
303 \fB\fBENOTRECOVERABLE\fR\fR
304 .ad
305 .RS 19n
306 The mutex was protecting the state that has now been left irrecoverable. The
307 mutex has not been acquired.
308 .RE
309
310 .sp
311 .ne 2
312 .na
313 \fB\fBEOWNERDEAD\fR\fR
314 .ad
315 .RS 19n
316 The last owner of the mutex died while holding the mutex, possibly leaving the
317 state it was protecting inconsistent. The mutex is now owned by the caller.
318 .RE
319
320 .sp
321 .LP
322 These functions may fail if:
323 .sp
324 .ne 2
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
370 .sp
371 .in +2
372 .nf
373 timestruc_t to;
374 \&...
375 (void) mutex_lock(mp);
376 to.tv_sec = time(NULL) + TIMEOUT;
377 to.tv_nsec = 0;
378 while (cond == FALSE) {
379 err = cond_timedwait(cvp, mp, &to);
380 if (err == ETIME) {
381 /* timeout, do something */
382 break;
383 }
384 }
385 (void) mutex_unlock(mp);
386 .fi
387 .in -2
388
389 .LP
390 \fBExample 3 \fRUse \fBcond_reltimedwait()\fR in a loop to test some condition.
391 .sp
392 .LP
393 The \fBcond_reltimedwait()\fR function is normally used in a loop testing in
394 some condition. It uses a relative timeout value as follows:
395
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
460 either \fBcond_timedwait()\fR or \fBcond_reltimedwait()\fR returns because of a
461 timeout, it returns the error value \fBETIME\fR.