Operating SystemsPthread Condition Variables

Pthread Condition Variables

LevelAdvanced

Duration120 mins

TopicPthread Condition Variables

5 / 5

Proper Usage Patterns

The Art of Condition Variable Usage

Having explored each pthread condition variable function individually, this page synthesizes everything into production-ready patterns that represent industry best practices.

Condition variables are deceptively simple—four functions, straightforward semantics. Yet they are among the most error-prone synchronization primitives. The difference between correct and subtly broken code often lies in adherence to established patterns.

This page presents:

The Canonical Pattern — The fundamental template for all condition variable usage
Standard Idioms — Time-tested implementations of common synchronization needs
Defensive Patterns — Techniques for robustness in production environments
Anti-Patterns — Common mistakes and how to avoid them
Testing Strategies — Approaches for validating concurrent code

Master these patterns, and you will write condition variable code that is correct by construction.

Learning Objectives

By completing this page, you will: (1) Internalize the canonical while-loop wait pattern, (2) Implement producer-consumer, readers-writers, and thread pool patterns correctly, (3) Apply defensive techniques for error handling and shutdown, (4) Recognize and avoid common anti-patterns, (5) Know strategies for testing condition variable code, and (6) Achieve production-level proficiency in pthread condition variable usage.

The Canonical Pattern

Every correct use of condition variables follows the same fundamental template. This template handles spurious wakeups, lost signals, and all edge cases.

The Template

canonical_pattern.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
#include <pthread.h>
#include <stdbool.h>
 
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
 
// Your shared state (the "condition" being waited on)
bool condition_predicate = false;  // Replace with your actual condition
 
/*
 * ========================================================
 * THE CANONICAL CONDITION VARIABLE PATTERN
 * ========================================================
 *
 * This pattern is MANDATORY for correctness. Deviation leads to bugs.
 * Memorize it. Apply it without exception.
 */
 
// WAITER: Thread that waits for condition to become true
void wait_for_condition(void) {
    pthread_mutex_lock(&mutex);           // 1. Always lock first
    
    while (!condition_predicate) {         // 2. WHILE, never IF
        pthread_cond_wait(&cond, &mutex); // 3. Wait releases mutex atomically
    }                                     // 4. Loop rechecks after wakeup
    
    // 5. Condition is true AND mutex is held here
    // ... do work that requires condition to be true ...
    
    pthread_mutex_unlock(&mutex);         // 6. Release mutex when done
}
 
// SIGNALER: Thread that makes condition true and notifies waiters
void signal_condition(void) {
    pthread_mutex_lock(&mutex);           // 1. Lock before modifying state
    
    condition_predicate = true;           // 2. Modify shared state
    
    pthread_cond_signal(&cond);           // 3. Signal (or broadcast) UNDER LOCK
    
    pthread_mutex_unlock(&mutex);         // 4. Release mutex
}

Pattern Requirements (Non-Negotiable)

•Lock before checking — The mutex MUST be held when evaluating the condition predicate. Checking outside the lock is a data race.
•WHILE, never IF — Spurious wakeups and stolen signals mean the condition might be false after wait returns. Always recheck.
•Predicate in shared state — The condition being tested must be protected by the same mutex passed to wait.
•Signal under lock (default) — While POSIX permits signaling without the lock, doing so complicates reasoning. Default to signaling under lock.
•Consistent mutex — A condition variable must always be used with the same mutex throughout its lifetime.

Why the While Loop is Mandatory

The while loop handles multiple scenarios:

1. Spurious Wakeups

POSIX explicitly permits pthread_cond_wait() to return without a signal. After return, the condition might still be false. The while loop rechecks.

2. Stolen Signals

With multiple waiters, a signal intended for thread A might wake thread B. Thread B checks the condition, finds it false (thread A consumed the resource), and the while loop sends B back to sleep.

3. Broadcast Wake

After broadcast, all threads wake. Only some may find the condition true. Others recheck via the while loop and go back to sleep.

4. Condition Becomes False Again

Another thread might change the condition between the signal and the waiter reacquiring the mutex. The while loop catches this.

The Pattern in Different Languages

This pattern is universal across languages and synchronization APIs:

Canonical Pattern Across Languages
Language	Lock	Wait	Signal
C (pthreads)	pthread_mutex_lock()	pthread_cond_wait()	pthread_cond_signal()
Java	synchronized / lock()	wait()	notify()
Python	lock.acquire()	condition.wait()	condition.notify()
C++	std::unique_lock	cond.wait(lock)	cond.notify_one()
Go	mu.Lock()	cond.Wait()	cond.Signal()
Rust	let guard = mutex.lock()	cond.wait(guard)	cond.notify_one()

The Pattern is Universal

Once you internalize this pattern for pthreads, it transfers directly to every other language and runtime. The while-loop-with-recheck is the universal correct approach to condition variables everywhere.

Producer-Consumer Pattern

The producer-consumer pattern is the most common use case for condition variables. It coordinates threads that produce work with threads that consume it, with a bounded buffer in between.

Complete, Production-Quality Implementation

producer_consumer_production.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
#include <pthread.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdio.h>
#include <errno.h>
 
// =====================================================
// Production Bounded Buffer with Full Error Handling
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t not_empty;    // Consumers wait when buffer empty
    pthread_cond_t not_full;     // Producers wait when buffer full
    
    void **items;                // Buffer storage
    int capacity;                // Maximum items
    int count;                   // Current item count
    int head;                    // Read position
    int tail;                    // Write position
    
    bool shutdown;               // Graceful shutdown flag
    int producers_active;        // Active producer count
    int consumers_waiting;       // Consumers currently waiting
} buffer_t;
 
// =====================================================
// Initialization
// =====================================================
 
int buffer_init(buffer_t *buf, int capacity) {
    if (capacity <= 0) return EINVAL;
    
    buf->items = malloc(sizeof(void *) * capacity);
    if (!buf->items) return ENOMEM;
    
    int rc = pthread_mutex_init(&buf->mutex, NULL);
    if (rc != 0) {
        free(buf->items);
        return rc;
    }
    
    // Use CLOCK_MONOTONIC for robust timeouts
    pthread_condattr_t attr;
    pthread_condattr_init(&attr);
    pthread_condattr_setclock(&attr, CLOCK_MONOTONIC);
    
    rc = pthread_cond_init(&buf->not_empty, &attr);
    if (rc != 0) {
        pthread_mutex_destroy(&buf->mutex);
        free(buf->items);
        pthread_condattr_destroy(&attr);
        return rc;
    }
    
    rc = pthread_cond_init(&buf->not_full, &attr);
    if (rc != 0) {
        pthread_cond_destroy(&buf->not_empty);
        pthread_mutex_destroy(&buf->mutex);
        free(buf->items);
        pthread_condattr_destroy(&attr);
        return rc;
    }
    
    pthread_condattr_destroy(&attr);
    
    buf->capacity = capacity;
    buf->count = 0;
    buf->head = 0;
    buf->tail = 0;
    buf->shutdown = false;
    buf->producers_active = 0;
    buf->consumers_waiting = 0;
    
    return 0;
}
 
// =====================================================
// Producer: Put Item with Timeout
// =====================================================
 
typedef enum {
    BUF_OK = 0,
    BUF_TIMEOUT,
    BUF_SHUTDOWN,
    BUF_ERROR
} buffer_status_t;
 
buffer_status_t buffer_put(buffer_t *buf, void *item, int timeout_ms) {
    struct timespec deadline;
    clock_gettime(CLOCK_MONOTONIC, &deadline);
    deadline.tv_sec += timeout_ms / 1000;
    deadline.tv_nsec += (timeout_ms % 1000) * 1000000L;
    if (deadline.tv_nsec >= 1000000000L) {
        deadline.tv_sec++;
        deadline.tv_nsec -= 1000000000L;
    }
    
    pthread_mutex_lock(&buf->mutex);
    buf->producers_active++;
    
    // Wait for space
    while (buf->count == buf->capacity && !buf->shutdown) {
        int rc = pthread_cond_timedwait(&buf->not_full, &buf->mutex, 
                                         &deadline);
        if (rc == ETIMEDOUT) {
            buf->producers_active--;
            pthread_mutex_unlock(&buf->mutex);
            return BUF_TIMEOUT;
        }
    }
    
    if (buf->shutdown) {
        buf->producers_active--;
        pthread_mutex_unlock(&buf->mutex);
        return BUF_SHUTDOWN;
    }
    
    // Add item
    buf->items[buf->tail] = item;
    buf->tail = (buf->tail + 1) % buf->capacity;
    buf->count++;
    
    buf->producers_active--;
    
    // Signal consumer
    pthread_cond_signal(&buf->not_empty);
    
    pthread_mutex_unlock(&buf->mutex);
    return BUF_OK;
}
 
