C Reference ยท POSIX and Systems
C pthread_cond functions
Reference for condition variables: pthread_cond_wait, signal, broadcast and timedwait, why you must wait in a loop, and a producer-consumer queue example.
A condition variable lets a thread sleep until another thread announces that something has changed, without wasting CPU on polling. It is always used together with a mutex and a predicate: an ordinary variable (a flag, a count, a queue length) that is protected by that mutex and describes what the waiter is waiting for.
pthread_cond_wait() atomically unlocks the mutex and puts the thread to sleep; when it wakes up it locks the mutex again before returning. Because wake-ups can be spurious and another thread may consume the condition first, you must always wait in a loop that rechecks the predicate.
pthread_mutex_lock(&m); while (!ready) { pthread_cond_wait(&cv, &m); } /* ready is true here, and we hold the mutex */ pthread_mutex_unlock(&m);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
#include <pthread.h> int pthread_cond_init(pthread_cond_t *restrict cond, const pthread_condattr_t *restrict attr); int pthread_cond_destroy(pthread_cond_t *cond); int pthread_cond_wait(pthread_cond_t *restrict cond, pthread_mutex_t *restrict mutex); int pthread_cond_timedwait(pthread_cond_t *restrict cond, pthread_mutex_t *restrict mutex, const struct timespec *restrict abstime); int pthread_cond_signal(pthread_cond_t *cond); int pthread_cond_broadcast(pthread_cond_t *cond); pthread_cond_t cv = PTHREAD_COND_INITIALIZER; /* static initialization */
| Name | Description |
|---|---|
cond |
The condition variable. |
mutex |
A mutex the caller has locked; it is released while waiting. |
abstime |
(timedwait) Absolute deadline, by default against CLOCK_REALTIME. |
Returns: 0 on success, an error number otherwise. timedwait returns ETIMEDOUT when the deadline passes (the mutex is still re-acquired).
Usage notes
- Always loop on the predicate.
while (!ready) wait(...), neverif. Wake-ups can be spurious, and a signal sent before the waiter started waiting is lost, so the predicate, not the signal, is the truth. - Change the predicate while holding the mutex, then signal. Signalling without changing shared state first, or changing state without the lock, creates lost wake-ups.
signalwakes at least one waiter;broadcastwakes all of them. Usebroadcastwhen waiters wait for different conditions on the same variable, or when several may proceed (for example "shutdown").- Use one condition variable per condition (
not_fullandnot_emptyabove) so a signal does not wake the wrong kind of waiter. - Calling
signalwhile holding the mutex is always correct. Signalling after unlocking can save a context switch, and is also correct if the predicate was already changed under the lock. - Every waiter of one condition variable must pass the same mutex.
- Do not destroy a condition variable while threads are waiting on it.
- For timeouts compute the deadline once from
clock_gettime(CLOCK_REALTIME)plus the delay; recomputing it inside the loop restarts the timer. - C11 provides
cnd_wait,cnd_signalandcnd_broadcastin threads.h.
Related
- pthread_mutex, pthread_create, threads.h
- Tutorial: Threads