Debian Codegraph @

upstream/debian-unstable/man3/pthread_cond_init.3

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH pthread_cond_init 3 2026-03-22 "Linux man-pages 6.18"
6 .
7 .
8 .SH NAME
9 pthread_cond_init,
10 pthread_cond_signal,
11 pthread_cond_broadcast,
12 pthread_cond_wait,
13 pthread_cond_timedwait,
14 pthread_cond_destroy
15 \-
16 operations on conditions
17 .
18 .
19 .SH SYNOPSIS
20 .nf
21 .B #include <pthread.h>
22 .P
23 .BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;"
24 .P
25 .BI "int pthread_cond_init(pthread_cond_t *" cond ,
26 .BI " pthread_condattr_t *" cond_attr );
27 .BI "int pthread_cond_signal(pthread_cond_t *" cond );
28 .BI "int pthread_cond_broadcast(pthread_cond_t *" cond );
29 .BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex );
30 .BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ,
31 .BI " const struct timespec *" abstime );
32 .BI "int pthread_cond_destroy(pthread_cond_t *" cond );
33 .fi
34 .
35 .
36 .SH DESCRIPTION
37 A condition (short for "condition variable")
38 is a synchronization device that allows threads
39 to suspend execution and relinquish the processors
40 until some predicate on shared data is satisfied.
41 The basic operations on conditions are:
42 signal the condition (when the predicate becomes true),
43 and wait for the condition,
44 suspending the thread execution until another thread signals the condition.
45 .P
46 A condition variable must always be associated with a mutex,
47 to avoid the race condition where
48 a thread prepares to wait on a condition variable
49 and another thread signals the condition
50 just before the first thread actually waits on it.
51 .P
52 .BR pthread_cond_init ()
53 initializes the condition variable
54 .IR cond ,
55 using the condition attributes specified in
56 .IR cond_attr ,
57 or default attributes if
58 .I cond_attr
59 is NULL.
60 The LinuxThreads implementation supports no attributes for conditions,
61 hence the
62 .I cond_attr
63 parameter is actually ignored.
64 .P
65 Variables of type
66 .I pthread_cond_t
67 can also be initialized statically,
68 using the constant
69 .BR PTHREAD_COND_INITIALIZER .
70 .P
71 .BR pthread_cond_signal ()
72 restarts one of the threads that
73 are waiting on the condition variable
74 .IR cond .
75 If no threads are waiting on
76 .IR cond ,
77 nothing happens.
78 If several threads are waiting on
79 .IR cond ,
80 exactly one is restarted,
81 but it is not specified which.
82 .P
83 .BR pthread_cond_broadcast ()
84 restarts all the threads that
85 are waiting on the condition variable
86 .IR cond .
87 Nothing happens if no threads are waiting on
88 .IR cond .
89 .P
90 .BR pthread_cond_wait ()
91 atomically unlocks the
92 .I mutex
93 (as per
94 .BR pthread_mutex_unlock ())
95 and waits for the condition variable
96 .I cond
97 to be signaled.
98 The thread execution is suspended and does not consume any CPU time
99 until the condition variable is signaled.
100 The
101 .I mutex
102 must be locked by the calling thread
103 on entrance to
104 .BR pthread_cond_wait ().
105 Before returning to the calling thread,
106 .BR pthread_cond_wait ()
107 re-acquires
108 .I mutex
109 (as per
110 .BR pthread_mutex_lock ()).
111 .P
112 Unlocking the mutex and suspending on the condition variable is done atomically.
113 Thus,
114 if all threads always acquire the mutex before signaling the condition,
115 this guarantees that the condition cannot be signaled (and thus ignored)
116 between the time a thread locks the mutex
117 and the time it waits on the condition variable.
118 See CAVEATS below.
119 .P
120 .BR pthread_cond_timedwait ()
121 atomically unlocks
122 .I mutex
123 and waits on
124 .IR cond ,
125 as
126 .BR pthread_cond_wait ()
127 does,
128 but it also bounds the duration of the wait.
129 If
130 .I cond
131 has not been signaled
132 within the amount of time specified by
133 .IR abstime ,
134 the mutex
135 .I mutex
136 is re-acquired
137 and
138 .BR pthread_cond_timedwait ()
139 returns the error
140 .BR ETIMEDOUT .
141 The
142 .I abstime
143 parameter specifies an absolute time,
144 with the same origin as
145 .BR time (2)
146 and
147 .BR gettimeofday (2):
148 an
149 .I abstime
150 of 0
151 corresponds to 00:00:00 GMT, January 1, 1970.
152 .P
153 .BR pthread_cond_destroy ()
154 destroys a condition variable,
155 freeing the resources it might hold.
156 No threads must be waiting on the condition variable
157 on entrance to
158 .BR pthread_cond_destroy ().
159 In the LinuxThreads implementation,
160 no resources are associated with condition variables,
161 thus
162 .BR pthread_cond_destroy ()
163 actually does nothing
164 except checking that the condition has no waiting threads.
165 .
166 .
167 .SH CANCELLATION
168 .BR pthread_cond_wait ()
169 and
170 .BR pthread_cond_timedwait ()
171 are cancelation points.
172 If a thread is cancelled while suspended in one of these functions,
173 the thread immediately resumes execution,
174 then locks again the
175 .I mutex
176 argument to
177 .BR pthread_cond_wait ()
178 and
179 .BR pthread_cond_timedwait (),
180 and finally executes the cancelation.
181 Consequently,
182 cleanup handlers are assured that
183 .I mutex
184 is locked
185 when they are called.
186 .
187 .
188 .SH "ASYNC-SIGNAL SAFETY"
189 The condition functions are not async-signal safe,
190 and should not be called from a signal handler.
191 In particular,
192 calling
193 .BR pthread_cond_signal ()
194 or
195 .BR pthread_cond_broadcast ()
196 from a signal handler
197 may deadlock the calling thread.
198 .
199 .
200 .SH "RETURN VALUE"
201 All condition variable functions return 0 on success
202 and a non-zero error code on error.
203 .
204 .
205 .SH ERRORS
206 .BR pthread_cond_init (),
207 .BR pthread_cond_signal (),
208 .BR pthread_cond_broadcast (),
209 and
210 .BR pthread_cond_wait ()
211 never return an error code.
212 .P
213 The
214 .BR pthread_cond_timedwait ()
215 function returns
216 the following error codes on error:
217 .RS
218 .TP
219 .B ETIMEDOUT
220 The condition variable was not signaled
221 until the timeout specified by
222 .I abstime .
223 .RE
224 .P
225 The
226 .BR pthread_cond_destroy ()
227 function returns
228 the following error code on error:
229 .RS
230 .TP
231 .B EBUSY
232 Some threads are currently waiting on
233 .I cond .
234 .RE
235 .
236 .
237 .SH "SEE ALSO"
238 .BR pthread_condattr_init (3),
239 .BR pthread_mutex_lock (3),
240 .BR pthread_mutex_unlock (3),
241 .BR gettimeofday (2),
242 .BR nanosleep (2).
243 .
244 .SH CAVEATS
245 The implementation of the provided functions until
246 glibc 2.25 used an internal data lock.
247 This lock did not support priority-inheritance and
248 was subject to unbounded priority inversion,
249 visible on a real-time system.
250 .P
251 After the rewrite of the implementation in glibc 2.25
252 the usage of internal lock changed.
253 The internal lock is always acquired by
254 the signaling functions
255 .BR pthread_cond_signal ()
256 and
257 .BR pthread_cond_broadcast ().
258 The waiting function acquires the lock
259 if the waiting process was interrupted.
260 The interruption can be caused for instance
261 by a specified timeout,
262 and denoted by the error value
263 .BR ETIMEDOUTA ,
264 or by a received signal,
265 which is denoted by the error value
266 .BR EINTR .
267 .
268 .SH EXAMPLE
269 Consider two shared variables
270 .I x
271 and
272 .I y ,
273 protected by the mutex
274 .IR mut ,
275 and a condition variable
276 .I cond
277 that is to be signaled
278 whenever
279 .I x
280 becomes greater than
281 .IR y .
282 .P
283 .RS
284 .ft 3
285 .nf
286 .sp
287 int x,y;
288 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
289 pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
290 .ft
291 .RE
292 .fi
293 .P
294 Waiting until
295 .I x
296 is greater than
297 .I y
298 is performed as follows:
299 .P
300 .RS
301 .ft 3
302 .nf
303 .sp
304 pthread_mutex_lock(&mut);
305 while (x <= y) {
306 pthread_cond_wait(&cond, &mut);
307 }
308 /* operate on x and y */
309 pthread_mutex_unlock(&mut);
310 .ft
311 .RE
312 .fi
313 .P
314 Modifications on
315 .I x
316 and
317 .I y
318 that may cause
319 .I x
320 to become greater than
321 .I y
322 should signal the condition if needed:
323 .P
324 .RS
325 .ft 3
326 .nf
327 .sp
328 pthread_mutex_lock(&mut);
329 /* modify x and y */
330 if (x > y) pthread_cond_broadcast(&cond);
331 pthread_mutex_unlock(&mut);
332 .ft
333 .RE
334 .fi
335 .P
336 If it can be proved that at most one waiting thread needs to be waken up
337 (for instance,
338 if there are only two threads communicating through
339 .I x
340 and
341 .IR y ),
342 .BR pthread_cond_signal ()
343 can be used as
344 a slightly more efficient alternative to
345 .BR pthread_cond_broadcast ().
346 In doubt,
347 use
348 .BR pthread_cond_broadcast ().
349 .P
350 To wait for
351 .I x
352 to become greater than
353 .I y
354 with a timeout of 5 seconds,
355 do:
356 .P
357 .RS
358 .ft 3
359 .nf
360 .sp
361 struct timeval now;
362 struct timespec timeout;
363 int retcode;
364 \&
365 pthread_mutex_lock(&mut);
366 gettimeofday(&now);
367 timeout.tv_sec = now.tv_sec + 5;
368 timeout.tv_nsec = now.tv_usec * 1000;
369 retcode = 0;
370 while (x <= y && retcode != ETIMEDOUT) {
371 retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
372 }
373 if (retcode == ETIMEDOUT) {
374 /* timeout occurred */
375 } else {
376 /* operate on x and y */
377 }
378 pthread_mutex_unlock(&mut);
379 .ft
380 .RE
381 .fi