// =====================================================
// Consumer: Get Item with Timeout
// =====================================================
 
buffer_status_t buffer_get(buffer_t *buf, void **item, int timeout_ms) {
    struct timespec deadline;
    clock_gettime(CLOCK_MONOTONIC, &deadline);
    deadline.tv_sec += timeout_ms / 1000;
    deadline.tv_nsec += (timeout_ms % 1000) * 1000000L;
    if (deadline.tv_nsec >= 1000000000L) {
        deadline.tv_sec++;
        deadline.tv_nsec -= 1000000000L;
    }
    
    pthread_mutex_lock(&buf->mutex);
    buf->consumers_waiting++;
    
    // Wait for item
    while (buf->count == 0 && !buf->shutdown) {
        int rc = pthread_cond_timedwait(&buf->not_empty, &buf->mutex,
                                         &deadline);
        if (rc == ETIMEDOUT) {
            buf->consumers_waiting--;
            pthread_mutex_unlock(&buf->mutex);
            return BUF_TIMEOUT;
        }
    }
    
    buf->consumers_waiting--;
    
    // Check for shutdown with empty buffer
    if (buf->count == 0 && buf->shutdown) {
        pthread_mutex_unlock(&buf->mutex);
        return BUF_SHUTDOWN;
    }
    
    // Remove item
    *item = buf->items[buf->head];
    buf->head = (buf->head + 1) % buf->capacity;
    buf->count--;
    
    // Signal producer
    pthread_cond_signal(&buf->not_full);
    
    pthread_mutex_unlock(&buf->mutex);
    return BUF_OK;
}
 
// =====================================================
// Graceful Shutdown
// =====================================================
 
void buffer_shutdown(buffer_t *buf) {
    pthread_mutex_lock(&buf->mutex);
    
    buf->shutdown = true;
    
    // Wake all waiters
    pthread_cond_broadcast(&buf->not_empty);
    pthread_cond_broadcast(&buf->not_full);
    
    pthread_mutex_unlock(&buf->mutex);
}

Pattern Features

•Two condition variables — not_empty and not_full prevent unnecessary wakeups.
•Timeout support — Uses CLOCK_MONOTONIC for reliable timeouts.
•Graceful shutdown — Shutdown flag checked in wait loops; broadcast wakes all.
•Status return values — Callers can distinguish success, timeout, shutdown, and error.
•Tracking metrics — producers_active and consumers_waiting enable monitoring.
•Signal (not broadcast) — Single-item operations use signal for efficiency.

Thread Pool Pattern

Thread pools are a fundamental building block for concurrent servers and applications. They maintain a set of worker threads that process tasks from a shared queue.

Production Thread Pool

thread_pool.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
#include <pthread.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdio.h>
 
// =====================================================
// Production Thread Pool with Condition Variables
// =====================================================
 
typedef void (*task_func_t)(void *arg);
 
typedef struct task_node {
    task_func_t func;
    void *arg;
    struct task_node *next;
} task_node_t;
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t task_available;   // Workers wait for tasks
    pthread_cond_t task_complete;    // Wait-for-completion support
    
    task_node_t *head;              // Task queue head
    task_node_t *tail;              // Task queue tail
    int pending_tasks;              // Tasks in queue
    int active_tasks;               // Tasks being processed
    
    pthread_t *threads;             // Worker thread handles
    int thread_count;
    bool shutdown;
} thread_pool_t;
 
// =====================================================
// Worker Thread
// =====================================================
 
static void *worker_thread(void *arg) {
    thread_pool_t *pool = (thread_pool_t *)arg;
    
    while (true) {
        pthread_mutex_lock(&pool->mutex);
        
        // Wait for task or shutdown
        while (pool->pending_tasks == 0 && !pool->shutdown) {
            pthread_cond_wait(&pool->task_available, &pool->mutex);
        }
        
        // Check for shutdown with empty queue
        if (pool->shutdown && pool->pending_tasks == 0) {
            pthread_mutex_unlock(&pool->mutex);
            break;
        }
        
        // Dequeue task
        task_node_t *task = pool->head;
        pool->head = task->next;
        if (!pool->head) pool->tail = NULL;
        pool->pending_tasks--;
        pool->active_tasks++;
        
        pthread_mutex_unlock(&pool->mutex);
        
        // Execute task (outside lock!)
        task->func(task->arg);
        free(task);
        
        // Task complete
        pthread_mutex_lock(&pool->mutex);
        pool->active_tasks--;
        
        // Signal completion waiters
        if (pool->pending_tasks == 0 && pool->active_tasks == 0) {
            pthread_cond_broadcast(&pool->task_complete);
        }
        
        pthread_mutex_unlock(&pool->mutex);
    }
    
    return NULL;
}
 
// =====================================================
// Pool Creation
// =====================================================
 
thread_pool_t *pool_create(int num_threads) {
    thread_pool_t *pool = calloc(1, sizeof(thread_pool_t));
    if (!pool) return NULL;
    
    pthread_mutex_init(&pool->mutex, NULL);
    pthread_cond_init(&pool->task_available, NULL);
    pthread_cond_init(&pool->task_complete, NULL);
    
    pool->threads = malloc(sizeof(pthread_t) * num_threads);
    pool->thread_count = num_threads;
    
    for (int i = 0; i < num_threads; i++) {
        pthread_create(&pool->threads[i], NULL, worker_thread, pool);
    }
    
    return pool;
}
 
// =====================================================
// Submit Task
// =====================================================
 
bool pool_submit(thread_pool_t *pool, task_func_t func, void *arg) {
    task_node_t *task = malloc(sizeof(task_node_t));
    if (!task) return false;
    
    task->func = func;
    task->arg = arg;
    task->next = NULL;
    
    pthread_mutex_lock(&pool->mutex);
    
    if (pool->shutdown) {
        pthread_mutex_unlock(&pool->mutex);
        free(task);
        return false;
    }
    
    // Enqueue
    if (pool->tail) {
        pool->tail->next = task;
    } else {
        pool->head = task;
    }
    pool->tail = task;
    pool->pending_tasks++;
    
    // Signal ONE worker
    pthread_cond_signal(&pool->task_available);
    
    pthread_mutex_unlock(&pool->mutex);
    return true;
}
 
// =====================================================
// Wait for All Tasks to Complete
// =====================================================
 
void pool_wait(thread_pool_t *pool) {
    pthread_mutex_lock(&pool->mutex);
    
    while (pool->pending_tasks > 0 || pool->active_tasks > 0) {
        pthread_cond_wait(&pool->task_complete, &pool->mutex);
    }
    
    pthread_mutex_unlock(&pool->mutex);
}
 
// =====================================================
// Graceful Shutdown
// =====================================================
 
void pool_destroy(thread_pool_t *pool) {
    pthread_mutex_lock(&pool->mutex);
    pool->shutdown = true;
    pthread_cond_broadcast(&pool->task_available);
    pthread_mutex_unlock(&pool->mutex);
    
    // Join all workers
    for (int i = 0; i < pool->thread_count; i++) {
        pthread_join(pool->threads[i], NULL);
    }
    
    // Cleanup
    pthread_cond_destroy(&pool->task_complete);
    pthread_cond_destroy(&pool->task_available);
    pthread_mutex_destroy(&pool->mutex);
    free(pool->threads);
    free(pool);
}

Key Design Points

