Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/cond_init.3c.man.txt
+++ new/usr/src/man/man3c/cond_init.3c.man.txt
1 1 COND_INIT(3C) Standard C Library Functions COND_INIT(3C)
2 2
3 3
4 4
5 5 NAME
6 6 cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal,
7 7 cond_broadcast, cond_destroy - condition variables
8 8
9 9 SYNOPSIS
10 10 cc -mt [ flag... ] file... [ library... ]
11 11 #include <thread.h>
12 12 #include <synch.h>
13 13
14 14 int cond_init(cond_t *cvp, int type, void *arg);
15 15
16 16
17 17 int cond_wait(cond_t *cvp, mutex_t *mp);
18 18
19 19
20 20 int cond_timedwait(cond_t *cvp, mutex_t *mp,
21 21 timestruc_t *abstime);
22 22
23 23
24 24 int cond_reltimedwait(cond_t *cvp, mutex_t *mp,
25 25 timestruc_t *reltime);
26 26
27 27
28 28 int cond_signal(cond_t *cvp);
29 29
30 30
31 31 int cond_broadcast(cond_t *cvp);
32 32
33 33
34 34 int cond_destroy(cond_t *cvp);
35 35
36 36
37 37 DESCRIPTION
38 38 Initialize
39 39 Condition variables and mutexes should be global. Condition variables
40 40 that are allocated in writable memory can synchronize threads among
41 41 processes if they are shared by the cooperating processes (see mmap(2))
42 42 and are initialized for this purpose.
43 43
44 44
45 45 The scope of a condition variable is either intra-process or inter-
46 46 process. This is dependent upon whether the argument is passed
47 47 implicitly or explicitly to the initialization of that condition
48 48 variable. A condition variable does not need to be explicitly
49 49 initialized. A condition variable is initialized with all zeros, by
50 50 default, and its scope is set to within the calling process. For inter-
51 51 process synchronization, a condition variable must be initialized once,
52 52 and only once, before use.
53 53
54 54
|
↓ open down ↓ |
54 lines elided |
↑ open up ↑ |
55 55 A condition variable must not be simultaneously initialized by multiple
56 56 threads or re-initialized while in use by other threads.
57 57
58 58
59 59 Attributes of condition variables can be set to the default or
60 60 customized at initialization.
61 61
62 62
63 63 The cond_init() function initializes the condition variable pointed to
64 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:
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 68
69 69 USYNC_THREAD
70 - The condition variable can synchronize threads only
71 - in this process. This is the default.
70 + The condition variable can synchronize threads only in
71 + this process. This is the default.
72 72
73 73
74 74 USYNC_PROCESS
75 75 The condition variable can synchronize threads in this
76 76 process and other processes. Only one process should
77 77 initialize the condition variable. The object
78 78 initialized with this attribute must be allocated in
79 79 memory shared between processes, either in System V
80 80 shared memory (see shmop(2)) or in memory mapped to a
81 81 file (see mmap(2)). It is illegal to initialize the
82 82 object this way and to not allocate it in such shared
83 83 memory.
84 84
85 85
86 86
87 87 Initializing condition variables can also be accomplished by allocating
88 88 in zeroed memory, in which case, a type of USYNC_THREAD is assumed.
89 89
90 90
91 91 If default condition variable attributes are used, statically allocated
92 92 condition variables can be initialized by the macro DEFAULTCV.
93 93
94 94
95 95 Default condition variable initialization (intra-process):
96 96
97 97 cond_t cvp;
98 98
99 99 cond_init(&cvp, NULL, NULL); /*initialize condition variable
100 100 with default*/
101 101
102 102
103 103
104 104 or
105 105
106 106 cond_init(&cvp, USYNC_THREAD, NULL);
107 107
108 108
109 109
110 110 or
111 111
112 112 cond_t cond = DEFAULTCV;
113 113
114 114
115 115
116 116 Customized condition variable initialization (inter-process):
117 117
118 118 cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
119 119 inter-process scope */
120 120
121 121
122 122 Condition Wait
|
↓ open down ↓ |
41 lines elided |
↑ open up ↑ |
123 123 The condition wait interface allows a thread to wait for a condition
124 124 and atomically release the associated mutex that it needs to hold to
125 125 check the condition. The thread waits for another thread to make the
126 126 condition true and that thread's resulting call to signal and wakeup
127 127 the waiting thread.
128 128
129 129
130 130 The cond_wait() function atomically releases the mutex pointed to by mp
131 131 and causes the calling thread to block on the condition variable
132 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().
133 + cond_broadcast(), or when interrupted by delivery of a UNIX signal or a
134 + fork().
135 135
136 136
137 137 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
138 138 always return with the mutex locked and owned by the calling thread
139 139 even when returning an error, except when the mutex has the LOCK_ROBUST
140 140 attribute and has been left irrecoverable by the mutex's last owner.
141 141 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
142 142 return the appropriate error value if they fail to internally reacquire
143 143 the mutex.
144 144
145 145 Condition Signaling
146 146 A condition signal allows a thread to unblock a single thread waiting
147 147 on the condition variable, whereas a condition broadcast allows a
148 148 thread to unblock all threads waiting on the condition variable.
149 149
150 150
151 151 The cond_signal() function unblocks one thread that is blocked on the
152 152 condition variable pointed to by cvp.
153 153
154 154
155 155 The cond_broadcast() function unblocks all threads that are blocked on
156 156 the condition variable pointed to by cvp.
157 157
158 158
159 159 If no threads are blocked on the condition variable, then cond_signal()
160 160 and cond_broadcast() have no effect.
161 161
162 162
163 163 The cond_signal() or cond_broadcast() functions can be called by a
164 164 thread whether or not it currently owns the mutex that threads calling
165 165 cond_wait(), cond_timedwait(), or cond_reltimedwait() have associated
166 166 with the condition variable during their waits. If, however,
167 167 predictable scheduling behavior is required, then that mutex should be
168 168 locked by the thread prior to calling cond_signal() or
169 169 cond_broadcast().
170 170
171 171 Destroy
172 172 The condition destroy functions destroy any state, but not the space,
173 173 associated with the condition variable.
174 174
175 175
176 176 The cond_destroy() function destroys any state associated with the
177 177 condition variable pointed to by cvp. The space for storing the
178 178 condition variable is not freed.
179 179
180 180 RETURN VALUES
181 181 Upon successful completion, these functions return 0. Otherwise, a non-
182 182 zero value is returned to indicate the error.
183 183
184 184 ERRORS
185 185 The cond_timedwait() and cond_reltimedwait() functions will fail if:
186 186
187 187 ETIME
188 188 The time specified by abstime or reltime has passed.
189 189
190 190
191 191
192 192 The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions
193 193 will fail if:
194 194
195 195 EINTR
196 196 Interrupted. The calling thread was awakened by the delivery
197 197 of a UNIX signal.
198 198
199 199
200 200
201 201 If the mutex pointed to by mp is a robust mutex (initialized with the
202 202 LOCK_ROBUST attribute), the cond_wait(), cond_timedwait() and
203 203 cond_reltimedwait() functions will, under the specified conditions,
|
↓ open down ↓ |
59 lines elided |
↑ open up ↑ |
204 204 return the following error values. For complete information, see the
205 205 description of the mutex_lock() function on the mutex_init(3C) manual
206 206 page.
207 207
208 208 ENOTRECOVERABLE
209 209 The mutex was protecting the state that has now been
210 210 left irrecoverable. The mutex has not been acquired.
211 211
212 212
213 213 EOWNERDEAD
214 - The last owner of the mutex died while holding the
214 + The last owner of the mutex died while holding the
215 215 mutex, possibly leaving the state it was protecting
216 216 inconsistent. The mutex is now owned by the caller.
217 217
218 218
219 219
220 220 These functions may fail if:
221 221
222 222 EFAULT
223 223 The cond, attr, cvp, arg, abstime, or mutex argument points
224 224 to an illegal address.
225 225
226 226
|
↓ open down ↓ |
2 lines elided |
↑ open up ↑ |
227 227 EINVAL
228 228 Invalid argument. For cond_init(), type is not a recognized
229 229 type. For cond_timedwait(), the number of nanoseconds is
230 230 greater than or equal to 1,000,000,000.
231 231
232 232
233 233 EXAMPLES
234 234 Example 1 Use cond_wait() in a loop to test some condition.
235 235
236 236
237 - The cond_wait() functin is normally used in a loop testing some
237 + The cond_wait() function is normally used in a loop testing some
238 238 condition, as follows:
239 239
240 240
241 241 (void) mutex_lock(mp);
242 242 while (cond == FALSE) {
243 243 (void) cond_wait(cvp, mp);
244 244 }
245 245 (void) mutex_unlock(mp);
246 246
247 247
248 248 Example 2 Use cond_timedwait() in a loop to test some condition.
249 249
250 250
251 251 The cond_timedwait() function is normally used in a loop testing some
252 252 condition. It uses an absolute timeout value as follows:
253 253
254 254
255 255 timestruc_t to;
256 256 ...
257 257 (void) mutex_lock(mp);
258 258 to.tv_sec = time(NULL) + TIMEOUT;
259 259 to.tv_nsec = 0;
260 260 while (cond == FALSE) {
261 261 err = cond_timedwait(cvp, mp, &to);
262 262 if (err == ETIME) {
263 263 /* timeout, do something */
264 264 break;
265 265 }
266 266 }
267 267 (void) mutex_unlock(mp);
268 268
269 269
270 270 Example 3 Use cond_reltimedwait() in a loop to test some condition.
271 271
272 272
273 273 The cond_reltimedwait() function is normally used in a loop testing in
274 274 some condition. It uses a relative timeout value as follows:
275 275
276 276
277 277 timestruc_t to;
278 278 ...
279 279 (void) mutex_lock(mp);
280 280 while (cond == FALSE) {
281 281 to.tv_sec = TIMEOUT;
282 282 to.tv_nsec = 0;
283 283 err = cond_reltimedwait(cvp, mp, &to);
284 284 if (err == ETIME) {
285 285 /* timeout, do something */
286 286 break;
287 287 }
288 288 }
289 289 (void) mutex_unlock(mp);
290 290
291 291
292 292 ATTRIBUTES
293 293 See attributes(5) for descriptions of the following attributes:
294 294
295 295
296 296
297 297
298 298 +---------------+-----------------+
299 299 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
300 300 +---------------+-----------------+
301 301 |MT-Level | MT-Safe |
302 302 +---------------+-----------------+
303 303
304 304 SEE ALSO
305 305 fork(2), mmap(2), setitimer(2), shmop(2), mutex_init(3C), signal(3C),
306 306 attributes(5), condition(5), mutex(5), standards(5)
307 307
308 308 NOTES
309 309 If more than one thread is blocked on a condition variable, the order
310 310 in which threads are unblocked is determined by the scheduling policy.
311 311 When each thread, unblocked as a result of a cond_signal() or
312 312 cond_broadcast(), returns from its call to cond_wait() or
313 313 cond_timedwait() , the thread owns the mutex with which it called
314 314 cond_wait(), cond_timedwait(), or cond_reltimedwait(). The thread(s)
315 315 that are unblocked compete for the mutex according to the scheduling
316 316 policy and as if each had called mutex_lock(3C).
317 317
318 318
319 319 When cond_wait() returns the value of the condition is indeterminate
320 320 and must be reevaluated.
321 321
322 322
323 323 The cond_timedwait() and cond_reltimedwait() functions are similar to
|
↓ open down ↓ |
76 lines elided |
↑ open up ↑ |
324 324 cond_wait(), except that the calling thread will not wait for the
325 325 condition to become true past the absolute time specified by abstime or
326 326 the relative time specified by reltime. Note that cond_timedwait() or
327 327 cond_reltimedwait() might continue to block as it trys to reacquire the
328 328 mutex pointed to by mp, which may be locked by another thread. If
329 329 either cond_timedwait() or cond_reltimedwait() returns because of a
330 330 timeout, it returns the error value ETIME.
331 331
332 332
333 333
334 - June 5, 2007 COND_INIT(3C)
334 + February 15, 2020 COND_INIT(3C)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX