1 .TH PTHREAD_COND 3 LinuxThreads
5 pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait \- operations on conditions
8 .B #include <pthread.h>
10 .BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;"
12 .BI "int pthread_cond_init(pthread_cond_t *" cond ", pthread_condattr_t *" cond_attr ");"
14 .BI "int pthread_cond_signal(pthread_cond_t *" cond ");"
16 .BI "int pthread_cond_broadcast(pthread_cond_t *" cond ");"
18 .BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ");"
20 .BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ", const struct timespec *" abstime ");"
22 .BI "int pthread_cond_destroy(pthread_cond_t *" cond ");"
26 A condition (short for ``condition variable'') is a synchronization
27 device that allows threads to suspend execution and relinquish the
28 processors until some predicate on shared data is satisfied. The basic
29 operations on conditions are: signal the condition (when the
30 predicate becomes true), and wait for the condition, suspending the
31 thread execution until another thread signals the condition.
33 A condition variable must always be associated with a mutex, to avoid
34 the race condition where a thread prepares to wait on a condition
35 variable and another thread signals the condition just before the
36 first thread actually waits on it.
38 .B "pthread_cond_init"
39 initializes the condition variable
42 condition attributes specified in
49 The LinuxThreads implementation supports no
50 attributes for conditions, hence the
57 can also be initialized
58 statically, using the constant
59 .BR "PTHREAD_COND_INITIALIZER" .
61 .B "pthread_cond_signal"
62 restarts one of the threads that are waiting on
63 the condition variable
65 If no threads are waiting on
67 nothing happens. If several threads are waiting on
70 is restarted, but it is not specified which.
72 .B "pthread_cond_broadcast"
73 restarts all the threads that are waiting on
74 the condition variable
76 Nothing happens if no threads are
80 .B "pthread_cond_wait"
81 atomically unlocks the
84 .BR "pthread_unlock_mutex" )
85 and waits for the condition variable
88 be signaled. The thread execution is suspended and does not consume
89 any CPU time until the condition variable is signaled. The
91 must be locked by the calling thread on entrance to
92 .BR "pthread_cond_wait" .
93 Before returning to the calling thread,
94 .B "pthread_cond_wait"
98 .BR "pthread_lock_mutex" ).
100 Unlocking the mutex and suspending on the condition variable is done
101 atomically. Thus, if all threads always acquire the mutex before
102 signaling the condition, this guarantees that the condition cannot be
103 signaled (and thus ignored) between the time a thread locks the mutex
104 and the time it waits on the condition variable.
106 .B "pthread_cond_timedwait"
112 .B "pthread_cond_wait"
113 does, but it also bounds the duration
116 has not been signaled within the amount of time
122 .B "pthread_cond_timedwait"
127 parameter specifies an absolute time, with the same
131 .BR "gettimeofday" (2):
135 corresponds to 00:00:00 GMT, January 1, 1970.
137 .B "pthread_cond_destroy"
138 destroys a condition variable, freeing the
139 resources it might hold. No threads must be waiting on the condition
140 variable on entrance to
141 .BR "pthread_cond_destroy" .
143 implementation, no resources are associated with condition variables,
145 .B "pthread_cond_destroy"
146 actually does nothing except checking that
147 the condition has no waiting threads.
151 .B "pthread_cond_wait"
153 .B "pthread_cond_timedwait"
155 points. If a thread is cancelled while suspended in one of these
156 functions, the thread immediately resumes execution, then locks again
160 .B "pthread_cond_wait"
162 .BR "pthread_cond_timedwait" ,
163 and finally executes the cancellation.
164 Consequently, cleanup handlers are assured that
169 .SH "ASYNC-SIGNAL SAFETY"
171 The condition functions are not async-signal safe, and should not be
172 called from a signal handler. In particular, calling
173 .B "pthread_cond_signal"
175 .B "pthread_cond_broadcast"
177 handler may deadlock the calling thread.
181 All condition variable functions return 0 on success and a non-zero
186 .BR "pthread_cond_init" ,
187 .BR "pthread_cond_signal" ,
188 .BR "pthread_cond_broadcast" ,
190 .B "pthread_cond_wait"
191 never return an error code.
194 .B "pthread_cond_timedwait"
195 function returns the following error codes
200 the condition variable was not signaled until the timeout specified by
205 .B "pthread_cond_timedwait"
206 was interrupted by a signal
210 .B "pthread_cond_destroy"
211 function returns the following error code
216 some threads are currently waiting on
221 Xavier Leroy <Xavier.Leroy@inria.fr>
224 .BR "pthread_condattr_init" (3),
225 .BR "pthread_mutex_lock" (3),
226 .BR "pthread_mutex_unlock" (3),
227 .BR "gettimeofday" (2),
232 Consider two shared variables
236 protected by the mutex
238 and a condition variable
240 that is to be signaled whenever
250 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
251 pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
261 is performed as follows:
267 pthread_mutex_lock(&mut);
269 pthread_cond_wait(&cond, &mut);
271 /* operate on x and y */
272 pthread_mutex_unlock(&mut);
284 to become greater than
286 should signal the condition if needed:
292 pthread_mutex_lock(&mut);
294 if (x > y) pthread_cond_broadcast(&cond);
295 pthread_mutex_unlock(&mut);
301 If it can be proved that at most one waiting thread needs to be waken
302 up (for instance, if there are only two threads communicating through
306 .B "pthread_cond_signal"
307 can be used as a slightly more
308 efficient alternative to
309 .BR "pthread_cond_broadcast" .
311 .BR "pthread_cond_broadcast" .
315 to becomes greater than
325 struct timespec timeout;
328 pthread_mutex_lock(&mut);
330 timeout.tv_sec = now.tv_sec + 5;
331 timeout.tv_nsec = now.tv_usec * 1000;
333 while (x <= y && retcode != ETIMEDOUT) {
334 retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
336 if (retcode == ETIMEDOUT) {
337 /* timeout occurred */
339 /* operate on x and y */
341 pthread_mutex_unlock(&mut);