Workers unlock the mutex BEFORE executing the task, allowing other workers to dequeue concurrently. The task_complete condition enables waiting for all work to finish. Signal (not broadcast) is used when submitting since each task needs exactly one worker.

Readers-Writers Pattern

The readers-writers problem allows multiple simultaneous readers but exclusive writer access. Condition variables coordinate between these modes.

Writers-Preference Implementation

readers_writers.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
#include <pthread.h>
 
// =====================================================
// Readers-Writers Lock (Writers Preference)
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t readers_ok;    // Readers wait here
    pthread_cond_t writers_ok;    // Writers wait here
    
    int active_readers;           // Currently reading
    int waiting_readers;          // Want to read
    int active_writers;           // Currently writing (0 or 1)
    int waiting_writers;          // Want to write
} rwlock_t;
 
void rwlock_init(rwlock_t *rw) {
    pthread_mutex_init(&rw->mutex, NULL);
    pthread_cond_init(&rw->readers_ok, NULL);
    pthread_cond_init(&rw->writers_ok, NULL);
    rw->active_readers = 0;
    rw->waiting_readers = 0;
    rw->active_writers = 0;
    rw->waiting_writers = 0;
}
 
// =====================================================
// Reader Lock: Multiple readers allowed
// =====================================================
 
void rwlock_read_lock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->waiting_readers++;
    
    // Wait if writer is active OR writers are waiting (preference)
    while (rw->active_writers > 0 || rw->waiting_writers > 0) {
        pthread_cond_wait(&rw->readers_ok, &rw->mutex);
    }
    
    rw->waiting_readers--;
    rw->active_readers++;
    
    pthread_mutex_unlock(&rw->mutex);
}
 
void rwlock_read_unlock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->active_readers--;
    
    // If last reader and writers waiting, signal ONE writer
    if (rw->active_readers == 0 && rw->waiting_writers > 0) {
        pthread_cond_signal(&rw->writers_ok);
    }
    
    pthread_mutex_unlock(&rw->mutex);
}
 
// =====================================================
// Writer Lock: Exclusive access
// =====================================================
 
void rwlock_write_lock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->waiting_writers++;
    
    // Wait for no active readers or writers
    while (rw->active_readers > 0 || rw->active_writers > 0) {
        pthread_cond_wait(&rw->writers_ok, &rw->mutex);
    }
    
    rw->waiting_writers--;
    rw->active_writers = 1;
    
    pthread_mutex_unlock(&rw->mutex);
}
 
void rwlock_write_unlock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->active_writers = 0;
    
    // Preference: wake writers first, then readers
    if (rw->waiting_writers > 0) {
        pthread_cond_signal(&rw->writers_ok);
    } else if (rw->waiting_readers > 0) {
        // Wake ALL waiting readers
        pthread_cond_broadcast(&rw->readers_ok);
    }
    
    pthread_mutex_unlock(&rw->mutex);
}

Pattern Analysis

•Writers preference — Readers wait if any writers are waiting, preventing writer starvation.
•Broadcast for readers — When writer finishes, ALL waiting readers can proceed simultaneously.
•Signal for writers — Only one writer proceeds at a time; signal suffices.
•Separate conditions — readers_ok and writers_ok prevent wrong thread from waking.
•Tracking counts — Four counters distinguish active vs. waiting for each role.

Defensive Patterns for Production

Production code must handle cancellation, timeouts, signal delivery, and cleanup robustly. These patterns provide that defense.

Pattern 1: Cancellation-Safe Wait

defensive_patterns.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
#include <pthread.h>
#include <stdbool.h>
#include <errno.h>
 
// =====================================================
// Cancellation-Safe Wait with Cleanup Handler
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t cond;
    bool ready;
} sync_point_t;
 
static void cleanup_mutex(void *arg) {
    pthread_mutex_unlock((pthread_mutex_t *)arg);
}
 
void sync_wait_cancellable(sync_point_t *sp) {
    pthread_mutex_lock(&sp->mutex);
    
    // Register cleanup handler BEFORE wait
    pthread_cleanup_push(cleanup_mutex, &sp->mutex);
    
    while (!sp->ready) {
        // If cancelled while waiting, cleanup handler runs
        pthread_cond_wait(&sp->cond, &sp->mutex);
    }
    
    // Pop cleanup; 0 = don't execute (we'll unlock normally)
    pthread_cleanup_pop(0);
    
    pthread_mutex_unlock(&sp->mutex);
}
 
// =====================================================
// Robust Timeout with Retry
// =====================================================
 
typedef enum {
    WAIT_SUCCESS,
    WAIT_TIMEOUT,
    WAIT_INTERRUPTED,
    WAIT_SHUTDOWN
} wait_result_t;
 
wait_result_t robust_timed_wait(sync_point_t *sp, int timeout_ms) {
    struct timespec deadline;
    clock_gettime(CLOCK_MONOTONIC, &deadline);
    deadline.tv_sec += timeout_ms / 1000;
    deadline.tv_nsec += (timeout_ms % 1000) * 1000000L;
    if (deadline.tv_nsec >= 1000000000L) {
        deadline.tv_sec++;
        deadline.tv_nsec -= 1000000000L;
    }
    
    pthread_mutex_lock(&sp->mutex);
    
    while (!sp->ready) {
        int rc = pthread_cond_timedwait(&sp->cond, &sp->mutex, &deadline);
        
        if (rc == ETIMEDOUT) {
            pthread_mutex_unlock(&sp->mutex);
            return WAIT_TIMEOUT;
        }
        
        // Handle rare error cases
        if (rc != 0 && rc != EINTR) {
            pthread_mutex_unlock(&sp->mutex);
            return WAIT_INTERRUPTED;
        }
        
        // rc == 0 or EINTR: continue loop, recheck condition
    }
    
    pthread_mutex_unlock(&sp->mutex);
    return WAIT_SUCCESS;
}
 
// =====================================================
// Double-Checked Initialization (Singleton)
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t init_complete;
    void *resource;
    bool initializing;
    bool initialized;
} lazy_resource_t;
 
void *get_resource(lazy_resource_t *lr) {
    pthread_mutex_lock(&lr->mutex);
    
    if (lr->initialized) {
        void *result = lr->resource;
        pthread_mutex_unlock(&lr->mutex);
        return result;
    }
    
    if (lr->initializing) {
        // Another thread is initializing; wait
        while (lr->initializing) {
            pthread_cond_wait(&lr->init_complete, &lr->mutex);
        }
        void *result = lr->resource;
        pthread_mutex_unlock(&lr->mutex);
        return result;
    }
    
    // We will initialize
    lr->initializing = true;
    pthread_mutex_unlock(&lr->mutex);
    
    // Do expensive initialization OUTSIDE lock
    void *new_resource = expensive_initialization();
    
    pthread_mutex_lock(&lr->mutex);
    lr->resource = new_resource;
    lr->initialized = true;
    lr->initializing = false;
    pthread_cond_broadcast(&lr->init_complete);
    pthread_mutex_unlock(&lr->mutex);
    
    return new_resource;
}

Defensive Techniques

•Cleanup handlers — Use pthread_cleanup_push/pop to ensure mutex is released on cancellation.
•CLOCK_MONOTONIC — Always configure condition variables to use monotonic clock for timeouts.
•Handle EINTR — Some implementations return EINTR on signal delivery; the while loop handles this.
•Status return values — Let callers distinguish success, timeout, shutdown, and error conditions.
•Lock minimization — Do expensive work outside the lock when possible (lazy initialization pattern).

Anti-Patterns to Avoid

These are patterns that appear in production code but are fundamentally flawed. Recognizing and avoiding them is essential.

anti_patterns.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
#include <pthread.h>
#include <stdbool.h>
#include <unistd.h>
 
// =====================================================
// ANTI-PATTERN 1: If Instead of While
// =====================================================
 
