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 "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
72 .nf
73 \fBint\fR \fBcond_reltimedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR,
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
114 initialization.
115 .sp
116 .LP
117 The \fBcond_init()\fR function initializes the condition variable pointed to by
118 \fIcvp\fR. A condition variable can have several different types of behavior,
119 specified by \fItype\fR. No current type uses \fIarg\fR although a future type
120 may specify additional behavior parameters with \fIarg\fR. The \fItype\fR
121 argument c take one of the following values:
122 .sp
123 .ne 2
124 .na
125 \fB\fBUSYNC_THREAD\fR\fR
126 .ad
127 .RS 17n
128 The condition variable can synchronize threads only in this process. This is
129 the default.
130 .RE
131
132 .sp
133 .ne 2
134 .na
135 \fB\fBUSYNC_PROCESS\fR\fR
136 .ad
137 .RS 17n
138 The condition variable can synchronize threads in this process and other
139 processes. Only one process should initialize the condition variable. The
140 object initialized with this attribute must be allocated in memory shared
141 between processes, either in System V shared memory (see \fBshmop\fR(2)) or in
142 memory mapped to a file (see \fBmmap\fR(2)). It is illegal to initialize the
143 object this way and to not allocate it in such shared memory.
144 .RE
145
146 .sp
147 .LP
148 Initializing condition variables can also be accomplished by allocating in
149 zeroed memory, in which case, a \fItype\fR of \fBUSYNC_THREAD\fR is assumed.
150 .sp
151 .LP
152 If default condition variable attributes are used, statically allocated
153 condition variables can be initialized by the macro \fBDEFAULTCV\fR.
154 .sp
155 .LP
156 Default condition variable initialization (intra-process):
157 .sp
158 .in +2
159 .nf
160 cond_t cvp;
161
162 cond_init(&cvp, NULL, NULL); /*initialize condition variable
163 with default*/
164 .fi
165 .in -2
166
167 .sp
168 .LP
169 or
170 .sp
171 .in +2
172 .nf
173 cond_init(&cvp, USYNC_THREAD, NULL);
174 .fi
175 .in -2
176
177 .sp
178 .LP
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
275 .RS 9n
276 Interrupted. The calling thread was awakened by the delivery of a UNIX signal.
277 .RE
278
279 .sp
280 .LP
281 If the mutex pointed to by \fImp\fR is a robust mutex (initialized with the
282 \fBLOCK_ROBUST\fR attribute), the \fBcond_wait()\fR, \fBcond_timedwait()\fR and
283 \fBcond_reltimedwait()\fR functions will, under the specified conditions,
284 return the following error values. For complete information, see the
285 description of the \fBmutex_lock()\fR function on the \fBmutex_init\fR(3C)
286 manual page.
287 .sp
288 .ne 2
289 .na
290 \fB\fBENOTRECOVERABLE\fR\fR
291 .ad
292 .RS 19n
293 The mutex was protecting the state that has now been left irrecoverable. The
294 mutex has not been acquired.
295 .RE
296
297 .sp
298 .ne 2
299 .na
300 \fB\fBEOWNERDEAD\fR\fR
301 .ad
302 .RS 19n
303 The last owner of the mutex died while holding the mutex, possibly leaving the
304 state it was protecting inconsistent. The mutex is now owned by the caller.
305 .RE
306
307 .sp
308 .LP
309 These functions may fail if:
310 .sp
311 .ne 2
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
356 .sp
357 .in +2
358 .nf
359 timestruc_t to;
360 \&...
361 (void) mutex_lock(mp);
362 to.tv_sec = time(NULL) + TIMEOUT;
363 to.tv_nsec = 0;
364 while (cond == FALSE) {
365 err = cond_timedwait(cvp, mp, &to);
366 if (err == ETIME) {
367 /* timeout, do something */
368 break;
369 }
370 }
371 (void) mutex_unlock(mp);
372 .fi
373 .in -2
374
375 .LP
376 \fBExample 3 \fRUse \fBcond_reltimedwait()\fR in a loop to test some condition.
377 .sp
378 .LP
379 The \fBcond_reltimedwait()\fR function is normally used in a loop testing in
380 some condition. It uses a relative timeout value as follows:
381
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
440 either \fBcond_timedwait()\fR or \fBcond_reltimedwait()\fR returns because of a
441 timeout, it returns the error value \fBETIME\fR.