summary refs log tree commit diff
path: root/linuxthreads/man/pthread_cond_init.man
blob: 4913062fd21d74e5aacfe2b7aa88d029b1ebf3d2 (plain) (blame)
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
.TH PTHREAD_COND 3 LinuxThreads

.XREF pthread_cond_signal
.XREF pthread_cond_broadcast
.XREF pthread_cond_wait
.XREF pthread_cond_timedwait
.XREF pthread_cond_destroy

.SH NAME
pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait \- operations on conditions

.SH SYNOPSIS
#include <pthread.h>

pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *cond_attr);

int pthread_cond_signal(pthread_cond_t *cond);

int pthread_cond_broadcast(pthread_cond_t *cond);

int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);

int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);

int pthread_cond_destroy(pthread_cond_t *cond);

.SH DESCRIPTION

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.

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.

!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.

Variables of type !pthread_cond_t! can also be initialized
statically, using the constant !PTHREAD_COND_INITIALIZER!.

!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.

!pthread_cond_broadcast! restarts all the threads that are waiting on
the condition variable |cond|. Nothing happens if no threads are
waiting on |cond|.

!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!).

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.

!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.

!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.

.SH CANCELLATION

!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.

.SH "ASYNC-SIGNAL SAFETY"

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.

.SH "RETURN VALUE"

All condition variable functions return 0 on success and a non-zero
error code on error.

.SH ERRORS

!pthread_cond_init!, !pthread_cond_signal!, !pthread_cond_broadcast!,
and !pthread_cond_wait! never return an error code.

The !pthread_cond_timedwait! function returns the following error codes
on error:
.RS
.TP
!ETIMEDOUT!
the condition variable was not signaled until the timeout specified by
|abstime|

.TP
!EINTR!
!pthread_cond_timedwait! was interrupted by a signal
.RE

The !pthread_cond_destroy! function returns the following error code
on error:
.RS
.TP
!EBUSY!
some threads are currently waiting on |cond|.
.RE

.SH AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>

.SH "SEE ALSO"
!pthread_condattr_init!(3),
!pthread_mutex_lock!(3),
!pthread_mutex_unlock!(3),
!gettimeofday!(2),
!nanosleep!(2).

.SH EXAMPLE

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|.

.RS
.ft 3
.nf
.sp
int x,y;
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
.ft
.LP
.RE
.fi

Waiting until |x| is greater than |y| is performed as follows:

.RS
.ft 3
.nf
.sp
pthread_mutex_lock(&mut);
while (x <= y) {
        pthread_cond_wait(&cond, &mut);
}
/* operate on x and y */
pthread_mutex_unlock(&mut);
.ft
.LP
.RE
.fi

Modifications on |x| and |y| that may cause |x| to become greater than
|y| should signal the condition if needed:

.RS
.ft 3
.nf
.sp
pthread_mutex_lock(&mut);
/* modify x and y */
if (x > y) pthread_cond_broadcast(&cond);
pthread_mutex_unlock(&mut);
.ft
.LP
.RE
.fi

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!.

To wait for |x| to becomes greater than |y| with a timeout of 5
seconds, do:

.RS
.ft 3
.nf
.sp
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);
.ft
.LP
.RE
.fi