void *anti_if_instead_of_while(void *arg) {
    pthread_mutex_lock(&mutex);
    
    if (!condition) {  // WRONG!
        pthread_cond_wait(&cond, &mutex);
    }
    // BUG: condition might be false after spurious wakeup
    process();  // May crash or corrupt data
    
    pthread_mutex_unlock(&mutex);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 2: Checking Condition Without Lock
// =====================================================
 
void *anti_check_without_lock(void *arg) {
    // WRONG: Data race! Reading condition outside lock
    while (!condition) {
        pthread_mutex_lock(&mutex);
        pthread_cond_wait(&cond, &mutex);
        pthread_mutex_unlock(&mutex);
    }
    // Even if loop exits, condition could immediately become false
    process();
    return NULL;
}
 
// CORRECT:
void *correct_check_under_lock(void *arg) {
    pthread_mutex_lock(&mutex);
    while (!condition) {
        pthread_cond_wait(&cond, &mutex);
    }
    process();  // Lock still held, condition guaranteed
    pthread_mutex_unlock(&mutex);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 3: Different Mutexes with Same Cond Var
// =====================================================
 
pthread_mutex_t mutex_a = PTHREAD_MUTEX_INITIALIZER;
pthread_mutex_t mutex_b = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t shared_cond = PTHREAD_COND_INITIALIZER;
 
void *anti_different_mutexes_a(void *arg) {
    pthread_mutex_lock(&mutex_a);
    pthread_cond_wait(&shared_cond, &mutex_a);  // Uses mutex_a
    pthread_mutex_unlock(&mutex_a);
    return NULL;
}
 
void *anti_different_mutexes_b(void *arg) {
    pthread_mutex_lock(&mutex_b);
    pthread_cond_wait(&shared_cond, &mutex_b);  // Uses mutex_b - UNDEFINED!
    pthread_mutex_unlock(&mutex_b);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 4: Busy Waiting in Loop
// =====================================================
 
void *anti_busy_wait(void *arg) {
    while (!condition) {
        pthread_mutex_lock(&mutex);
        bool c = condition;
        pthread_mutex_unlock(&mutex);
        
        if (!c) {
            usleep(1000);  // WRONG: Still burns CPU, adds latency
        }
    }
    return NULL;
}
 
// CORRECT: Use condition variable
void *correct_blocking_wait(void *arg) {
    pthread_mutex_lock(&mutex);
    while (!condition) {
        pthread_cond_wait(&cond, &mutex);  // Blocks, no CPU use
    }
    pthread_mutex_unlock(&mutex);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 5: Forgetting to Signal
// =====================================================
 
void anti_no_signal(void) {
    pthread_mutex_lock(&mutex);
    condition = true;
    pthread_mutex_unlock(&mutex);
    // WHERE IS THE SIGNAL? Waiters wait forever!
}
 
// =====================================================
// ANTI-PATTERN 6: Signal with No State Change
// =====================================================
 
void anti_empty_signal(void) {
    pthread_mutex_lock(&mutex);
    // No state change!
    pthread_cond_signal(&cond);  // Wakes thread that rechecks and sleeps
    pthread_mutex_unlock(&mutex);
    // Wasted wakeup, confusing code
}

Anti-Pattern Summary
Anti-Pattern	Consequence	Correct Approach
if instead of while	Spurious wakeup causes incorrect execution	Always use while loop
Check without lock	Data race; undefined behavior	Check predicate under lock
Different mutexes	Undefined behavior	One mutex per condition variable
Busy waiting	CPU waste; latency	Use pthread_cond_wait()
Forgotten signal	Waiters block forever	Always signal after state change
Signal without change	Wasted wakeup	Signal only when predicate changes

Testing Concurrent Code

Condition variable bugs are notoriously hard to reproduce and debug. Systematic testing approaches improve confidence.

Strategy 1: Stress Testing

Run operations at high volume and concurrency to expose race conditions:

testing_strategies.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
#include <pthread.h>
#include <stdio.h>
#include <assert.h>
#include <stdlib.h>
 
// =====================================================
// Stress Test: High Volume Concurrent Operations
// =====================================================
 
#define NUM_PRODUCERS 10
#define NUM_CONSUMERS 10
#define ITEMS_PER_PRODUCER 10000
 
buffer_t test_buffer;
int items_produced = 0;
int items_consumed = 0;
pthread_mutex_t counter_mutex = PTHREAD_MUTEX_INITIALIZER;
 
void *stress_producer(void *arg) {
    for (int i = 0; i < ITEMS_PER_PRODUCER; i++) {
        void *item = malloc(sizeof(int));
        *(int *)item = rand();
        
        buffer_status_t s = buffer_put(&test_buffer, item, 10000);
        assert(s == BUF_OK);
        
        pthread_mutex_lock(&counter_mutex);
        items_produced++;
        pthread_mutex_unlock(&counter_mutex);
    }
    return NULL;
}
 
void *stress_consumer(void *arg) {
    while (1) {
        void *item;
        buffer_status_t s = buffer_get(&test_buffer, &item, 100);
        
        if (s == BUF_TIMEOUT) continue;
        if (s == BUF_SHUTDOWN) break;
        
        free(item);
        
        pthread_mutex_lock(&counter_mutex);
        items_consumed++;
        pthread_mutex_unlock(&counter_mutex);
    }
    return NULL;
}
 
void run_stress_test(void) {
    buffer_init(&test_buffer, 100);
    
    pthread_t producers[NUM_PRODUCERS];
    pthread_t consumers[NUM_CONSUMERS];
    
    for (int i = 0; i < NUM_CONSUMERS; i++) {
        pthread_create(&consumers[i], NULL, stress_consumer, NULL);
    }
    for (int i = 0; i < NUM_PRODUCERS; i++) {
        pthread_create(&producers[i], NULL, stress_producer, NULL);
    }
    
    for (int i = 0; i < NUM_PRODUCERS; i++) {
        pthread_join(producers[i], NULL);
    }
    
    // Wait for consumers to drain
    while (items_consumed < items_produced) {
        usleep(1000);
    }
    
    buffer_shutdown(&test_buffer);
    
    for (int i = 0; i < NUM_CONSUMERS; i++) {
        pthread_join(consumers[i], NULL);
    }
    
    printf("Produced: %d, Consumed: %d\n", items_produced, items_consumed);
    assert(items_produced == items_consumed);
    printf("STRESS TEST PASSED\n");
}
 
// =====================================================
// Instrumentation: Track Wait Statistics
// =====================================================
 
typedef struct {
    int wait_count;
    int wakeup_count;
    int spurious_wakeup_count;
} wait_stats_t;
 
__thread wait_stats_t thread_stats;
 
void instrumented_wait(pthread_cond_t *cond, pthread_mutex_t *mutex,
                       bool *predicate) {
    thread_stats.wait_count++;
    
    while (!*predicate) {
        pthread_cond_wait(cond, mutex);
        thread_stats.wakeup_count++;
        
        if (!*predicate) {
            thread_stats.spurious_wakeup_count++;
        }
    }
}

Testing Approaches

•Stress testing — High volume with many threads exposes races that rarely occur with low volume.
•Delay injection — Add random delays to increase race window visibility.
•ThreadSanitizer — Use -fsanitize=thread to detect data races at runtime.
•Helgrind (Valgrind) — Another race detector with different detection algorithms.
•Assertion-heavy code — Assert invariants frequently; fail fast on corruption.
•Instrumentation — Track wait/wakeup statistics to detect unexpected spurious wakeups.
•Deterministic testing — Record and replay thread schedules for reproducibility.

Run Under Sanitizers

Compile your tests with -fsanitize=thread and run frequently. ThreadSanitizer catches races, lock-order inversions, and many condition variable misuses automatically. It's your first line of defense against concurrency bugs.

Summary

This page has consolidated pthread condition variable usage into production-ready patterns. These patterns represent decades of collective experience in concurrent programming.

Key Takeaways

•The Canonical Pattern — Lock, while(!predicate) wait, do work, unlock. This is mandatory and universal.
•Producer-Consumer — Two condition variables (not_empty, not_full), signal for single-item operations.
•Thread Pool — Workers wait for tasks, signal on submit, broadcast on shutdown.
•Readers-Writers — Broadcast for readers (multiple can proceed), signal for writers (one at a time).
•Defensive Patterns — Cleanup handlers, CLOCK_MONOTONIC, status return values.
•Anti-Patterns — if instead of while, checking without lock, different mutexes, busy waiting.
•Testing — Stress tests, ThreadSanitizer, instrumentation. Test under adverse conditions.

Module Complete: Pthread Condition Variables

You have completed the comprehensive study of pthread condition variables. You understand pthread_cond_t, wait, signal, broadcast, and the patterns that combine them into correct, efficient concurrent programs. These skills form the foundation for building any concurrent system on POSIX platforms.

5 / 5

Loading learning content...

Operating SystemsPthread Condition Variables

Pthread Condition Variables

LevelAdvanced

Duration120 mins

TopicPthread Condition Variables

5 / 5

Proper Usage Patterns

The Art of Condition Variable Usage

Having explored each pthread condition variable function individually, this page synthesizes everything into production-ready patterns that represent industry best practices.

This page presents:

The Canonical Pattern — The fundamental template for all condition variable usage
Standard Idioms — Time-tested implementations of common synchronization needs
Defensive Patterns — Techniques for robustness in production environments
Anti-Patterns — Common mistakes and how to avoid them
Testing Strategies — Approaches for validating concurrent code

Master these patterns, and you will write condition variable code that is correct by construction.

Learning Objectives

The Canonical Pattern

Every correct use of condition variables follows the same fundamental template. This template handles spurious wakeups, lost signals, and all edge cases.

The Template

canonical_pattern.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
#include <pthread.h>
#include <stdbool.h>
 
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
 
// Your shared state (the "condition" being waited on)
bool condition_predicate = false;  // Replace with your actual condition
 
/*
 * ========================================================
 * THE CANONICAL CONDITION VARIABLE PATTERN
 * ========================================================
 *
 * This pattern is MANDATORY for correctness. Deviation leads to bugs.
 * Memorize it. Apply it without exception.
 */
 
// WAITER: Thread that waits for condition to become true
void wait_for_condition(void) {
    pthread_mutex_lock(&mutex);           // 1. Always lock first
    
    while (!condition_predicate) {         // 2. WHILE, never IF
        pthread_cond_wait(&cond, &mutex); // 3. Wait releases mutex atomically
    }                                     // 4. Loop rechecks after wakeup
    
    // 5. Condition is true AND mutex is held here
    // ... do work that requires condition to be true ...
    
    pthread_mutex_unlock(&mutex);         // 6. Release mutex when done
}
 
// SIGNALER: Thread that makes condition true and notifies waiters
void signal_condition(void) {
    pthread_mutex_lock(&mutex);           // 1. Lock before modifying state
    
    condition_predicate = true;           // 2. Modify shared state
    
    pthread_cond_signal(&cond);           // 3. Signal (or broadcast) UNDER LOCK
    
    pthread_mutex_unlock(&mutex);         // 4. Release mutex
}

Pattern Requirements (Non-Negotiable)

•Lock before checking — The mutex MUST be held when evaluating the condition predicate. Checking outside the lock is a data race.
•WHILE, never IF — Spurious wakeups and stolen signals mean the condition might be false after wait returns. Always recheck.
•Predicate in shared state — The condition being tested must be protected by the same mutex passed to wait.
•Signal under lock (default) — While POSIX permits signaling without the lock, doing so complicates reasoning. Default to signaling under lock.
•Consistent mutex — A condition variable must always be used with the same mutex throughout its lifetime.

Why the While Loop is Mandatory

The while loop handles multiple scenarios:

1. Spurious Wakeups

POSIX explicitly permits pthread_cond_wait() to return without a signal. After return, the condition might still be false. The while loop rechecks.

2. Stolen Signals

With multiple waiters, a signal intended for thread A might wake thread B. Thread B checks the condition, finds it false (thread A consumed the resource), and the while loop sends B back to sleep.

3. Broadcast Wake

After broadcast, all threads wake. Only some may find the condition true. Others recheck via the while loop and go back to sleep.

4. Condition Becomes False Again

Another thread might change the condition between the signal and the waiter reacquiring the mutex. The while loop catches this.

The Pattern in Different Languages

This pattern is universal across languages and synchronization APIs:

Canonical Pattern Across Languages
Language	Lock	Wait	Signal
C (pthreads)	pthread_mutex_lock()	pthread_cond_wait()	pthread_cond_signal()
Java	synchronized / lock()	wait()	notify()
Python	lock.acquire()	condition.wait()	condition.notify()
C++	std::unique_lock	cond.wait(lock)	cond.notify_one()
Go	mu.Lock()	cond.Wait()	cond.Signal()
Rust	let guard = mutex.lock()	cond.wait(guard)	cond.notify_one()

The Pattern is Universal

Producer-Consumer Pattern

The producer-consumer pattern is the most common use case for condition variables. It coordinates threads that produce work with threads that consume it, with a bounded buffer in between.

Complete, Production-Quality Implementation

producer_consumer_production.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
#include <pthread.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdio.h>
#include <errno.h>
 
// =====================================================
// Production Bounded Buffer with Full Error Handling
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t not_empty;    // Consumers wait when buffer empty
    pthread_cond_t not_full;     // Producers wait when buffer full
    
    void **items;                // Buffer storage
    int capacity;                // Maximum items
    int count;                   // Current item count
    int head;                    // Read position
    int tail;                    // Write position
    
    bool shutdown;               // Graceful shutdown flag
    int producers_active;        // Active producer count
    int consumers_waiting;       // Consumers currently waiting
} buffer_t;
 
// =====================================================
// Initialization
// =====================================================
 
int buffer_init(buffer_t *buf, int capacity) {
    if (capacity <= 0) return EINVAL;
    
    buf->items = malloc(sizeof(void *) * capacity);
    if (!buf->items) return ENOMEM;
    
    int rc = pthread_mutex_init(&buf->mutex, NULL);
    if (rc != 0) {
        free(buf->items);
        return rc;
    }
    
    // Use CLOCK_MONOTONIC for robust timeouts
    pthread_condattr_t attr;
    pthread_condattr_init(&attr);
    pthread_condattr_setclock(&attr, CLOCK_MONOTONIC);
    
    rc = pthread_cond_init(&buf->not_empty, &attr);
    if (rc != 0) {
        pthread_mutex_destroy(&buf->mutex);
        free(buf->items);
        pthread_condattr_destroy(&attr);
        return rc;
    }
    
    rc = pthread_cond_init(&buf->not_full, &attr);
    if (rc != 0) {
        pthread_cond_destroy(&buf->not_empty);
        pthread_mutex_destroy(&buf->mutex);
        free(buf->items);
        pthread_condattr_destroy(&attr);
        return rc;
    }
    
    pthread_condattr_destroy(&attr);
    
    buf->capacity = capacity;
    buf->count = 0;
    buf->head = 0;
    buf->tail = 0;
    buf->shutdown = false;
    buf->producers_active = 0;
    buf->consumers_waiting = 0;
    
    return 0;
}
 
// =====================================================
// Producer: Put Item with Timeout
// =====================================================
 
typedef enum {
    BUF_OK = 0,
    BUF_TIMEOUT,
    BUF_SHUTDOWN,
    BUF_ERROR
} buffer_status_t;
 
buffer_status_t buffer_put(buffer_t *buf, void *item, int timeout_ms) {
    struct timespec deadline;
    clock_gettime(CLOCK_MONOTONIC, &deadline);
    deadline.tv_sec += timeout_ms / 1000;
    deadline.tv_nsec += (timeout_ms % 1000) * 1000000L;
    if (deadline.tv_nsec >= 1000000000L) {
        deadline.tv_sec++;
        deadline.tv_nsec -= 1000000000L;
    }
    
    pthread_mutex_lock(&buf->mutex);
    buf->producers_active++;
    
    // Wait for space
    while (buf->count == buf->capacity && !buf->shutdown) {
        int rc = pthread_cond_timedwait(&buf->not_full, &buf->mutex, 
                                         &deadline);
        if (rc == ETIMEDOUT) {
            buf->producers_active--;
            pthread_mutex_unlock(&buf->mutex);
            return BUF_TIMEOUT;
        }
    }
    
    if (buf->shutdown) {
        buf->producers_active--;
        pthread_mutex_unlock(&buf->mutex);
        return BUF_SHUTDOWN;
    }
    
    // Add item
    buf->items[buf->tail] = item;
    buf->tail = (buf->tail + 1) % buf->capacity;
    buf->count++;
    
    buf->producers_active--;
    
    // Signal consumer
    pthread_cond_signal(&buf->not_empty);
    
    pthread_mutex_unlock(&buf->mutex);
    return BUF_OK;
}
 
// =====================================================
// Consumer: Get Item with Timeout
// =====================================================
 
buffer_status_t buffer_get(buffer_t *buf, void **item, int timeout_ms) {
    struct timespec deadline;
    clock_gettime(CLOCK_MONOTONIC, &deadline);
    deadline.tv_sec += timeout_ms / 1000;
    deadline.tv_nsec += (timeout_ms % 1000) * 1000000L;
    if (deadline.tv_nsec >= 1000000000L) {
        deadline.tv_sec++;
        deadline.tv_nsec -= 1000000000L;
    }
    
    pthread_mutex_lock(&buf->mutex);
    buf->consumers_waiting++;
    
    // Wait for item
    while (buf->count == 0 && !buf->shutdown) {
        int rc = pthread_cond_timedwait(&buf->not_empty, &buf->mutex,
                                         &deadline);
        if (rc == ETIMEDOUT) {
            buf->consumers_waiting--;
            pthread_mutex_unlock(&buf->mutex);
            return BUF_TIMEOUT;
        }
    }
    
    buf->consumers_waiting--;
    
    // Check for shutdown with empty buffer
    if (buf->count == 0 && buf->shutdown) {
        pthread_mutex_unlock(&buf->mutex);
        return BUF_SHUTDOWN;
    }
    
    // Remove item
    *item = buf->items[buf->head];
    buf->head = (buf->head + 1) % buf->capacity;
    buf->count--;
    
    // Signal producer
    pthread_cond_signal(&buf->not_full);
    
    pthread_mutex_unlock(&buf->mutex);
    return BUF_OK;
}
 
// =====================================================
// Graceful Shutdown
// =====================================================
 
void buffer_shutdown(buffer_t *buf) {
    pthread_mutex_lock(&buf->mutex);
    
    buf->shutdown = true;
    
    // Wake all waiters
    pthread_cond_broadcast(&buf->not_empty);
    pthread_cond_broadcast(&buf->not_full);
    
    pthread_mutex_unlock(&buf->mutex);
}

Pattern Features

•Two condition variables — not_empty and not_full prevent unnecessary wakeups.
•Timeout support — Uses CLOCK_MONOTONIC for reliable timeouts.
•Graceful shutdown — Shutdown flag checked in wait loops; broadcast wakes all.
•Status return values — Callers can distinguish success, timeout, shutdown, and error.
•Tracking metrics — producers_active and consumers_waiting enable monitoring.
•Signal (not broadcast) — Single-item operations use signal for efficiency.

Thread Pool Pattern

Thread pools are a fundamental building block for concurrent servers and applications. They maintain a set of worker threads that process tasks from a shared queue.

Production Thread Pool

thread_pool.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
#include <pthread.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdio.h>
 
// =====================================================
// Production Thread Pool with Condition Variables
// =====================================================
 
typedef void (*task_func_t)(void *arg);
 
typedef struct task_node {
    task_func_t func;
    void *arg;
    struct task_node *next;
} task_node_t;
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t task_available;   // Workers wait for tasks
    pthread_cond_t task_complete;    // Wait-for-completion support
    
    task_node_t *head;              // Task queue head
    task_node_t *tail;              // Task queue tail
    int pending_tasks;              // Tasks in queue
    int active_tasks;               // Tasks being processed
    
    pthread_t *threads;             // Worker thread handles
    int thread_count;
    bool shutdown;
} thread_pool_t;
 
// =====================================================
// Worker Thread
// =====================================================
 
static void *worker_thread(void *arg) {
    thread_pool_t *pool = (thread_pool_t *)arg;
    
    while (true) {
        pthread_mutex_lock(&pool->mutex);
        
        // Wait for task or shutdown
        while (pool->pending_tasks == 0 && !pool->shutdown) {
            pthread_cond_wait(&pool->task_available, &pool->mutex);
        }
        
        // Check for shutdown with empty queue
        if (pool->shutdown && pool->pending_tasks == 0) {
            pthread_mutex_unlock(&pool->mutex);
            break;
        }
        
        // Dequeue task
        task_node_t *task = pool->head;
        pool->head = task->next;
        if (!pool->head) pool->tail = NULL;
        pool->pending_tasks--;
        pool->active_tasks++;
        
        pthread_mutex_unlock(&pool->mutex);
        
        // Execute task (outside lock!)
        task->func(task->arg);
        free(task);
        
        // Task complete
        pthread_mutex_lock(&pool->mutex);
        pool->active_tasks--;
        
        // Signal completion waiters
        if (pool->pending_tasks == 0 && pool->active_tasks == 0) {
            pthread_cond_broadcast(&pool->task_complete);
        }
        
        pthread_mutex_unlock(&pool->mutex);
    }
    
    return NULL;
}
 
// =====================================================
// Pool Creation
// =====================================================
 
thread_pool_t *pool_create(int num_threads) {
    thread_pool_t *pool = calloc(1, sizeof(thread_pool_t));
    if (!pool) return NULL;
    
    pthread_mutex_init(&pool->mutex, NULL);
    pthread_cond_init(&pool->task_available, NULL);
    pthread_cond_init(&pool->task_complete, NULL);
    
    pool->threads = malloc(sizeof(pthread_t) * num_threads);
    pool->thread_count = num_threads;
    
    for (int i = 0; i < num_threads; i++) {
        pthread_create(&pool->threads[i], NULL, worker_thread, pool);
    }
    
    return pool;
}
 
// =====================================================
// Submit Task
// =====================================================
 
bool pool_submit(thread_pool_t *pool, task_func_t func, void *arg) {
    task_node_t *task = malloc(sizeof(task_node_t));
    if (!task) return false;
    
    task->func = func;
    task->arg = arg;
    task->next = NULL;
    
    pthread_mutex_lock(&pool->mutex);
    
    if (pool->shutdown) {
        pthread_mutex_unlock(&pool->mutex);
        free(task);
        return false;
    }
    
    // Enqueue
    if (pool->tail) {
        pool->tail->next = task;
    } else {
        pool->head = task;
    }
    pool->tail = task;
    pool->pending_tasks++;
    
    // Signal ONE worker
    pthread_cond_signal(&pool->task_available);
    
    pthread_mutex_unlock(&pool->mutex);
    return true;
}
 
// =====================================================
// Wait for All Tasks to Complete
// =====================================================
 
void pool_wait(thread_pool_t *pool) {
    pthread_mutex_lock(&pool->mutex);
    
    while (pool->pending_tasks > 0 || pool->active_tasks > 0) {
        pthread_cond_wait(&pool->task_complete, &pool->mutex);
    }
    
    pthread_mutex_unlock(&pool->mutex);
}
 
// =====================================================
// Graceful Shutdown
// =====================================================
 
void pool_destroy(thread_pool_t *pool) {
    pthread_mutex_lock(&pool->mutex);
    pool->shutdown = true;
    pthread_cond_broadcast(&pool->task_available);
    pthread_mutex_unlock(&pool->mutex);
    
    // Join all workers
    for (int i = 0; i < pool->thread_count; i++) {
        pthread_join(pool->threads[i], NULL);
    }
    
    // Cleanup
    pthread_cond_destroy(&pool->task_complete);
    pthread_cond_destroy(&pool->task_available);
    pthread_mutex_destroy(&pool->mutex);
    free(pool->threads);
    free(pool);
}

Key Design Points

Readers-Writers Pattern

The readers-writers problem allows multiple simultaneous readers but exclusive writer access. Condition variables coordinate between these modes.

Writers-Preference Implementation

readers_writers.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
#include <pthread.h>
 
// =====================================================
// Readers-Writers Lock (Writers Preference)
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t readers_ok;    // Readers wait here
    pthread_cond_t writers_ok;    // Writers wait here
    
    int active_readers;           // Currently reading
    int waiting_readers;          // Want to read
    int active_writers;           // Currently writing (0 or 1)
    int waiting_writers;          // Want to write
} rwlock_t;
 
void rwlock_init(rwlock_t *rw) {
    pthread_mutex_init(&rw->mutex, NULL);
    pthread_cond_init(&rw->readers_ok, NULL);
    pthread_cond_init(&rw->writers_ok, NULL);
    rw->active_readers = 0;
    rw->waiting_readers = 0;
    rw->active_writers = 0;
    rw->waiting_writers = 0;
}
 
// =====================================================
// Reader Lock: Multiple readers allowed
// =====================================================
 
void rwlock_read_lock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->waiting_readers++;
    
    // Wait if writer is active OR writers are waiting (preference)
    while (rw->active_writers > 0 || rw->waiting_writers > 0) {
        pthread_cond_wait(&rw->readers_ok, &rw->mutex);
    }
    
    rw->waiting_readers--;
    rw->active_readers++;
    
    pthread_mutex_unlock(&rw->mutex);
}
 
