pthread_cond_signal()¶

Purpose¶

pthread_cond_signal() wakes one thread currently waiting on a condition variable.

It is typically used to notify a single waiting thread that a shared condition may have changed.

#include <pthread.h>

Prototype¶

int pthread_cond_signal(pthread_cond_t *cond);

Parameters¶

cond¶

Condition variable used for synchronization.

Example:

pthread_cond_t cond;

Return Value¶

Returns:

on success.

Otherwise returns a POSIX error code.

Typical Usage Pattern¶

Producer:

pthread_mutex_lock(&lock);

condition = true;

pthread_cond_signal(&cond);

pthread_mutex_unlock(&lock);

Consumer:

pthread_mutex_lock(&lock);

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

pthread_mutex_unlock(&lock);

Behavior¶

Conceptually:

Waiting Thread
        ↓
pthread_cond_wait()
        ↓
Sleep

Another thread:

Update Condition
        ↓
pthread_cond_signal()
        ↓
Wake One Thread

The awakened thread:

Wakeup
        ↓
Re-lock Mutex
        ↓
Continue

One Thread Is Woken¶

If multiple threads are waiting:

Thread A
Thread B
Thread C

then:

pthread_cond_signal(&cond);

wakes:

One Waiting Thread

The specific thread selected is implementation-dependent.

Producer-Consumer Example¶

Producer:

pthread_mutex_lock(&lock);

queue_push(item);

pthread_cond_signal(&cond);

pthread_mutex_unlock(&lock);

Consumer:

pthread_mutex_lock(&lock);

while (queue_empty())
    pthread_cond_wait(&cond,
                      &lock);

item = queue_pop();

pthread_mutex_unlock(&lock);

Why Signal While Holding Mutex?¶

Recommended pattern:

pthread_mutex_lock(&lock);

condition = true;

pthread_cond_signal(&cond);

pthread_mutex_unlock(&lock);

This ensures:

State Update
        ↓
Notification

occurs in a well-defined order.

Signal Does Not Store State¶

A condition variable is not an event queue.

Incorrect assumption:

signal()
        ↓
wait()
        ↓
Wakeup Guaranteed

This is false.

Condition variables only notify threads that are already waiting.

The shared condition must always be checked separately.

Common Mistake¶

Incorrect:

pthread_cond_signal(&cond);

without updating the associated condition.

A waiting thread may wake up and immediately go back to sleep.

Correct:

condition = true;

pthread_cond_signal(&cond);

Common Mistake¶

Incorrect:

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

The waiting thread must still use:

while (...)

because wakeup does not guarantee the condition remains true.

signal() vs broadcast()¶