Skip to content
Tutorials Center
My learning

Topics

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.

C
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

C Waiting for a flag

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.

C A bounded queue with a producer and a consumer

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

C
#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(...), never if. 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.
  • signal wakes at least one waiter; broadcast wakes all of them. Use broadcast when waiters wait for different conditions on the same variable, or when several may proceed (for example "shutdown").
  • Use one condition variable per condition (not_full and not_empty above) so a signal does not wake the wrong kind of waiter.
  • Calling signal while 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_signal and cnd_broadcast in threads.h.