void rwlock_read_unlock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->active_readers--;
    
    // If last reader and writers waiting, signal ONE writer
    if (rw->active_readers == 0 && rw->waiting_writers > 0) {
        pthread_cond_signal(&rw->writers_ok);
    }
    
    pthread_mutex_unlock(&rw->mutex);
}
 
// =====================================================
// Writer Lock: Exclusive access
// =====================================================
 
void rwlock_write_lock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->waiting_writers++;
    
    // Wait for no active readers or writers
    while (rw->active_readers > 0 || rw->active_writers > 0) {
        pthread_cond_wait(&rw->writers_ok, &rw->mutex);
    }
    
    rw->waiting_writers--;
    rw->active_writers = 1;
    
    pthread_mutex_unlock(&rw->mutex);
}
 
void rwlock_write_unlock(rwlock_t *rw) {
    pthread_mutex_lock(&rw->mutex);
    
    rw->active_writers = 0;
    
    // Preference: wake writers first, then readers
    if (rw->waiting_writers > 0) {
        pthread_cond_signal(&rw->writers_ok);
    } else if (rw->waiting_readers > 0) {
        // Wake ALL waiting readers
        pthread_cond_broadcast(&rw->readers_ok);
    }
    
    pthread_mutex_unlock(&rw->mutex);
}

