1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>PTHREAD_COND(3) manual page</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
<META NAME="CREATED" CONTENT="20050504;16454400">
<META NAME="CHANGED" CONTENT="20050505;19004700">
<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at http://polyglotman.sourceforge.net/ -->
</HEAD>
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
<H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
<P><A HREF="index.html">Reference Index</A></P>
<P><A HREF="#toc">Table of Contents</A></P>
<H2><A HREF="#toc0" NAME="sect0">Name</A></H2>
<P>pthread_cond_init, pthread_cond_destroy, pthread_cond_signal,
pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait -
operations on conditions
</P>
<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
<P><B>#include <pthread.h></B>
</P>
<P><B>pthread_cond_t </B><I>cond</I> <B>= PTHREAD_COND_INITIALIZER;</B>
</P>
<P><B>int pthread_cond_init(pthread_cond_t *</B><I>cond</I><B>,
pthread_condattr_t *</B><I>cond_attr</I><B>);</B>
</P>
<P><B>int pthread_cond_signal(pthread_cond_t *</B><I>cond</I><B>);</B>
</P>
<P><B>int pthread_cond_broadcast(pthread_cond_t *</B><I>cond</I><B>);</B>
</P>
<P><B>int pthread_cond_wait(pthread_cond_t *</B><I>cond</I><B>,
pthread_mutex_t *</B><I>mutex</I><B>);</B>
</P>
<P><B>int pthread_cond_timedwait(pthread_cond_t *</B><I>cond</I><B>,
pthread_mutex_t *</B><I>mutex</I><B>, const struct timespec
*</B><I>abstime</I><B>);</B>
</P>
<P><B>int pthread_cond_destroy(pthread_cond_t *</B><I>cond</I><B>);</B>
</P>
<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
<P>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.
</P>
<P>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.
</P>
<P><B>pthread_cond_init</B> initializes the condition variable <I>cond</I>,
using the condition attributes specified in <I>cond_attr</I>, or
default attributes if <I>cond_attr</I> is <B>NULL</B>.
</P>
<P>Variables of type <B>pthread_cond_t</B> can also be initialized
statically, using the constant <B>PTHREAD_COND_INITIALIZER</B>. In
the <B>Pthreads-w32</B> implementation, an application should still
call <B>pthread_cond_destroy</B> at some point to ensure that any
resources consumed by the condition variable are released.</P>
<P><B>pthread_cond_signal</B> restarts one of the threads that are
waiting on the condition variable <I>cond</I>. If no threads are
waiting on <I>cond</I>, nothing happens. If several threads are
waiting on <I>cond</I>, exactly one is restarted, but it is not
specified which.
</P>
<P><B>pthread_cond_broadcast</B> restarts all the threads that are
waiting on the condition variable <I>cond</I>. Nothing happens if no
threads are waiting on <I>cond</I>.
</P>
<P><B>pthread_cond_wait</B> atomically unlocks the <I>mutex</I> (as
per <B>pthread_unlock_mutex</B>) and waits for the condition variable
<I>cond</I> to be signalled. The thread execution is suspended and
does not consume any CPU time until the condition variable is
signalled. The <I>mutex</I> must be locked by the calling thread on
entrance to <B>pthread_cond_wait</B>. Before returning to the calling
thread, <B>pthread_cond_wait</B> re-acquires <I>mutex</I> (as per
<B>pthread_lock_mutex</B>).
</P>
<P>Unlocking the mutex and suspending on the condition variable is
done atomically. Thus, if all threads always acquire the mutex before
signalling the condition, this guarantees that the condition cannot
be signalled (and thus ignored) between the time a thread locks the
mutex and the time it waits on the condition variable.
</P>
<P><B>pthread_cond_timedwait</B> atomically unlocks <I>mutex</I> and
waits on <I>cond</I>, as <B>pthread_cond_wait</B> does, but it also
bounds the duration of the wait. If <I>cond</I> has not been
signalled within the amount of time specified by <I>abstime</I>, the
mutex <I>mutex</I> is re-acquired and <B>pthread_cond_timedwait</B>
returns the error <B>ETIMEDOUT</B>. The <I>abstime</I> parameter
specifies an absolute time, with the same origin as <A HREF="time.html"><B>time</B>(2)</A>
and <A HREF="gettimeofday.html"><B>gettimeofday</B>(2)</A>.
</P>
<P><B>pthread_cond_destroy</B> destroys a condition variable, freeing
the resources it might hold. No threads must be waiting on the
condition variable on entrance to <B>pthread_cond_destroy</B>.</P>
<H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
<P><B>pthread_cond_wait</B> and <B>pthread_cond_timedwait</B> are
cancellation points. If a thread is cancelled while suspended in one
of these functions, the thread immediately resumes execution, then
locks again the <I>mutex</I> argument to <B>pthread_cond_wait</B> and
<B>pthread_cond_timedwait</B>, and finally executes the cancellation.
Consequently, cleanup handlers are assured that <I>mutex</I> is
locked when they are called.
</P>
<H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2>
<P>The condition functions are not async-signal safe, and should not
be called from a signal handler. In particular, calling
<B>pthread_cond_signal</B> or <B>pthread_cond_broadcast</B> from a
signal handler may deadlock the calling thread.
</P>
<H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2>
<P>All condition variable functions return 0 on success and a
non-zero error code on error.
</P>
<H2><A HREF="#toc6" NAME="sect6">Errors</A></H2>
<P><B>pthread_cond_init</B>, <B>pthread_cond_signal</B>,
<B>pthread_cond_broadcast</B>, and <B>pthread_cond_wait</B> never
return an error code.
</P>
<P>The <B>pthread_cond_init</B> function returns the following error
codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
The <I>cond</I> argument is invalid.
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<B>ENOMEM</B>
</DT></DL>
</DL>
<BLOCKQUOTE STYLE="margin-left: 4cm">
There was not enough memory to allocate the condition variable.
</BLOCKQUOTE>
<P>The <B>pthread_cond_signal</B> function returns the following
error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
The <I>cond</I> argument is invalid.
</DD></DL>
</DL>
<P>
The <B>pthread_cond_broadcast</B> function returns the following
error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
The <I>cond</I> argument is invalid.
</DD></DL>
</DL>
<P>
The <B>pthread_cond_wait</B> function returns the following error
codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
The <I>cond</I> argument is invalid.
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<B>ENOMEM</B>
</DT></DL>
</DL>
<BLOCKQUOTE STYLE="margin-left: 4cm">
There was not enough memory to allocate the statically initialised
condition variable. Statically initialised condition variables are
dynamically allocated by the first thread to wait on them.</BLOCKQUOTE>
<P>The <B>pthread_cond_timedwait</B> function returns the following
error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT></DL>
</DL>
<P STYLE="margin-left: 2cm">
The <I>cond</I> argument is invalid.
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
The condition variable was not signalled before the timeout
specified by <I>abstime</I>
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<B>ENOMEM</B>
</DT></DL>
</DL>
<BLOCKQUOTE STYLE="margin-left: 4cm">
There was not enough memory to allocate the statically initialised
condition variable. Statically initialised condition variables are
dynamically allocated by the first thread to wait on them.
</BLOCKQUOTE>
<P>The <B>pthread_cond_destroy</B> function returns the following
error code on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT></DL>
</DL>
<P STYLE="margin-left: 2cm; margin-right: 1cm">
The <I>cond</I> argument is invalid.
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
Some threads are currently waiting on <I>cond</I>.
</DD></DL>
</DL>
<H2>
<A HREF="#toc7" NAME="sect7">Author</A></H2>
<P>Xavier Leroy <Xavier.Leroy@inria.fr>
</P>
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
<H2><A HREF="#toc8" NAME="sect8">See Also</A></H2>
<P><A HREF="pthread_condattr_init.html"><B>pthread_condattr_init</B>(3)</A>
, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
, <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
, <A HREF="pthread_cancel.html"><B>pthread_cancel(3)</B></A>.
</P>
<H2><A HREF="#toc9" NAME="sect9">Example</A></H2>
<P>Consider two shared variables <I>x</I> and <I>y</I>, protected by
the mutex <I>mut</I>, and a condition variable <I>cond</I> that is to
be signaled whenever <I>x</I> becomes greater than <I>y</I>.
</P>
<PRE STYLE="margin-left: 1cm; margin-right: 1cm">int x,y;
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;</PRE><BLOCKQUOTE>
Waiting until <I>x</I> is greater than <I>y</I> is performed as
follows:
</BLOCKQUOTE>
<PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&mut);
while (x <= y) {
pthread_cond_wait(&cond, &mut);
}
/* operate on x and y */
pthread_mutex_unlock(&mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
Modifications on <I>x</I> and <I>y</I> that may cause <I>x</I> to
become greater than <I>y</I> should signal the condition if needed:
</BLOCKQUOTE>
<PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&mut);
/* modify x and y */
if (x > y) pthread_cond_broadcast(&cond);
pthread_mutex_unlock(&mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
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
<I>x</I> and <I>y</I>), <B>pthread_cond_signal</B> can be used as a
slightly more efficient alternative to <B>pthread_cond_broadcast</B>.
If in doubt, use <B>pthread_cond_broadcast</B>.
</BLOCKQUOTE>
<BLOCKQUOTE STYLE="margin-left: 3.01cm">To wait for <I>x</I> to
become greater than <I>y</I> with a timeout of 5 seconds, do:
</BLOCKQUOTE>
<PRE STYLE="margin-left: 1.01cm">struct timeval now;
struct timespec timeout;
int retcode;
pthread_mutex_lock(&mut);
gettimeofday(&now);
timeout.tv_sec = now.tv_sec + 5;
timeout.tv_nsec = now.tv_usec * 1000;
retcode = 0;
while (x <= y && retcode != ETIMEDOUT) {
retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
}
if (retcode == ETIMEDOUT) {
/* timeout occurred */
} else {
/* operate on x and y */
}
pthread_mutex_unlock(&mut);</PRE>
<HR>
<BLOCKQUOTE STYLE="margin-left: 0cm; margin-right: 0cm"><A NAME="toc"></A>
<B>Table of Contents</B></BLOCKQUOTE>
<UL>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal
Safety</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return
Value</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">See
Also</A>
</BLOCKQUOTE>
<LI><BLOCKQUOTE STYLE="margin-right: 0cm"><A HREF="#sect9" NAME="toc9">Example</A>
</BLOCKQUOTE>
</UL>
</BODY>
</HTML>
|
