Skip to content

pthread_cond_broadcast()

Purpose

pthread_cond_broadcast() wakes all threads currently waiting on a condition variable.

It is used when a state change may allow multiple waiting threads to proceed.

Unlike pthread_cond_signal(), which wakes a single waiter, pthread_cond_broadcast() wakes every waiting thread.

#include <pthread.h>

Prototype

int pthread_cond_broadcast(pthread_cond_t *cond);

Parameters

cond

Condition variable used for synchronization.

Example:

pthread_cond_t cond;

Return Value

Returns:

0

on success.

Otherwise returns a POSIX error code.

Typical Usage Pattern

Notifier:

pthread_mutex_lock(&lock);

shutdown_requested = true;

pthread_cond_broadcast(&cond);

pthread_mutex_unlock(&lock);

Workers:

pthread_mutex_lock(&lock);

while (!shutdown_requested)
    pthread_cond_wait(&cond,
                      &lock);

pthread_mutex_unlock(&lock);

Behavior

Conceptually:

Thread A Waiting
Thread B Waiting
Thread C Waiting
        ↓
pthread_cond_broadcast()
        ↓
Wake All Waiting Threads

Each awakened thread:

Wakeup
        ↓
Re-lock Mutex
        ↓
Recheck Condition

Why All Threads Must Recheck

After wakeup:

Condition May Be True

or:

Condition May Already Be Consumed

Therefore every thread must continue using:

while (...)

instead of:

if (...)

Example - Shutdown Notification

Worker thread:

pthread_mutex_lock(&lock);

while (!shutdown_requested)
    pthread_cond_wait(&cond,
                      &lock);

pthread_mutex_unlock(&lock);

cleanup();

Controller thread:

pthread_mutex_lock(&lock);

shutdown_requested = true;

pthread_cond_broadcast(&cond);

pthread_mutex_unlock(&lock);

All workers are awakened and exit.

Example - Global State Change

Suppose multiple threads are waiting for:

System Ready

When initialization completes:

pthread_mutex_lock(&lock);

system_ready = true;

pthread_cond_broadcast(&cond);

pthread_mutex_unlock(&lock);

All waiting threads may proceed.

broadcast() vs signal()

pthread_cond_signal()

Wake One Waiting Thread

Typical use:

Producer-consumer queue
Single work item
Single resource available

pthread_cond_broadcast()

Wake All Waiting Threads

Typical use:

Global state changes
Shutdown notification
System initialization complete

Wakeup Sequence

Assume:

Thread A Waiting
Thread B Waiting
Thread C Waiting

After:

pthread_cond_broadcast(&cond);

Conceptually:

Thread A Wakeup
Thread B Wakeup
Thread C Wakeup

However:

Only One Thread
Can Hold The Mutex
At A Time

The awakened threads still compete for the associated mutex.

Common Mistake

Incorrect:

pthread_cond_broadcast(&cond);

without updating the shared condition.

Awakened threads may immediately return to waiting.

Correct:

shutdown_requested = true;

pthread_cond_broadcast(&cond);

Common Mistake

Incorrect:

if (!shutdown_requested)
    pthread_cond_wait(&cond,
                      &lock);

Correct:

while (!shutdown_requested)
    pthread_cond_wait(&cond,
                      &lock);

The condition must always be rechecked.

Advantages

Wake All Waiters

Useful for global state transitions.

Simple Shutdown Handling

A common pattern for worker-thread termination.

Easy Coordination

Useful when many threads depend on the same condition.

Limitations

Higher Wakeup Cost

Many threads may wake simultaneously.

This can increase:

Context Switches
Mutex Contention
CPU Usage

Potential Thundering Herd

Large numbers of awakened threads may compete for the same resource.