Pattern Analysis

•Writers preference — Readers wait if any writers are waiting, preventing writer starvation.
•Broadcast for readers — When writer finishes, ALL waiting readers can proceed simultaneously.
•Signal for writers — Only one writer proceeds at a time; signal suffices.
•Separate conditions — readers_ok and writers_ok prevent wrong thread from waking.
•Tracking counts — Four counters distinguish active vs. waiting for each role.

Defensive Patterns for Production

Production code must handle cancellation, timeouts, signal delivery, and cleanup robustly. These patterns provide that defense.

Pattern 1: Cancellation-Safe Wait

defensive_patterns.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
#include <pthread.h>
#include <stdbool.h>
#include <errno.h>
 
// =====================================================
// Cancellation-Safe Wait with Cleanup Handler
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t cond;
    bool ready;
} sync_point_t;
 
static void cleanup_mutex(void *arg) {
    pthread_mutex_unlock((pthread_mutex_t *)arg);
}
 
void sync_wait_cancellable(sync_point_t *sp) {
    pthread_mutex_lock(&sp->mutex);
    
    // Register cleanup handler BEFORE wait
    pthread_cleanup_push(cleanup_mutex, &sp->mutex);
    
    while (!sp->ready) {
        // If cancelled while waiting, cleanup handler runs
        pthread_cond_wait(&sp->cond, &sp->mutex);
    }
    
    // Pop cleanup; 0 = don't execute (we'll unlock normally)
    pthread_cleanup_pop(0);
    
    pthread_mutex_unlock(&sp->mutex);
}
 
