Penguin
Recent Changes
Blame: pthread_cond_init(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of pthread_cond_init(3) version 1 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 JohnMcPherson 1 !!NAME
2 pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait - operations on conditions
3
4
5
6 !!SYNOPSIS
7 __#include <pthread.h>__
8
9 __pthread_cond_t __ ''cond'' __ = PTHREAD_COND_INITIALIZER;__
10
11 __int pthread_cond_init(pthread_cond_t *__ ''cond'' __, pthread_condattr_t *__ ''cond_attr'' __);__
12
13 __int pthread_cond_signal(pthread_cond_t *__ ''cond'' __);__
14
15 __int pthread_cond_broadcast(pthread_cond_t *__ ''cond'' __);__
16
17 __int pthread_cond_wait(pthread_cond_t *__ ''cond'' __, pthread_mutex_t *__ ''mutex'' __);__
18
19 __int pthread_cond_timedwait(pthread_cond_t *__ ''cond'' __, pthread_mutex_t *__ ''mutex'' __, const struct timespec *__ ''abstime'' __);__
20
21 __int pthread_cond_destroy(pthread_cond_t *__ ''cond'' __);__
22
23
24 !!DESCRIPTION
25
26
27 A condition (short for "condition variable") is a synchronization device that allows threads to suspend execution and relinquish the processors until some predicate on shared data is satisfied. The basic operations on conditions are: signal the condition (when the predicate becomes true), and wait for the condition, suspending the thread execution until another thread signals the condition.
28
29 A condition variable must always be associated with a mutex, to avoid the race condition where a thread prepares to wait on a condition variable and another thread signals the condition just before the first thread actually waits on it.
30
31 __pthread_cond_init__ initializes the condition variable ''cond'' , using the condition attributes specified in ''cond_attr'' , or default attributes if ''cond_attr'' is __NULL__ . The ~LinuxThreads implementation supports no attributes for conditions, hence the ''cond_attr'' parameter is actually ignored.
32
33 Variables of type __pthread_cond_t__ can also be initialized statically, using the constant __PTHREAD_COND_INITIALIZER__ .
34
35 __pthread_cond_signal__ restarts one of the threads that are waiting on the condition variable ''cond'' . If no threads are waiting on ''cond'' , nothing happens. If several threads are waiting on ''cond'' , exactly one is restarted, but it is not specified which.
36
37 __pthread_cond_broadcast__ restarts all the threads that are waiting on the condition variable ''cond'' . Nothing happens if no threads are waiting on ''cond'' .
38
39 __pthread_cond_wait__ atomically unlocks the ''mutex'' (as per __pthread_unlock_mutex__ ) and waits for the condition variable ''cond'' to be signaled. The thread execution is suspended and does not consume any CPU time until the condition variable is signaled. The ''mutex'' must be locked by the calling thread on entrance to __pthread_cond_wait__ . Before returning to the calling thread, __pthread_cond_wait__ re-acquires ''mutex'' (as per __pthread_lock_mutex__ ).
40
41 Unlocking the mutex and suspending on the condition variable is done atomically. Thus, if all threads always acquire the mutex before signaling the condition, this guarantees that the condition cannot be signaled (and thus ignored) between the time a thread locks the mutex and the time it waits on the condition variable.
42
43 __pthread_cond_timedwait__ atomically unlocks ''mutex'' and waits on ''cond'' , as __pthread_cond_wait__ does, but it also bounds the duration of the wait. If ''cond'' has not been signaled within the amount of time specified by ''abstime'' , the mutex ''mutex'' is re-acquired and __pthread_cond_timedwait__ returns the error __ETIMEDOUT__ . The ''abstime'' parameter specifies an absolute time, with the same origin as time(2) and gettimeofday(2): an ''abstime'' of 0 corresponds to 00:00:00 GMT, January 1, 1970.
44
45 __pthread_cond_destroy__ destroys a condition variable, freeing the resources it might hold. No threads must be waiting on the condition variable on entrance to __pthread_cond_destroy__ . In the ~LinuxThreads implementation, no resources are associated with condition variables, thus __pthread_cond_destroy__ actually does nothing except checking that the condition has no waiting threads.
46
47
48
49 !!CANCELLATION
50 __pthread_cond_wait__ and __pthread_cond_timedwait__ are cancellation points. If a thread is cancelled while suspended in one of these functions, the thread immediately resumes execution, then locks again the ''mutex'' argument to __pthread_cond_wait__ and __pthread_cond_timedwait__ , and finally executes the cancellation. Consequently, cleanup handlers are assured that ''mutex'' is locked when they are called.
51
52
53
54 !!ASYNC-SIGNAL SAFETY
55 The condition functions are not async-signal safe, and should not be called from a signal handler. In particular, calling __pthread_cond_signal__ or __pthread_cond_broadcast__ from a signal handler may deadlock the calling thread.
56
57
58
59 !!RETURN VALUE
60 All condition variable functions return 0 on success and a non-zero error code on error.
61
62
63 !!ERRORS
64 __pthread_cond_init__, __pthread_cond_signal__, __pthread_cond_broadcast__, and __pthread_cond_wait__ never return an error code.
65
66 The __pthread_cond_timedwait__ function returns the following error codes on error:
67
68 ;__ETIMEDOUT__: the condition variable was not signaled until the timeout specified by ''abstime''
69
70
71 ;__EINTR__: __pthread_cond_timedwait__ was interrupted by a signal
72
73
74 The __pthread_cond_destroy__ function returns the following error code on error:
75
76 ;__EBUSY__: some threads are currently waiting on ''cond'' .
77
78
79
80
81 !!AUTHOR
82 Xavier Leroy <Xavier.Leroy@inria.fr>
83
84
85
86 !!SEE ALSO
87 pthread_condattr_init(3), pthread_mutex_lock(3), pthread_mutex_unlock(3), gettimeofday(2), nanosleep(2).
88
89
90
91 !!EXAMPLE
92 Consider two shared variables ''x'' and ''y'', protected by the mutex ''mut'' , and a condition variable ''cond'' that is to be signaled whenever ''x'' becomes greater than ''y''.
93
94
95
96
97
98 %%%
99 int x,y; %%%
100 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; %%%
101 pthread_cond_t cond = PTHREAD_COND_INITIALIZER; %%%
102
103 %%%
104
105 %%%
106
107
108
109 Waiting until ''x'' is greater than ''y'' is performed as follows:
110
111
112
113 %%%
114 pthread_mutex_lock(&mut); %%%
115 while (x <= y) { %%%
116
117 pthread_cond_wait(&cond, &mut); %%%
118 } %%%
119 /* operate on x and y */ %%%
120 pthread_mutex_unlock(&mut); %%%
121
122 %%%
123
124 %%%
125
126
127
128 Modifications on ''x'' and ''y'' that may cause ''x'' to become greater than ''y'' should signal the condition if needed:
129
130
131
132
133
134 %%%
135 pthread_mutex_lock(&mut); %%%
136 /* modify x and y */ %%%
137 if (x > y) pthread_cond_broadcast(&cond); %%%
138 pthread_mutex_unlock(&mut); %%%
139
140
141
142
143 If it can be proved that at most one waiting thread needs to be waken up (for instance, if there are only two threads communicating through ''x'' and ''y'' ), __pthread_cond_signal__ can be used as a slightly more efficient alternative to __pthread_cond_broadcast__ . In doubt, use __pthread_cond_broadcast__ .
144
145 To wait for ''x'' to becomes greater than ''y'' with a timeout of 5 seconds, do:
146
147 <verbatim>
148 struct timeval now;
149 struct timespec timeout;
150 int retcode;
151
152 pthread_mutex_lock(&mut);
153 gettimeofday(&now);
154 timeout.tv_sec = now.tv_sec + 5;
155 timeout.tv_nsec = now.tv_usec * 1000;
156 retcode = 0;
157 while (x <= y && retcode != ETIMEDOUT) {
158 retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
159 }
160 if (retcode == ETIMEDOUT) {
161 /* timeout occurred */
162 } else {
163 /* operate on x and y */
164 }
165 pthread_mutex_unlock(&mut);
166 </verbatim>
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.