pthread_cond_wait() Is NOT Just “Wait”

Many developers believe pthread_cond_wait() simply pauses a thread until a signal arrives. This description is misleading and incomplete. In reality, it performs a critical atomic operation that makes multithreaded synchronization safe.
The Hidden Mechanics: What it Actually Does

When a thread calls pthread_cond_wait(&cond, &mutex);, the system doesn't just "stop." It performs a sequence of three steps that are bundled together:

1. Unlocks the mutex: Releases the lock so other threads can modify the shared data.

2. Puts the thread to sleep: Suspends the thread until the condition variable is signaled.

3. Re-locks the mutex: Before the function returns, the thread must compete for and re-acquire the lock.

The Fatal Flaw: Why Atomicity is Required

You might wonder: "Why can't I just unlock the mutex and wait manually?" Consider this common (but broken) logic:

// INCORRECT: The "Manual" Approach
pthread_mutex_lock(&mutex);
if (!condition) {
    pthread_mutex_unlock(&mutex); // Step A
    /* SIGNAL HAPPENS HERE */      // Step B: Race Condition!
    wait_on_condition(&cond);      // Step C
    pthread_mutex_lock(&mutex);
}

The Race Condition: If another thread signals the condition at Step B (after you unlock but before you actually start waiting), your thread will miss the signal entirely. It will then go to sleep at Step C and potentially block forever, even though the condition was met.

Because pthread_cond_wait() performs the unlock and the sleep atomically, there is no window for a signal to be missed.

The Wake-Up Protocol

When a signaling thread calls pthread_cond_signal(&cond);, the following happens for the waiting thread:

1. Wake-up: The thread is moved out of the sleep state.

2. Contention: The thread attempts to re-acquire the mutex. It cannot proceed until it successfully locks it again.

3. Return: Only once the mutex is held does the function return.

   Crucial Rule: The mutex is always held when your code resumes execution after the wait.

Why the while Loop is Mandatory:
You should never use an if statement to check your condition. Always use a while loop.

// CORRECT: The Robust Approach
pthread_mutex_lock(&mutex);
while (!condition) {
    pthread_cond_wait(&cond, &mutex);
}
/* Safe to access shared data here */
pthread_mutex_unlock(&mutex);

A while loop is required for three reasons:

1. Spurious Wakeups: On some systems, threads can wake up even if no signal was sent (a quirk of OS implementation).

2. The "Thundering Herd": Multiple threads might wake up for a single signal, but only one can "consume" the work.

3. State Change: Between the time a thread is signaled and the time it actually re-locks the mutex, another thread might have slipped in and changed the condition back to false.

pthread_cond_wait() is a sophisticated synchronization tool, not a simple pause button. By understanding the atomic handoff between the mutex and the condition variable, you can write thread-safe code that avoids the dreaded "lost wakeup" bug.

Comments

[Paul J. Lucas]

Many developers believe pthread_cond_wait() simply pauses a thread until a signal arrives.

While your article is good overall, I don't think your premise is true since all documentation for pthread_cond_wait() clearly says that it both unlocks and relocks the mutex — which explains why it takes a mutex as an argument.

Some developers might have some misunderstandings about pthread_cond_wait(), but I don't think that's one of them.