// =====================================================
// Robust Timeout with Retry
// =====================================================
 
typedef enum {
    WAIT_SUCCESS,
    WAIT_TIMEOUT,
    WAIT_INTERRUPTED,
    WAIT_SHUTDOWN
} wait_result_t;
 
wait_result_t robust_timed_wait(sync_point_t *sp, int timeout_ms) {
    struct timespec deadline;
    clock_gettime(CLOCK_MONOTONIC, &deadline);
    deadline.tv_sec += timeout_ms / 1000;
    deadline.tv_nsec += (timeout_ms % 1000) * 1000000L;
    if (deadline.tv_nsec >= 1000000000L) {
        deadline.tv_sec++;
        deadline.tv_nsec -= 1000000000L;
    }
    
    pthread_mutex_lock(&sp->mutex);
    
    while (!sp->ready) {
        int rc = pthread_cond_timedwait(&sp->cond, &sp->mutex, &deadline);
        
        if (rc == ETIMEDOUT) {
            pthread_mutex_unlock(&sp->mutex);
            return WAIT_TIMEOUT;
        }
        
        // Handle rare error cases
        if (rc != 0 && rc != EINTR) {
            pthread_mutex_unlock(&sp->mutex);
            return WAIT_INTERRUPTED;
        }
        
        // rc == 0 or EINTR: continue loop, recheck condition
    }
    
    pthread_mutex_unlock(&sp->mutex);
    return WAIT_SUCCESS;
}
 
// =====================================================
// Double-Checked Initialization (Singleton)
// =====================================================
 
typedef struct {
    pthread_mutex_t mutex;
    pthread_cond_t init_complete;
    void *resource;
    bool initializing;
    bool initialized;
} lazy_resource_t;
 
void *get_resource(lazy_resource_t *lr) {
    pthread_mutex_lock(&lr->mutex);
    
    if (lr->initialized) {
        void *result = lr->resource;
        pthread_mutex_unlock(&lr->mutex);
        return result;
    }
    
    if (lr->initializing) {
        // Another thread is initializing; wait
        while (lr->initializing) {
            pthread_cond_wait(&lr->init_complete, &lr->mutex);
        }
        void *result = lr->resource;
        pthread_mutex_unlock(&lr->mutex);
        return result;
    }
    
    // We will initialize
    lr->initializing = true;
    pthread_mutex_unlock(&lr->mutex);
    
    // Do expensive initialization OUTSIDE lock
    void *new_resource = expensive_initialization();
    
    pthread_mutex_lock(&lr->mutex);
    lr->resource = new_resource;
    lr->initialized = true;
    lr->initializing = false;
    pthread_cond_broadcast(&lr->init_complete);
    pthread_mutex_unlock(&lr->mutex);
    
    return new_resource;
}

Defensive Techniques

•Cleanup handlers — Use pthread_cleanup_push/pop to ensure mutex is released on cancellation.
•CLOCK_MONOTONIC — Always configure condition variables to use monotonic clock for timeouts.
•Handle EINTR — Some implementations return EINTR on signal delivery; the while loop handles this.
•Status return values — Let callers distinguish success, timeout, shutdown, and error conditions.
•Lock minimization — Do expensive work outside the lock when possible (lazy initialization pattern).

Anti-Patterns to Avoid

These are patterns that appear in production code but are fundamentally flawed. Recognizing and avoiding them is essential.

anti_patterns.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
#include <pthread.h>
#include <stdbool.h>
#include <unistd.h>
 
// =====================================================
// ANTI-PATTERN 1: If Instead of While
// =====================================================
 
