Debian Codegraph @

upstream/debian-trixie/man3/pthread_cond_init.3

raw
1 .\" Copyright, Xavier Leroy <[email protected]>
2 .\" Copyright 2023, Alejandro Colomar <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_cond_init 3 2024-06-16 "Linux man-pages 6.9.1"
7 .
8 .
9 .SH NAME
10 pthread_cond_init,
11 pthread_cond_signal,
12 pthread_cond_broadcast,
13 pthread_cond_wait,
14 pthread_cond_timedwait,
15 pthread_cond_destroy
16 \-
17 operations on conditions
18 .
19 .
20 .SH SYNOPSIS
21 .nf
22 .B #include <pthread.h>
23 .P
24 .BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;"
25 .P
26 .BI "int pthread_cond_init(pthread_cond_t *" cond ,
27 .BI " pthread_condattr_t *" cond_attr );
28 .BI "int pthread_cond_signal(pthread_cond_t *" cond );
29 .BI "int pthread_cond_broadcast(pthread_cond_t *" cond );
30 .BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex );
31 .BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ,
32 .BI " const struct timespec *" abstime );
33 .BI "int pthread_cond_destroy(pthread_cond_t *" cond );
34 .fi
35 .
36 .
37 .SH DESCRIPTION
38 A condition (short for ``condition variable'')
39 is a synchronization device that allows threads
40 to suspend execution and relinquish the processors
41 until some predicate on shared data is satisfied.
42 The basic operations on conditions are:
43 signal the condition (when the predicate becomes true),
44 and wait for the condition,
45 suspending the thread execution until another thread signals the condition.
46 .P
47 A condition variable must always be associated with a mutex,
48 to avoid the race condition where
49 a thread prepares to wait on a condition variable
50 and another thread signals the condition
51 just before the first thread actually waits on it.
52 .P
53 \fBpthread_cond_init\fP initializes the condition variable \fIcond\fP,
54 using the condition attributes specified in \fIcond_attr\fP,
55 or default attributes if \fIcond_attr\fP is \fBNULL\fP.
56 The LinuxThreads implementation supports no attributes for conditions,
57 hence the \fIcond_attr\fP parameter is actually ignored.
58 .P
59 Variables of type \fBpthread_cond_t\fP can also be initialized statically,
60 using the constant \fBPTHREAD_COND_INITIALIZER\fP.
61 .P
62 \fBpthread_cond_signal\fP restarts one of the threads that
63 are waiting on the condition variable \fIcond\fP.
64 If no threads are waiting on \fIcond\fP,
65 nothing happens.
66 If several threads are waiting on \fIcond\fP,
67 exactly one is restarted,
68 but it is not specified which.
69 .P
70 \fBpthread_cond_broadcast\fP restarts all the threads that
71 are waiting on the condition variable \fIcond\fP.
72 Nothing happens if no threads are waiting on \fIcond\fP.
73 .P
74 \fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP
75 (as per \fBpthread_unlock_mutex\fP)
76 and waits for the condition variable \fIcond\fP to be signaled.
77 The thread execution is suspended and does not consume any CPU time
78 until the condition variable is signaled.
79 The \fImutex\fP must be locked by the calling thread
80 on entrance to \fBpthread_cond_wait\fP.
81 Before returning to the calling thread,
82 \fBpthread_cond_wait\fP re-acquires \fImutex\fP
83 (as per \fBpthread_lock_mutex\fP).
84 .P
85 Unlocking the mutex and suspending on the condition variable is done atomically.
86 Thus,
87 if all threads always acquire the mutex before signaling the condition,
88 this guarantees that the condition cannot be signaled (and thus ignored)
89 between the time a thread locks the mutex
90 and the time it waits on the condition variable.
91 .P
92 \fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP
93 and waits on \fIcond\fP,
94 as \fBpthread_cond_wait\fP does,
95 but it also bounds the duration of the wait.
96 If \fIcond\fP has not been signaled
97 within the amount of time specified by \fIabstime\fP,
98 the mutex \fImutex\fP is re-acquired
99 and \fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP.
100 The \fIabstime\fP parameter specifies an absolute time,
101 with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2):
102 an \fIabstime\fP of 0
103 corresponds to 00:00:00 GMT, January 1, 1970.
104 .P
105 \fBpthread_cond_destroy\fP destroys a condition variable,
106 freeing the resources it might hold.
107 No threads must be waiting on the condition variable
108 on entrance to \fBpthread_cond_destroy\fP.
109 In the LinuxThreads implementation,
110 no resources are associated with condition variables,
111 thus \fBpthread_cond_destroy\fP actually does nothing
112 except checking that the condition has no waiting threads.
113 .
114 .
115 .SH CANCELLATION
116 \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP
117 are cancelation points.
118 If a thread is cancelled while suspended in one of these functions,
119 the thread immediately resumes execution,
120 then locks again the \fImutex\fP
121 argument to \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP,
122 and finally executes the cancelation.
123 Consequently,
124 cleanup handlers are assured that \fImutex\fP is locked
125 when they are called.
126 .
127 .
128 .SH "ASYNC-SIGNAL SAFETY"
129 The condition functions are not async-signal safe,
130 and should not be called from a signal handler.
131 In particular,
132 calling \fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP
133 from a signal handler
134 may deadlock the calling thread.
135 .
136 .
137 .SH "RETURN VALUE"
138 All condition variable functions return 0 on success
139 and a non-zero error code on error.
140 .
141 .
142 .SH ERRORS
143 \fBpthread_cond_init\fP,
144 \fBpthread_cond_signal\fP,
145 \fBpthread_cond_broadcast\fP,
146 and \fBpthread_cond_wait\fP
147 never return an error code.
148 .P
149 The \fBpthread_cond_timedwait\fP function returns
150 the following error codes on error:
151 .RS
152 .TP
153 \fBETIMEDOUT\fP
154 The condition variable was not signaled
155 until the timeout specified by \fIabstime\fP.
156 .TP
157 \fBEINTR\fP
158 \fBpthread_cond_timedwait\fP was interrupted by a signal.
159 .RE
160 .P
161 The \fBpthread_cond_destroy\fP function returns
162 the following error code on error:
163 .RS
164 .TP
165 \fBEBUSY\fP
166 Some threads are currently waiting on \fIcond\fP.
167 .RE
168 .
169 .
170 .SH "SEE ALSO"
171 \fBpthread_condattr_init\fP(3),
172 \fBpthread_mutex_lock\fP(3),
173 \fBpthread_mutex_unlock\fP(3),
174 \fBgettimeofday\fP(2),
175 \fBnanosleep\fP(2).
176 .
177 .
178 .SH EXAMPLE
179 Consider two shared variables \fIx\fP and \fIy\fP,
180 protected by the mutex \fImut\fP,
181 and a condition variable \fIcond\fP
182 that is to be signaled
183 whenever \fIx\fP becomes greater than \fIy\fP.
184 .P
185 .RS
186 .ft 3
187 .nf
188 .sp
189 int x,y;
190 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
191 pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
192 .ft
193 .RE
194 .fi
195 .P
196 Waiting until \fIx\fP is greater than \fIy\fP is performed as follows:
197 .P
198 .RS
199 .ft 3
200 .nf
201 .sp
202 pthread_mutex_lock(&mut);
203 while (x <= y) {
204 pthread_cond_wait(&cond, &mut);
205 }
206 /* operate on x and y */
207 pthread_mutex_unlock(&mut);
208 .ft
209 .RE
210 .fi
211 .P
212 Modifications on \fIx\fP and \fIy\fP
213 that may cause \fIx\fP to become greater than \fIy\fP
214 should signal the condition if needed:
215 .P
216 .RS
217 .ft 3
218 .nf
219 .sp
220 pthread_mutex_lock(&mut);
221 /* modify x and y */
222 if (x > y) pthread_cond_broadcast(&cond);
223 pthread_mutex_unlock(&mut);
224 .ft
225 .RE
226 .fi
227 .P
228 If it can be proved that at most one waiting thread needs to be waken up
229 (for instance,
230 if there are only two threads communicating through \fIx\fP and \fIy\fP),
231 \fBpthread_cond_signal\fP can be used as
232 a slightly more efficient alternative to \fBpthread_cond_broadcast\fP.
233 In doubt,
234 use \fBpthread_cond_broadcast\fP.
235 .P
236 To wait for \fIx\fP to become greater than \fIy\fP
237 with a timeout of 5 seconds,
238 do:
239 .P
240 .RS
241 .ft 3
242 .nf
243 .sp
244 struct timeval now;
245 struct timespec timeout;
246 int retcode;
247 \&
248 pthread_mutex_lock(&mut);
249 gettimeofday(&now);
250 timeout.tv_sec = now.tv_sec + 5;
251 timeout.tv_nsec = now.tv_usec * 1000;
252 retcode = 0;
253 while (x <= y && retcode != ETIMEDOUT) {
254 retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
255 }
256 if (retcode == ETIMEDOUT) {
257 /* timeout occurred */
258 } else {
259 /* operate on x and y */
260 }
261 pthread_mutex_unlock(&mut);
262 .ft
263 .RE
264 .fi