1cond_init(3C)            Standard C Library Functions            cond_init(3C)
2
3
4

NAME

6       cond_init,  cond_wait,  cond_timedwait, cond_reltimedwait, cond_signal,
7       cond_broadcast, cond_destroy - condition variables
8

SYNOPSIS

10       cc -mt [ flag... ] file... [ library... ]
11       #include <thread.h>
12       #include <synch.h>
13
14       int cond_init(cond_t *cvp, int type, void *arg);
15
16
17       int cond_wait(cond_t *cvp, mutex_t *mp);
18
19
20       int cond_timedwait(cond_t *cvp, mutex_t *mp,
21            timestruc_t *abstime);
22
23
24       int cond_reltimedwait(cond_t *cvp, mutex_t *mp,
25            timestruc_t *reltime);
26
27
28       int cond_signal(cond_t *cvp);
29
30
31       int cond_broadcast(cond_t *cvp);
32
33
34       int cond_destroy(cond_t *cvp);
35
36

DESCRIPTION

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
44
45       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
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 custom‐
60       ized 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 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
69       USYNC_THREAD     The condition variable can synchronize   threads  only
70                        in this process. This is the default.
71
72
73       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
82
83
84       Initializing condition variables can also be accomplished by allocating
85       in zeroed memory, in which case, a type of USYNC_THREAD is assumed.
86
87
88       If default condition variable attributes are used, statically allocated
89       condition variables can be initialized by the macro DEFAULTCV.
90
91
92       Default condition variable initialization (intra-process):
93
94         cond_t cvp;
95
96         cond_init(&cvp, NULL, NULL); /*initialize condition variable
97                                         with default*/
98
99
100
101       or
102
103         cond_init(&cvp, USYNC_THREAD, NULL);
104
105
106
107       or
108
109         cond_t  cond  = DEFAULTCV;
110
111
112
113       Customized condition variable initialization (inter-process):
114
115         cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
116                                                 inter-process scope */
117
118
119   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
126
127       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
133
134       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
142   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
147
148       The cond_signal() function unblocks one thread that is blocked  on  the
149       condition variable pointed to by cvp.
150
151
152       The  cond_broadcast() function unblocks all threads that are blocked on
153       the condition variable pointed to by cvp.
154
155
156       If no threads are blocked on the condition variable, then cond_signal()
157       and cond_broadcast() have no effect.
158
159
160       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
168   Destroy
169       The  condition  destroy functions destroy any state, but not the space,
170       associated with the condition variable.
171
172
173       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

RETURN VALUES

178       Upon successful completion, these functions return 0. Otherwise, a non-
179       zero value is returned to indicate the error.
180

ERRORS

182       The cond_timedwait() and cond_reltimedwait() functions will fail if:
183
184       ETIME    The time specified by abstime or reltime has passed.
185
186
187
188       The  cond_wait(),  cond_timedwait(),  and cond_reltimedwait() functions
189       will fail if:
190
191       EINTR    Interrupted. The calling thread was awakened by  the  delivery
192                of a UNIX signal.
193
194
195
196       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
202       ENOTRECOVERABLE    The mutex was protecting the state that has now been
203                          left irrecoverable. The mutex has not been acquired.
204
205
206       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
210
211
212       These functions may fail if:
213
214       EFAULT    The cond, attr, cvp, arg, abstime, or mutex  argument  points
215                 to an illegal address.
216
217
218       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
222

EXAMPLES

224       Example 1 Use cond_wait() in a loop to test some condition.
225
226
227       The  cond_wait() functin is normally used in a loop testing some condi‐
228       tion, as follows:
229
230
231         (void) mutex_lock(mp);
232         while (cond == FALSE) {
233              (void) cond_wait(cvp, mp);
234         }
235         (void) mutex_unlock(mp);
236
237
238       Example 2 Use cond_timedwait() in a loop to test some condition.
239
240
241       The cond_timedwait() function is normally used in a loop  testing  some
242       condition.  It uses an absolute timeout value as follows:
243
244
245         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
259
260       Example 3 Use cond_reltimedwait() in a loop to test some condition.
261
262
263       The  cond_reltimedwait() function is normally used in a loop testing in
264       some condition. It uses a relative timeout value as follows:
265
266
267         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
281

ATTRIBUTES

283       See attributes(5) for descriptions of the following attributes:
284
285
286
287
288       ┌─────────────────────────────┬─────────────────────────────┐
289       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
290       ├─────────────────────────────┼─────────────────────────────┤
291       │MT-Level                     │MT-Safe                      │
292       └─────────────────────────────┴─────────────────────────────┘
293

SEE ALSO

295       fork(2), mmap(2), setitimer(2), shmop(2),  mutex_init(3C),  signal(3C),
296       attributes(5), condition(5), mutex(5), standards(5)
297

NOTES

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
308
309       When cond_wait() returns the value of the  condition  is  indeterminate
310       and must be reevaluated.
311
312
313       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.
321
322
323
324SunOS 5.11                        5 Jun 2007                     cond_init(3C)
Impressum