1cond_init(3C) Standard C Library Functions cond_init(3C)
2
6 cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal,
7 cond_broadcast, cond_destroy - condition variables
8
10 cc -mt [ flag... ] file... [ library... ]
11 #include <thread.h>
12 #include <synch.h>
13 int cond_init(cond_t *cvp, int type, void *arg);
15 int cond_wait(cond_t *cvp, mutex_t *mp);
18 int cond_timedwait(cond_t *cvp, mutex_t *mp,
21 timestruc_t *abstime);
22 int cond_reltimedwait(cond_t *cvp, mutex_t *mp,
25 timestruc_t *reltime);
26 int cond_signal(cond_t *cvp);
29 int cond_broadcast(cond_t *cvp);
32 int cond_destroy(cond_t *cvp);
35
38 Initialize
39 Condition variables and mutexes should be global. Condition variables
40 that are allocated in writable memory can synchronize threads among
41 processes if they are shared by the cooperating processes (see mmap(2))
42 and are initialized for this purpose.
43 The scope of a condition variable is either intra-process or inter-
46 process. This is dependent upon whether the argument is passed implic‐
47 itly or explicitly to the initialization of that condition variable. A
48 condition variable does not need to be explicitly initialized. A condi‐
49 tion variable is initialized with all zeros, by default, and its scope
50 is set to within the calling process. For inter-process synchroniza‐
51 tion, a condition variable must be initialized once, and only once,
52 before use.
53 A condition variable must not be simultaneously initialized by multiple
56 threads or re-initialized while in use by other threads.
57 Attributes of condition variables can be set to the default or custom‐
60 ized at initialization.
61 The cond_init() function initializes the condition variable pointed to
64 by cvp. A condition variable can have several different types of behav‐
65 ior, specified by type. No current type uses arg although a future
66 type may specify additional behavior parameters with arg. The type
67 argument c take one of the following values:
68 USYNC_THREAD The condition variable can synchronize threads only
70 in this process. This is the default.
71 USYNC_PROCESS The condition variable can synchronize threads in this
74 process and other processes. Only one process should
75 initialize the condition variable. The object initial‐
76 ized with this attribute must be allocated in memory
77 shared between processes, either in System V shared
78 memory (see shmop(2)) or in memory mapped to a file
79 (see mmap(2)). It is illegal to initialize the object
80 this way and to not allocate it in such shared memory.
81 Initializing condition variables can also be accomplished by allocating
85 in zeroed memory, in which case, a type of USYNC_THREAD is assumed.
86 If default condition variable attributes are used, statically allocated
89 condition variables can be initialized by the macro DEFAULTCV.
90 Default condition variable initialization (intra-process):
93 cond_t cvp;
95 cond_init(&cvp, NULL, NULL); /*initialize condition variable
97 with default*/
98 or
102 cond_init(&cvp, USYNC_THREAD, NULL);
104 or
108 cond_t cond = DEFAULTCV;
110 Customized condition variable initialization (inter-process):
114 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
116 inter-process scope */
117 Condition Wait
120 The condition wait interface allows a thread to wait for a condition
121 and atomically release the associated mutex that it needs to hold to
122 check the condition. The thread waits for another thread to make the
123 condition true and that thread's resulting call to signal and wakeup
124 the waiting thread.
125 The cond_wait() function atomically releases the mutex pointed to by mp
128 and causes the calling thread to block on the condition variable
129 pointed to by cvp. The blocked thread may be awakened by cond_signal(),
130 cond_broadcast(), or when interrupted by delivery of a UNIX signal or
131 a fork().
132 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
135 always return with the mutex locked and owned by the calling thread
136 even when returning an error, except when the mutex has the LOCK_ROBUST
137 attribute and has been left irrecoverable by the mutex's last owner.
138 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
139 return the appropriate error value if they fail to internally reacquire
140 the mutex.
141 Condition Signaling
143 A condition signal allows a thread to unblock a single thread waiting
144 on the condition variable, whereas a condition broadcast allows a
145 thread to unblock all threads waiting on the condition variable.
146 The cond_signal() function unblocks one thread that is blocked on the
149 condition variable pointed to by cvp.
150 The cond_broadcast() function unblocks all threads that are blocked on
153 the condition variable pointed to by cvp.
154 If no threads are blocked on the condition variable, then cond_signal()
157 and cond_broadcast() have no effect.
158 The cond_signal() or cond_broadcast() functions can be called by a
161 thread whether or not it currently owns the mutex that threads calling
162 cond_wait(), cond_timedwait(), or cond_reltimedwait() have associated
163 with the condition variable during their waits. If, however, pre‐
164 dictable scheduling behavior is required, then that mutex should be
165 locked by the thread prior to calling cond_signal() or cond_broad‐
166 cast().
167 Destroy
169 The condition destroy functions destroy any state, but not the space,
170 associated with the condition variable.
171 The cond_destroy() function destroys any state associated with the con‐
174 dition variable pointed to by cvp. The space for storing the condition
175 variable is not freed.
176
178 Upon successful completion, these functions return 0. Otherwise, a non-
179 zero value is returned to indicate the error.
180
182 The cond_timedwait() and cond_reltimedwait() functions will fail if:
183 ETIME The time specified by abstime or reltime has passed.
185 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
189 will fail if:
190 EINTR Interrupted. The calling thread was awakened by the delivery
192 of a UNIX signal.
193 If the mutex pointed to by mp is a robust mutex (initialized with the
197 LOCK_ROBUST attribute), the cond_wait(), cond_timedwait() and cond_rel‐
198 timedwait() functions will, under the specified conditions, return the
199 following error values. For complete information, see the description
200 of the mutex_lock() function on the mutex_init(3C) manual page.
201 ENOTRECOVERABLE The mutex was protecting the state that has now been
203 left irrecoverable. The mutex has not been acquired.
204 EOWNERDEAD The last owner of the mutex died while holding the
207 mutex, possibly leaving the state it was protecting
208 inconsistent. The mutex is now owned by the caller.
209 These functions may fail if:
213 EFAULT The cond, attr, cvp, arg, abstime, or mutex argument points
215 to an illegal address.
216 EINVAL Invalid argument. For cond_init(), type is not a recognized
219 type. For cond_timedwait(), the number of nanoseconds is
220 greater than or equal to 1,000,000,000.
221
224 Example 1 Use cond_wait() in a loop to test some condition.
225 The cond_wait() functin is normally used in a loop testing some condi‐
228 tion, as follows:
229 (void) mutex_lock(mp);
232 while (cond == FALSE) {
233 (void) cond_wait(cvp, mp);
234 }
235 (void) mutex_unlock(mp);
236 Example 2 Use cond_timedwait() in a loop to test some condition.
239 The cond_timedwait() function is normally used in a loop testing some
242 condition. It uses an absolute timeout value as follows:
243 timestruc_t to;
246 ...
247 (void) mutex_lock(mp);
248 to.tv_sec = time(NULL) + TIMEOUT;
249 to.tv_nsec = 0;
250 while (cond == FALSE) {
251 err = cond_timedwait(cvp, mp, &to);
252 if (err == ETIME) {
253 /* timeout, do something */
254 break;
255 }
256 }
257 (void) mutex_unlock(mp);
258 Example 3 Use cond_reltimedwait() in a loop to test some condition.
261 The cond_reltimedwait() function is normally used in a loop testing in
264 some condition. It uses a relative timeout value as follows:
265 timestruc_t to;
268 ...
269 (void) mutex_lock(mp);
270 while (cond == FALSE) {
271 to.tv_sec = TIMEOUT;
272 to.tv_nsec = 0;
273 err = cond_reltimedwait(cvp, mp, &to);
274 if (err == ETIME) {
275 /* timeout, do something */
276 break;
277 }
278 }
279 (void) mutex_unlock(mp);
280
283 See attributes(5) for descriptions of the following attributes:
284 ┌─────────────────────────────┬─────────────────────────────┐
289 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
290 ├─────────────────────────────┼─────────────────────────────┤
291 │MT-Level │MT-Safe │
292 └─────────────────────────────┴─────────────────────────────┘
293
295 fork(2), mmap(2), setitimer(2), shmop(2), mutex_init(3C), signal(3C),
296 attributes(5), condition(5), mutex(5), standards(5)
297
299 If more than one thread is blocked on a condition variable, the order
300 in which threads are unblocked is determined by the scheduling policy.
301 When each thread, unblocked as a result of a cond_signal() or
302 cond_broadcast(), returns from its call to cond_wait() or cond_timed‐
303 wait() , the thread owns the mutex with which it called cond_wait(),
304 cond_timedwait(), or cond_reltimedwait(). The thread(s) that are
305 unblocked compete for the mutex according to the scheduling policy and
306 as if each had called mutex_lock(3C).
307 When cond_wait() returns the value of the condition is indeterminate
310 and must be reevaluated.
311 The cond_timedwait() and cond_reltimedwait() functions are similar to
314 cond_wait(), except that the calling thread will not wait for the con‐
315 dition to become true past the absolute time specified by abstime or
316 the relative time specified by reltime. Note that cond_timedwait() or
317 cond_reltimedwait() might continue to block as it trys to reacquire the
318 mutex pointed to by mp, which may be locked by another thread. If
319 either cond_timedwait() or cond_reltimedwait() returns because of a
320 timeout, it returns the error value ETIME.
321SunOS 5.11 5 Jun 2007 cond_init(3C)