45 The scope of a condition variable is either intra-process or inter-
46 process. This is dependent upon whether the argument is passed
47 implicitly or explicitly to the initialization of that condition
48 variable. A condition variable does not need to be explicitly
49 initialized. A condition variable is initialized with all zeros, by
50 default, and its scope is set to within the calling process. For inter-
51 process synchronization, a condition variable must be initialized once,
52 and only once, before use.
53
54
55 A condition variable must not be simultaneously initialized by multiple
56 threads or re-initialized while in use by other threads.
57
58
59 Attributes of condition variables can be set to the default or
60 customized at initialization.
61
62
63 The cond_init() function initializes the condition variable pointed to
64 by cvp. A condition variable can have several different types of
65 behavior, specified by type. No current type uses arg although a
66 future type may specify additional behavior parameters with arg. The
67 type argument c take one of the following values:
68
69 USYNC_THREAD
70 The condition variable can synchronize threads only
71 in this process. This is the default.
72
73
74 USYNC_PROCESS
75 The condition variable can synchronize threads in this
76 process and other processes. Only one process should
77 initialize the condition variable. The object
78 initialized with this attribute must be allocated in
79 memory shared between processes, either in System V
80 shared memory (see shmop(2)) or in memory mapped to a
81 file (see mmap(2)). It is illegal to initialize the
82 object this way and to not allocate it in such shared
83 memory.
84
85
86
87 Initializing condition variables can also be accomplished by allocating
88 in zeroed memory, in which case, a type of USYNC_THREAD is assumed.
89
90
91 If default condition variable attributes are used, statically allocated
113
114
115
116 Customized condition variable initialization (inter-process):
117
118 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
119 inter-process scope */
120
121
122 Condition Wait
123 The condition wait interface allows a thread to wait for a condition
124 and atomically release the associated mutex that it needs to hold to
125 check the condition. The thread waits for another thread to make the
126 condition true and that thread's resulting call to signal and wakeup
127 the waiting thread.
128
129
130 The cond_wait() function atomically releases the mutex pointed to by mp
131 and causes the calling thread to block on the condition variable
132 pointed to by cvp. The blocked thread may be awakened by cond_signal(),
133 cond_broadcast(), or when interrupted by delivery of a UNIX signal or
134 a fork().
135
136
137 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
138 always return with the mutex locked and owned by the calling thread
139 even when returning an error, except when the mutex has the LOCK_ROBUST
140 attribute and has been left irrecoverable by the mutex's last owner.
141 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
142 return the appropriate error value if they fail to internally reacquire
143 the mutex.
144
145 Condition Signaling
146 A condition signal allows a thread to unblock a single thread waiting
147 on the condition variable, whereas a condition broadcast allows a
148 thread to unblock all threads waiting on the condition variable.
149
150
151 The cond_signal() function unblocks one thread that is blocked on the
152 condition variable pointed to by cvp.
153
154
217
218
219
220 These functions may fail if:
221
222 EFAULT
223 The cond, attr, cvp, arg, abstime, or mutex argument points
224 to an illegal address.
225
226
227 EINVAL
228 Invalid argument. For cond_init(), type is not a recognized
229 type. For cond_timedwait(), the number of nanoseconds is
230 greater than or equal to 1,000,000,000.
231
232
233 EXAMPLES
234 Example 1 Use cond_wait() in a loop to test some condition.
235
236
237 The cond_wait() functin is normally used in a loop testing some
238 condition, as follows:
239
240
241 (void) mutex_lock(mp);
242 while (cond == FALSE) {
243 (void) cond_wait(cvp, mp);
244 }
245 (void) mutex_unlock(mp);
246
247
248 Example 2 Use cond_timedwait() in a loop to test some condition.
249
250
251 The cond_timedwait() function is normally used in a loop testing some
252 condition. It uses an absolute timeout value as follows:
253
254
255 timestruc_t to;
256 ...
257 (void) mutex_lock(mp);
314 cond_wait(), cond_timedwait(), or cond_reltimedwait(). The thread(s)
315 that are unblocked compete for the mutex according to the scheduling
316 policy and as if each had called mutex_lock(3C).
317
318
319 When cond_wait() returns the value of the condition is indeterminate
320 and must be reevaluated.
321
322
323 The cond_timedwait() and cond_reltimedwait() functions are similar to
324 cond_wait(), except that the calling thread will not wait for the
325 condition to become true past the absolute time specified by abstime or
326 the relative time specified by reltime. Note that cond_timedwait() or
327 cond_reltimedwait() might continue to block as it trys to reacquire the
328 mutex pointed to by mp, which may be locked by another thread. If
329 either cond_timedwait() or cond_reltimedwait() returns because of a
330 timeout, it returns the error value ETIME.
331
332
333
334 June 5, 2007 COND_INIT(3C)
|
45 The scope of a condition variable is either intra-process or inter-
46 process. This is dependent upon whether the argument is passed
47 implicitly or explicitly to the initialization of that condition
48 variable. A condition variable does not need to be explicitly
49 initialized. A condition variable is initialized with all zeros, by
50 default, and its scope is set to within the calling process. For inter-
51 process synchronization, a condition variable must be initialized once,
52 and only once, before use.
53
54
55 A condition variable must not be simultaneously initialized by multiple
56 threads or re-initialized while in use by other threads.
57
58
59 Attributes of condition variables can be set to the default or
60 customized at initialization.
61
62
63 The cond_init() function initializes the condition variable pointed to
64 by cvp. A condition variable can have several different types of
65 behavior, 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
69 USYNC_THREAD
70 The condition variable can synchronize threads only in
71 this process. This is the default.
72
73
74 USYNC_PROCESS
75 The condition variable can synchronize threads in this
76 process and other processes. Only one process should
77 initialize the condition variable. The object
78 initialized with this attribute must be allocated in
79 memory shared between processes, either in System V
80 shared memory (see shmop(2)) or in memory mapped to a
81 file (see mmap(2)). It is illegal to initialize the
82 object this way and to not allocate it in such shared
83 memory.
84
85
86
87 Initializing condition variables can also be accomplished by allocating
88 in zeroed memory, in which case, a type of USYNC_THREAD is assumed.
89
90
91 If default condition variable attributes are used, statically allocated
113
114
115
116 Customized condition variable initialization (inter-process):
117
118 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
119 inter-process scope */
120
121
122 Condition Wait
123 The condition wait interface allows a thread to wait for a condition
124 and atomically release the associated mutex that it needs to hold to
125 check the condition. The thread waits for another thread to make the
126 condition true and that thread's resulting call to signal and wakeup
127 the waiting thread.
128
129
130 The cond_wait() function atomically releases the mutex pointed to by mp
131 and causes the calling thread to block on the condition variable
132 pointed to by cvp. The blocked thread may be awakened by cond_signal(),
133 cond_broadcast(), or when interrupted by delivery of a UNIX signal or a
134 fork().
135
136
137 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
138 always return with the mutex locked and owned by the calling thread
139 even when returning an error, except when the mutex has the LOCK_ROBUST
140 attribute and has been left irrecoverable by the mutex's last owner.
141 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
142 return the appropriate error value if they fail to internally reacquire
143 the mutex.
144
145 Condition Signaling
146 A condition signal allows a thread to unblock a single thread waiting
147 on the condition variable, whereas a condition broadcast allows a
148 thread to unblock all threads waiting on the condition variable.
149
150
151 The cond_signal() function unblocks one thread that is blocked on the
152 condition variable pointed to by cvp.
153
154
217
218
219
220 These functions may fail if:
221
222 EFAULT
223 The cond, attr, cvp, arg, abstime, or mutex argument points
224 to an illegal address.
225
226
227 EINVAL
228 Invalid argument. For cond_init(), type is not a recognized
229 type. For cond_timedwait(), the number of nanoseconds is
230 greater than or equal to 1,000,000,000.
231
232
233 EXAMPLES
234 Example 1 Use cond_wait() in a loop to test some condition.
235
236
237 The cond_wait() function is normally used in a loop testing some
238 condition, as follows:
239
240
241 (void) mutex_lock(mp);
242 while (cond == FALSE) {
243 (void) cond_wait(cvp, mp);
244 }
245 (void) mutex_unlock(mp);
246
247
248 Example 2 Use cond_timedwait() in a loop to test some condition.
249
250
251 The cond_timedwait() function is normally used in a loop testing some
252 condition. It uses an absolute timeout value as follows:
253
254
255 timestruc_t to;
256 ...
257 (void) mutex_lock(mp);
314 cond_wait(), cond_timedwait(), or cond_reltimedwait(). The thread(s)
315 that are unblocked compete for the mutex according to the scheduling
316 policy and as if each had called mutex_lock(3C).
317
318
319 When cond_wait() returns the value of the condition is indeterminate
320 and must be reevaluated.
321
322
323 The cond_timedwait() and cond_reltimedwait() functions are similar to
324 cond_wait(), except that the calling thread will not wait for the
325 condition to become true past the absolute time specified by abstime or
326 the relative time specified by reltime. Note that cond_timedwait() or
327 cond_reltimedwait() might continue to block as it trys to reacquire the
328 mutex pointed to by mp, which may be locked by another thread. If
329 either cond_timedwait() or cond_reltimedwait() returns because of a
330 timeout, it returns the error value ETIME.
331
332
333
334 February 15, 2020 COND_INIT(3C)
|