void *anti_if_instead_of_while(void *arg) {
    pthread_mutex_lock(&mutex);
    
    if (!condition) {  // WRONG!
        pthread_cond_wait(&cond, &mutex);
    }
    // BUG: condition might be false after spurious wakeup
    process();  // May crash or corrupt data
    
    pthread_mutex_unlock(&mutex);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 2: Checking Condition Without Lock
// =====================================================
 
void *anti_check_without_lock(void *arg) {
    // WRONG: Data race! Reading condition outside lock
    while (!condition) {
        pthread_mutex_lock(&mutex);
        pthread_cond_wait(&cond, &mutex);
        pthread_mutex_unlock(&mutex);
    }
    // Even if loop exits, condition could immediately become false
    process();
    return NULL;
}
 
// CORRECT:
void *correct_check_under_lock(void *arg) {
    pthread_mutex_lock(&mutex);
    while (!condition) {
        pthread_cond_wait(&cond, &mutex);
    }
    process();  // Lock still held, condition guaranteed
    pthread_mutex_unlock(&mutex);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 3: Different Mutexes with Same Cond Var
// =====================================================
 
pthread_mutex_t mutex_a = PTHREAD_MUTEX_INITIALIZER;
pthread_mutex_t mutex_b = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t shared_cond = PTHREAD_COND_INITIALIZER;
 
void *anti_different_mutexes_a(void *arg) {
    pthread_mutex_lock(&mutex_a);
    pthread_cond_wait(&shared_cond, &mutex_a);  // Uses mutex_a
    pthread_mutex_unlock(&mutex_a);
    return NULL;
}
 
void *anti_different_mutexes_b(void *arg) {
    pthread_mutex_lock(&mutex_b);
    pthread_cond_wait(&shared_cond, &mutex_b);  // Uses mutex_b - UNDEFINED!
    pthread_mutex_unlock(&mutex_b);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 4: Busy Waiting in Loop
// =====================================================
 
void *anti_busy_wait(void *arg) {
    while (!condition) {
        pthread_mutex_lock(&mutex);
        bool c = condition;
        pthread_mutex_unlock(&mutex);
        
        if (!c) {
            usleep(1000);  // WRONG: Still burns CPU, adds latency
        }
    }
    return NULL;
}
 
// CORRECT: Use condition variable
void *correct_blocking_wait(void *arg) {
    pthread_mutex_lock(&mutex);
    while (!condition) {
        pthread_cond_wait(&cond, &mutex);  // Blocks, no CPU use
    }
    pthread_mutex_unlock(&mutex);
    return NULL;
}
 
// =====================================================
// ANTI-PATTERN 5: Forgetting to Signal
// =====================================================
 
void anti_no_signal(void) {
    pthread_mutex_lock(&mutex);
    condition = true;
    pthread_mutex_unlock(&mutex);
    // WHERE IS THE SIGNAL? Waiters wait forever!
}
 
// =====================================================
// ANTI-PATTERN 6: Signal with No State Change
// =====================================================
 
void anti_empty_signal(void) {
    pthread_mutex_lock(&mutex);
    // No state change!
    pthread_cond_signal(&cond);  // Wakes thread that rechecks and sleeps
    pthread_mutex_unlock(&mutex);
    // Wasted wakeup, confusing code
}

Anti-Pattern Summary
Anti-Pattern	Consequence	Correct Approach
if instead of while	Spurious wakeup causes incorrect execution	Always use while loop
Check without lock	Data race; undefined behavior	Check predicate under lock
Different mutexes	Undefined behavior	One mutex per condition variable
Busy waiting	CPU waste; latency	Use pthread_cond_wait()
Forgotten signal	Waiters block forever	Always signal after state change
Signal without change	Wasted wakeup	Signal only when predicate changes

Testing Concurrent Code

Condition variable bugs are notoriously hard to reproduce and debug. Systematic testing approaches improve confidence.

Strategy 1: Stress Testing

Run operations at high volume and concurrency to expose race conditions:

testing_strategies.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
#include <pthread.h>
#include <stdio.h>
#include <assert.h>
#include <stdlib.h>
 
// =====================================================
// Stress Test: High Volume Concurrent Operations
// =====================================================
 
#define NUM_PRODUCERS 10
#define NUM_CONSUMERS 10
#define ITEMS_PER_PRODUCER 10000
 
buffer_t test_buffer;
int items_produced = 0;
int items_consumed = 0;
pthread_mutex_t counter_mutex = PTHREAD_MUTEX_INITIALIZER;
 
void *stress_producer(void *arg) {
    for (int i = 0; i < ITEMS_PER_PRODUCER; i++) {
        void *item = malloc(sizeof(int));
        *(int *)item = rand();
        
        buffer_status_t s = buffer_put(&test_buffer, item, 10000);
        assert(s == BUF_OK);
        
        pthread_mutex_lock(&counter_mutex);
        items_produced++;
        pthread_mutex_unlock(&counter_mutex);
    }
    return NULL;
}
 
void *stress_consumer(void *arg) {
    while (1) {
        void *item;
        buffer_status_t s = buffer_get(&test_buffer, &item, 100);
        
        if (s == BUF_TIMEOUT) continue;
        if (s == BUF_SHUTDOWN) break;
        
        free(item);
        
        pthread_mutex_lock(&counter_mutex);
        items_consumed++;
        pthread_mutex_unlock(&counter_mutex);
    }
    return NULL;
}
 
void run_stress_test(void) {
    buffer_init(&test_buffer, 100);
    
    pthread_t producers[NUM_PRODUCERS];
    pthread_t consumers[NUM_CONSUMERS];
    
    for (int i = 0; i < NUM_CONSUMERS; i++) {
        pthread_create(&consumers[i], NULL, stress_consumer, NULL);
    }
    for (int i = 0; i < NUM_PRODUCERS; i++) {
        pthread_create(&producers[i], NULL, stress_producer, NULL);
    }
    
    for (int i = 0; i < NUM_PRODUCERS; i++) {
        pthread_join(producers[i], NULL);
    }
    
    // Wait for consumers to drain
    while (items_consumed < items_produced) {
        usleep(1000);
    }
    
    buffer_shutdown(&test_buffer);
    
    for (int i = 0; i < NUM_CONSUMERS; i++) {
        pthread_join(consumers[i], NULL);
    }
    
    printf("Produced: %d, Consumed: %d\n", items_produced, items_consumed);
    assert(items_produced == items_consumed);
    printf("STRESS TEST PASSED\n");
}
 
// =====================================================
// Instrumentation: Track Wait Statistics
// =====================================================
 
typedef struct {
    int wait_count;
    int wakeup_count;
    int spurious_wakeup_count;
} wait_stats_t;
 
__thread wait_stats_t thread_stats;
 
void instrumented_wait(pthread_cond_t *cond, pthread_mutex_t *mutex,
                       bool *predicate) {
    thread_stats.wait_count++;
    
    while (!*predicate) {
        pthread_cond_wait(cond, mutex);
        thread_stats.wakeup_count++;
        
        if (!*predicate) {
            thread_stats.spurious_wakeup_count++;
        }
    }
}

Testing Approaches

•Stress testing — High volume with many threads exposes races that rarely occur with low volume.
•Delay injection — Add random delays to increase race window visibility.
•ThreadSanitizer — Use -fsanitize=thread to detect data races at runtime.
•Helgrind (Valgrind) — Another race detector with different detection algorithms.
•Assertion-heavy code — Assert invariants frequently; fail fast on corruption.
•Instrumentation — Track wait/wakeup statistics to detect unexpected spurious wakeups.
•Deterministic testing — Record and replay thread schedules for reproducibility.

Run Under Sanitizers

Summary

This page has consolidated pthread condition variable usage into production-ready patterns. These patterns represent decades of collective experience in concurrent programming.

Key Takeaways

•The Canonical Pattern — Lock, while(!predicate) wait, do work, unlock. This is mandatory and universal.
•Producer-Consumer — Two condition variables (not_empty, not_full), signal for single-item operations.
•Thread Pool — Workers wait for tasks, signal on submit, broadcast on shutdown.
•Readers-Writers — Broadcast for readers (multiple can proceed), signal for writers (one at a time).
•Defensive Patterns — Cleanup handlers, CLOCK_MONOTONIC, status return values.
•Anti-Patterns — if instead of while, checking without lock, different mutexes, busy waiting.
•Testing — Stress tests, ThreadSanitizer, instrumentation. Test under adverse conditions.

Module Complete: Pthread Condition Variables

5 / 5