7a:T55b,In the landscape of concurrent programming, **condition variables** represent one of the most powerful and essential synchronization primitives. While mutexes provide mutual exclusion—ensuring only one thread can access shared state at a time—they cannot express the equally important concept of **waiting for a condition to become true**. Consider a bounded buffer where producer threads add items and consumer threads remove them. A consumer encountering an empty buffer needs to wait efficiently until data becomes available. Simply releasing and re-acquiring a mutex in a loop (busy-waiting) wastes CPU cycles. What's needed is a mechanism to **suspend the thread until another thread signals that the buffer is no longer empty**. This is precisely what condition variables provide. In the POSIX Threads (pthreads) standard—the dominant threading API on Unix-like systems—condition variables are embodied in the **`pthread_cond_t`** type. This fundamental type, along with its associated operations, enables threads to coordinate based on arbitrary conditions while maintaining efficiency and correctness. This page provides a comprehensive, production-grade exploration of `pthread_cond_t`—its design philosophy, internal structure, initialization patterns, destruction requirements, and the critical role it plays in building robust concurrent systems.7b:T693,#include #include // ===================================================== // SCOPE 1: Global/Static Condition Variable // ===================================================== // Suitable for program-wide coordination // Lifetime: entire program execution pthread_cond_t global_cond = PTHREAD_COND_INITIALIZER; pthread_mutex_t global_mutex = PTHREAD_MUTEX_INITIALIZER; // ===================================================== // SCOPE 2: Struct-Embedded Condition Variable // ===================================================== // Condition variable as part of a data structure // Lifetime: same as the containing structure typedef struct { pthread_mutex_t mutex; pthread_cond_t not_empty; // Signaled when buffer becomes non-empty pthread_cond_t not_full; // Signaled when buffer becomes non-full int *buffer; int capacity; int count; int head; int tail; } bounded_buffer_t; // ===================================================== // SCOPE 3: Heap-Allocated (via containing struct) // ===================================================== bounded_buffer_t *buffer_create(int capacity) { bounded_buffer_t *buf = malloc(sizeof(bounded_buffer_t)); if (!buf) return NULL; buf->buffer = malloc(sizeof(int) * capacity); if (!buf->buffer) { free(buf); return NULL; } // Must use pthread_*_init for heap-allocated objects pthread_mutex_init(&buf->mutex, NULL); pthread_cond_init(&buf->not_empty, NULL); pthread_cond_init(&buf->not_full, NULL); buf->capacity = capacity; buf->count = 0; buf->head = 0; buf->tail = 0; return buf; }7c:T459,#include // ===================================================== // Static Initialization: The Simplest Approach // ===================================================== // Global condition variable - initialized at compile time static pthread_mutex_t g_mutex = PTHREAD_MUTEX_INITIALIZER; static pthread_cond_t g_data_ready = PTHREAD_COND_INITIALIZER; static int g_data_available = 0; void producer(void) { pthread_mutex_lock(&g_mutex); // Produce data... g_data_available = 1; pthread_cond_signal(&g_data_ready); pthread_mutex_unlock(&g_mutex); } void *consumer(void *arg) { pthread_mutex_lock(&g_mutex); while (!g_data_available) { // Wait releases mutex, blocks, reacquires mutex on wakeup pthread_cond_wait(&g_data_ready, &g_mutex); } // Consume data... g_data_available = 0; pthread_mutex_unlock(&g_mutex); return NULL; } // Note: Static initialization means no pthread_cond_destroy() // is strictly required for global variables (though it's good practice // in library code that might be unloaded).7d:T630,#include #include #include #include // ===================================================== // Dynamic Initialization: For Runtime-Created Objects // ===================================================== typedef struct work_queue { pthread_mutex_t mutex; pthread_cond_t not_empty; // ... queue data } work_queue_t; // Proper initialization with error handling work_queue_t *work_queue_create(void) { work_queue_t *wq = malloc(sizeof(work_queue_t)); if (!wq) { return NULL; } // Initialize mutex first int rc = pthread_mutex_init(&wq->mutex, NULL); if (rc != 0) { fprintf(stderr, "mutex init failed: %d ", rc); free(wq); return NULL; } // Then initialize condition variable rc = pthread_cond_init(&wq->not_empty, NULL); if (rc != 0) { fprintf(stderr, "cond init failed: %d ", rc); // Must clean up already-initialized mutex! pthread_mutex_destroy(&wq->mutex); free(wq); return NULL; } // Initialize other fields... return wq; } // Corresponding destruction void work_queue_destroy(work_queue_t *wq) { if (!wq) return; // Destroy in reverse order of initialization int rc = pthread_cond_destroy(&wq->not_empty); if (rc != 0) { fprintf(stderr, "Warning: cond destroy failed: %d ", rc); } rc = pthread_mutex_destroy(&wq->mutex); if (rc != 0) { fprintf(stderr, "Warning: mutex destroy failed: %d ", rc); } free(wq); }7e:T764,#include #include #include // ===================================================== // Configuring Condition Variable Attributes // ===================================================== // Example 1: Process-Shared Condition Variable // (For use in shared memory between processes) int create_shared_condvar(pthread_cond_t *cond) { pthread_condattr_t attr; int rc; rc = pthread_condattr_init(&attr); if (rc != 0) return rc; // Enable process sharing rc = pthread_condattr_setpshared(&attr, PTHREAD_PROCESS_SHARED); if (rc != 0) { pthread_condattr_destroy(&attr); return rc; } rc = pthread_cond_init(cond, &attr); pthread_condattr_destroy(&attr); // Always clean up return rc; } // Example 2: Monotonic Clock for Robust Timeouts // CRITICAL: Use CLOCK_MONOTONIC to prevent issues with system time changes int create_monotonic_condvar(pthread_cond_t *cond) { pthread_condattr_t attr; int rc; rc = pthread_condattr_init(&attr); if (rc != 0) return rc; // Use monotonic clock for timedwait // This prevents spurious timeouts/waits when system time is adjusted rc = pthread_condattr_setclock(&attr, CLOCK_MONOTONIC); if (rc != 0) { pthread_condattr_destroy(&attr); return rc; } rc = pthread_cond_init(cond, &attr); pthread_condattr_destroy(&attr); return rc; } // Example 3: Query Current Attributes void print_condvar_attributes(pthread_condattr_t *attr) { int pshared; clockid_t clock_id; pthread_condattr_getpshared(attr, &pshared); pthread_condattr_getclock(attr, &clock_id); printf("Process-shared: %s ", pshared == PTHREAD_PROCESS_SHARED ? "yes" : "no"); printf("Clock: %s ", clock_id == CLOCK_MONOTONIC ? "MONOTONIC" : "REALTIME"); }7f:T8f9,#include #include #include #include // ===================================================== // Safe Destruction Patterns // ===================================================== typedef struct { pthread_mutex_t mutex; pthread_cond_t cond; bool shutdown; int waiting_count; // Track waiters for safe shutdown // ... other fields } worker_pool_t; // Pattern 1: Graceful Shutdown with Coordination void worker_pool_shutdown(worker_pool_t *pool) { pthread_mutex_lock(&pool->mutex); // Signal shutdown to all workers pool->shutdown = true; // Wake ALL waiting threads so they can exit pthread_cond_broadcast(&pool->cond); pthread_mutex_unlock(&pool->mutex); // In a real implementation, you would join worker threads here // to ensure they've actually exited before destroying } void worker_pool_destroy(worker_pool_t *pool) { if (!pool) return; // Ensure shutdown was called first pthread_mutex_lock(&pool->mutex); if (!pool->shutdown) { pthread_mutex_unlock(&pool->mutex); fprintf(stderr, "Error: must call shutdown before destroy "); return; } // Check for remaining waiters if (pool->waiting_count > 0) { pthread_mutex_unlock(&pool->mutex); fprintf(stderr, "Error: %d threads still waiting ", pool->waiting_count); return; } pthread_mutex_unlock(&pool->mutex); // Safe to destroy now int rc = pthread_cond_destroy(&pool->cond); if (rc == EBUSY) { fprintf(stderr, "Warning: condition variable still in use "); // Handle error - this shouldn't happen if shutdown was correct } pthread_mutex_destroy(&pool->mutex); free(pool); } // Pattern 2: Worker Thread that Tracks Waiting State void *worker_thread(void *arg) { worker_pool_t *pool = (worker_pool_t *)arg; pthread_mutex_lock(&pool->mutex); while (!pool->shutdown) { // Track that we're about to wait pool->waiting_count++; pthread_cond_wait(&pool->cond, &pool->mutex); // No longer waiting pool->waiting_count--; } pthread_mutex_unlock(&pool->mutex); return NULL; }80:T521,// ===================================================== // Conceptual Internal Structure (Simplified) // Note: Actual implementations are more complex // ===================================================== struct __pthread_cond_s { // Sequence number - incremented on each signal/broadcast // Used to detect missed wakeups after spurious kernel returns unsigned int __wseq; // Wait sequence unsigned int __g1_start; // Generation 1 start // Reference counts for waiting groups unsigned int __g_refs[2]; // Group reference counts unsigned int __g_size[2]; // Group sizes // Internal state (clock type, etc.) unsigned int __g1_orig_size; unsigned int __wrefs; unsigned int __g_signals[2]; }; // Key behavioral implications: // // 1. SIGNAL WHEN NO WAITERS: // - Nearly free (just atomic increment of sequence) // - No system call needed // // 2. WAIT WITH IMMEDIATE SIGNAL AVAILABLE: // - May return immediately without blocking // - Sequence comparison detects pending signal // // 3. BLOCKING WAIT: // - Uses futex to sleep efficiently in kernel // - Thread is descheduled, consuming no CPU // // 4. WAKEUP: // - futex_wake notifies kernel to reschedule waiter // - Waking thread doesn't context-switch to waiter81:T966,#include #include // ===================================================== // MISTAKE 1: Wrong Mutex Association // ===================================================== pthread_mutex_t mutex1 = PTHREAD_MUTEX_INITIALIZER; pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; pthread_cond_t cond = PTHREAD_COND_INITIALIZER; void *thread_a(void *arg) { pthread_mutex_lock(&mutex1); pthread_cond_wait(&cond, &mutex1); // Uses mutex1 pthread_mutex_unlock(&mutex1); return NULL; } void *thread_b(void *arg) { pthread_mutex_lock(&mutex2); pthread_cond_wait(&cond, &mutex2); // WRONG: Same cond, different mutex! pthread_mutex_unlock(&mutex2); // Undefined behavior return NULL; } // CORRECT: Use the same mutex with a given condition variable // ===================================================== // MISTAKE 2: Signaling Without Mutex // ===================================================== // While technically allowed, signaling without the mutex is DANGEROUS: int data_ready = 0; void producer_wrong(void) { data_ready = 1; // Modify shared state pthread_cond_signal(&cond); // Signal without lock // Race: consumer might test data_ready==0, miss signal, // then block forever after signal is lost } void producer_correct(void) { pthread_mutex_lock(&mutex1); data_ready = 1; // Modify shared state pthread_cond_signal(&cond); // Signal WITH lock held pthread_mutex_unlock(&mutex1); // Safe: consumer either sees data_ready==1 before waiting, // or is already waiting and will be woken } // ===================================================== // MISTAKE 3: Using IF Instead of WHILE // ===================================================== void consumer_wrong(void) { pthread_mutex_lock(&mutex1); if (!data_ready) { // WRONG: if pthread_cond_wait(&cond, &mutex1); } // Spurious wakeup can leave data_ready==0 here! process_data(); // BUG: may process nonexistent data pthread_mutex_unlock(&mutex1); } void consumer_correct(void) { pthread_mutex_lock(&mutex1); while (!data_ready) { // CORRECT: while loop pthread_cond_wait(&cond, &mutex1); } // Guaranteed: data_ready==1 here process_data(); pthread_mutex_unlock(&mutex1); }72:{"json":{"id":"seed_d2004f7681f65ba7fb199a4c3f408fb4","slug":"pthread-condition-variables","category":"Operating Systems","topic":"Pthread Condition Variables","title":"Pthread Condition Variables","description":"Master the POSIX threads condition variable API—pthread_cond_t, pthread_cond_wait, pthread_cond_signal, and pthread_cond_broadcast. Understand their semantics, proper usage patterns, and how they enable sophisticated thread coordination in production systems.","difficulty":"ADVANCED","estimatedMinutes":120,"pages":[{"id":"seed_a88c17b17fda8e4ef6ed84fbc914888c","title":"pthread_cond_t","order":0,"content":[{"id":"opening-context","title":"The POSIX Condition Variable Foundation","content":[{"data":{"content":"$7a"},"type":"text"},{"data":{"icon":"Target","title":"Learning Objectives","content":"By completing this page, you will: (1) Understand the purpose and design philosophy of pthread condition variables, (2) Master the pthread_cond_t type and its relationship to mutexes, (3) Learn correct initialization using PTHREAD_COND_INITIALIZER and pthread_cond_init(), (4) Understand attribute configuration via pthread_condattr_t, (5) Know when and how to properly destroy condition variables, and (6) Recognize condition variables as the key to efficient thread coordination.","variant":"info"},"type":"callout"}]},{"id":"why-condition-variables","title":"Why Condition Variables Exist","content":[{"data":{"content":"To appreciate `pthread_cond_t`, we must first understand the problem it solves. Consider this flawed approach to the producer-consumer problem:\n\n### The Polling Disaster\n\nWithout condition variables, a consumer thread waiting for data might poll:\n\n```c\n// WRONG: Busy-waiting approach\nwhile (1) {\n pthread_mutex_lock(&mutex);\n if (buffer_count > 0) {\n // consume item\n pthread_mutex_unlock(&mutex);\n break;\n }\n pthread_mutex_unlock(&mutex);\n // Brief sleep to reduce CPU waste... but how long?\n usleep(1000); // Still wastes resources\n}\n```\n\nThis approach has severe problems:\n\n1. **CPU Waste**: Even with sleep, the thread burns cycles checking repeatedly\n2. **Latency**: If data arrives just after a check, the thread waits until the next poll\n3. **Tuning Nightmare**: Short sleep = high CPU; long sleep = high latency\n4. **Priority Inversion**: The consuming thread's polling can starve the producer\n5. **Unscalable**: Multiple waiters multiply the overhead"},"type":"text"},{"data":{"icon":"AlertCircle","title":"The Fundamental Problem","content":"Mutexes solve 'who can access data' but not 'when should I access data'. A thread that acquires a mutex but finds the data isn't ready yet has no efficient recourse. Releasing and busy-waiting wastes CPU. What's needed is a way to release the mutex AND sleep atomically, waking only when the condition might have changed.","variant":"warning"},"type":"callout"},{"data":{"content":"### The Condition Variable Solution\n\nCondition variables solve this by providing two key operations:\n\n1. **Wait**: Atomically release the mutex and suspend the thread until signaled\n2. **Signal/Broadcast**: Wake one or all threads waiting on the condition\n\nThe critical insight is the **atomicity of wait**. The thread releases the mutex and sleeps in a single indivisible operation. This prevents the **lost wakeup problem**—if signal occurred between releasing the mutex and sleeping, the wait would miss it.\n\n### The Mental Model\n\nThink of a condition variable as a **waiting room** attached to a mutex-protected resource:\n\n- Threads that find the resource not ready enter the waiting room (wait)\n- The thread that makes the resource ready announces it (signal/broadcast)\n- Waiting threads wake up and re-compete for the mutex\n\nThis model enables efficient, event-driven thread coordination without polling."},"type":"text"},{"data":{"items":["**Efficient Waiting** — Blocked threads consume no CPU cycles while waiting for conditions to change.","**Event-Driven Wakeup** — Threads wake precisely when conditions might have changed, not on arbitrary timeouts.","**Atomic Release-and-Wait** — The mutex release and thread suspension happen indivisibly, preventing lost wakeups.","**Flexible Coordination** — Any boolean condition expressible in code can be waited upon.","**Scalable Design** — Multiple threads can wait on the same condition without multiplicative overhead."],"title":{"icon":"CheckCircle","text":"What Condition Variables Provide","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}],"titleType":"number","titleNumber":1},{"id":"pthread-cond-t-type","title":"The pthread_cond_t Type","content":[{"data":{"content":"**`pthread_cond_t`** is the POSIX data type representing a condition variable. It is defined in `` and is the central type for all condition variable operations.\n\n### Type Characteristics\n\n`pthread_cond_t` is an **opaque type**—its internal structure is implementation-defined and should never be accessed directly by applications. The type might be:\n\n- A structure containing kernel synchronization handles\n- An index into a kernel-managed table\n- A structure with embedded wait queues and state\n\nDifferent POSIX implementations (glibc/NPTL on Linux, libc on macOS, etc.) have different internal representations, but the API remains consistent.\n\n### Declaration and Scope\n\nCondition variables are typically declared in one of three scopes:\n\n1. **Global/Static**: For coordination across an entire program\n2. **Struct Members**: Embedded in data structures they protect\n3. **Heap-Allocated**: For dynamic synchronization objects\n\nThe choice of scope affects initialization strategy and lifetime management."},"type":"text"},{"data":{"code":"$7b","fileName":"pthread_cond_declarations.c","showLineNumbers":true},"type":"code"},{"data":{"content":"### The Mutex Relationship\n\nA critical aspect of `pthread_cond_t` is its **inseparable relationship with a mutex**. Every condition variable operation that involves waiting *requires* an associated mutex. This relationship exists because:\n\n1. **The condition being waited upon is protected state**\n2. **Checking and waiting must be atomic**\n3. **Signaling threads must hold the mutex to modify state**\n\nThe pattern is:\n\n```\nlock(mutex)\nwhile (!condition) {\n wait(cond, mutex) // Releases mutex while waiting\n}\n// Condition is true, mutex is held\ndo_work()\nunlock(mutex)\n```\n\nThe mutex is *always* held when checking the condition. The wait operation atomically releases it and reacquires it before returning. This atomicity prevents race conditions between checking and waiting."},"type":"text"},{"data":{"icon":"Info","title":"One Mutex, Multiple Condition Variables","content":"A single mutex can be associated with multiple condition variables. For example, a bounded buffer uses one mutex with two conditions: 'not_empty' (for consumers) and 'not_full' (for producers). However, a single condition variable should be used with only ONE mutex throughout its lifetime—mixing mutexes leads to undefined behavior.","variant":"note"},"type":"callout"},{"data":{"rows":[["pthread_cond_init()","Initialize a condition variable","Not required"],["pthread_cond_destroy()","Destroy a condition variable","Not required"],["pthread_cond_wait()","Wait for signal (blocks)","Must be held; released during wait"],["pthread_cond_timedwait()","Wait with timeout","Must be held; released during wait"],["pthread_cond_signal()","Wake one waiter","Typically held (not required)"],["pthread_cond_broadcast()","Wake all waiters","Typically held (not required)"]],"caption":"pthread_cond_t API Overview","headers":["Function","Purpose","Mutex State"]},"type":"table"}],"titleType":"number","titleNumber":2},{"id":"initialization-strategies","title":"Initialization Strategies","content":[{"data":{"content":"Proper initialization of `pthread_cond_t` is essential for correct behavior. POSIX provides two initialization methods, each suited to different use cases.\n\n### Method 1: Static Initialization\n\nFor condition variables with static storage duration (global or static local), POSIX provides the `PTHREAD_COND_INITIALIZER` macro:\n\n```c\npthread_cond_t cond = PTHREAD_COND_INITIALIZER;\n```\n\nThis macro expands to a brace-enclosed initializer that sets the condition variable to a valid initial state with default attributes. It is evaluated at compile time, incurring **zero runtime cost**.\n\n**Advantages of static initialization:**\n- No runtime initialization code required\n- No possibility of initialization failure\n- Thread-safe by C standards (initialized before main())\n- Simpler code with fewer error paths\n\n**Limitations:**\n- Only works for static/global variables\n- Uses default attributes only\n- Cannot be used for heap-allocated condition variables\n- Cannot be used for struct members initialized at runtime"},"type":"text"},{"data":{"code":"$7c","fileName":"static_initialization.c","showLineNumbers":true},"type":"code"},{"data":{"content":"### Method 2: Dynamic Initialization with pthread_cond_init()\n\nFor condition variables that are:\n- Heap-allocated\n- Members of dynamically created structures \n- Requiring non-default attributes\n\n...you must use `pthread_cond_init()`:\n\n```c\nint pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr);\n```\n\n**Parameters:**\n- `cond`: Pointer to the condition variable to initialize\n- `attr`: Pointer to attributes, or NULL for defaults\n\n**Return Value:**\n- `0` on success\n- Error code on failure (e.g., `EAGAIN`, `ENOMEM`, `EBUSY`)"},"type":"text"},{"data":{"code":"$7d","fileName":"dynamic_initialization.c","showLineNumbers":true},"type":"code"},{"data":{"icon":"AlertCircle","title":"Initialization Errors Are Real","content":"Unlike some resources, pthread_cond_init() CAN fail. Common failures include: EAGAIN (system lacked resources), ENOMEM (insufficient memory), EINVAL (invalid attributes). Production code must check return values. Ignoring failures leads to undefined behavior when the uninitialized condition variable is used.","variant":"warning"},"type":"callout"},{"data":{"content":"### Initialization Error Codes\n\nUnderstanding possible errors helps write robust code:"},"type":"text"},{"data":{"rows":[["EAGAIN","Insufficient resources (non-memory)","System limit on condition variables reached"],["ENOMEM","Insufficient memory","System cannot allocate required memory"],["EBUSY","Already initialized","Attempting to reinitialize an active cond var"],["EINVAL","Invalid attributes","attr points to invalid pthread_condattr_t"]],"caption":"pthread_cond_init() Error Codes","headers":["Error","Meaning","Typical Cause"]},"type":"table"}],"titleType":"number","titleNumber":3},{"id":"condvar-attributes","title":"Condition Variable Attributes","content":[{"data":{"content":"While most applications use default attributes (passing `NULL` to `pthread_cond_init()`), POSIX allows configuration through **`pthread_condattr_t`**. These attributes must be initialized, configured, and destroyed using dedicated functions.\n\n### Attribute Lifecycle\n\n```c\npthread_condattr_t attr;\n\n// 1. Initialize attribute object\npthread_condattr_init(&attr);\n\n// 2. Configure desired attributes\npthread_condattr_setpshared(&attr, PTHREAD_PROCESS_SHARED);\npthread_condattr_setclock(&attr, CLOCK_MONOTONIC);\n\n// 3. Use attribute to initialize condition variable\npthread_cond_t cond;\npthread_cond_init(&cond, &attr);\n\n// 4. Destroy attribute object (cond variable retains settings)\npthread_condattr_destroy(&attr);\n\n// 5. Use condition variable...\n\n// 6. Eventually destroy condition variable\npthread_cond_destroy(&cond);\n```\n\n### Available Attributes\n\nPOSIX defines two condition variable attributes:"},"type":"text"},{"data":{"items":["**Process-Shared (pshared)** — Determines whether the condition variable can be shared between processes (in shared memory) or only between threads of a single process. Values: PTHREAD_PROCESS_PRIVATE (default) or PTHREAD_PROCESS_SHARED.","**Clock Selection** — Specifies which clock pthread_cond_timedwait() uses for its timeout. Values: CLOCK_REALTIME (default, wall-clock time) or CLOCK_MONOTONIC (steady clock, immune to system time changes). This attribute is particularly important for robust timeout handling."],"title":{"icon":"Target","text":"pthread_condattr_t Attributes","type":"icon","color":"primary","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"code":"$7e","fileName":"condvar_attributes.c","showLineNumbers":true},"type":"code"},{"data":{"icon":"Lightbulb","title":"CLOCK_MONOTONIC: The Production Choice","content":"For any code using pthread_cond_timedwait(), strongly consider CLOCK_MONOTONIC. Wall-clock time (CLOCK_REALTIME) can jump forward or backward due to NTP adjustments, daylight saving, or manual changes. A wait intended for 5 seconds could become instant (if time jumps forward) or very long (if time jumps backward). CLOCK_MONOTONIC is immune to these issues.","variant":"tip"},"type":"callout"},{"data":{"rows":[["pthread_condattr_init()","Initialize attribute object with defaults"],["pthread_condattr_destroy()","Destroy attribute object, freeing resources"],["pthread_condattr_setpshared()","Set process-sharing mode"],["pthread_condattr_getpshared()","Query process-sharing mode"],["pthread_condattr_setclock()","Set clock for timedwait operations"],["pthread_condattr_getclock()","Query clock setting"]],"caption":"Condition Variable Attribute Functions","headers":["Function","Purpose"]},"type":"table"}],"titleType":"number","titleNumber":4},{"id":"destruction-cleanup","title":"Destruction and Cleanup","content":[{"data":{"content":"Proper destruction of condition variables is essential for preventing resource leaks and undefined behavior. The `pthread_cond_destroy()` function releases any resources associated with a condition variable.\n\n### The pthread_cond_destroy() Function\n\n```c\nint pthread_cond_destroy(pthread_cond_t *cond);\n```\n\n**Parameters:**\n- `cond`: Pointer to the condition variable to destroy\n\n**Return Value:**\n- `0` on success\n- `EBUSY` if threads are waiting on the condition variable\n- `EINVAL` if the condition variable is invalid\n\n### Destruction Requirements\n\nDestroying a condition variable has strict preconditions:"},"type":"text"},{"data":{"items":["**No Waiting Threads** — No threads may be blocked on the condition variable. Destroying with waiters is undefined behavior (may return EBUSY on some implementations).","**No Concurrent Operations** — No thread may be executing wait, signal, or broadcast on the condition variable during destruction.","**Previously Initialized** — The condition variable must have been successfully initialized. Destroying an uninitialized or previously-destroyed condition variable is undefined.","**No Future Use** — After destruction, the condition variable cannot be used until reinitialized."],"title":{"icon":"AlertCircle","text":"Preconditions for pthread_cond_destroy()","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"code":"$7f","fileName":"condvar_destruction.c","showLineNumbers":true},"type":"code"},{"data":{"icon":"AlertCircle","title":"Static Variables: To Destroy or Not?","content":"For condition variables initialized with PTHREAD_COND_INITIALIZER at global scope, destruction is technically optional since resources are reclaimed at process exit. However, calling pthread_cond_destroy() is recommended for: (1) libraries that might be dynamically unloaded, (2) code that might run under memory debuggers like Valgrind, and (3) maintaining good resource hygiene habits.","variant":"warning"},"type":"callout"},{"data":{"content":"### Reinitialization After Destruction\n\nOnce destroyed, a condition variable storage can be reinitialized:\n\n```c\npthread_cond_t cond;\npthread_cond_init(&cond, NULL);\n\n// ... use cond ...\n\npthread_cond_destroy(&cond);\n\n// Later, same storage can be reused\npthread_cond_init(&cond, NULL); // Valid\n```\n\nThis pattern is sometimes used in object pools where synchronization primitives are recycled. However, ensure complete quiescence between destruction and reinitialization—no thread should hold any reference to the condition variable during this window."},"type":"text"}],"titleType":"number","titleNumber":5},{"id":"internal-structure","title":"Internal Structure (Implementation Perspective)","content":[{"data":{"content":"While `pthread_cond_t` is an opaque type, understanding typical implementations deepens comprehension of behavior and performance characteristics.\n\n### Linux/NPTL Implementation\n\nIn the GNU C Library (glibc) using NPTL (Native POSIX Threads Library), a condition variable is implemented using the **futex** (Fast Userspace Mutex) system call. The structure conceptually contains:\n\n- **Sequence counter**: Used to detect spurious wakeups\n- **Waiter count**: Number of threads in pthread_cond_wait()\n- **Lock**: Internal spinlock for modifying cond var state\n- **Future reference**: Futex word the kernel monitors\n\nKey insight: Most operations are optimized for the **uncontended fast path**. When no one is waiting, signal() is essentially a no-op. This enables efficient usage patterns where signals often find no waiters."},"type":"text"},{"data":{"code":"$80","fileName":"conceptual_condvar_structure.c","showLineNumbers":true},"type":"code"},{"data":{"content":"### Performance Characteristics\n\nUnderstanding implementation helps predict performance:\n\n**Fast Path (Uncontended)**:\n- `pthread_cond_signal()` with no waiters: ~10-20 CPU cycles\n- `pthread_cond_wait()` when signal pending: ~50-100 cycles\n\n**Slow Path (Contended)**:\n- `pthread_cond_wait()` that blocks: ~10,000+ cycles (system call + context switch)\n- `pthread_cond_signal()` that wakes a thread: ~5,000+ cycles (system call)\n\nThe 100-1000x difference between fast and slow paths motivates design patterns that minimize contended waits."},"type":"text"},{"data":{"rows":[["signal() (no waiters)","~20 cycles","N/A","Just increments sequence counter"],["signal() (with waiters)","N/A","~5,000 cycles","Requires futex syscall"],["wait() (signal pending)","~100 cycles","N/A","Detects sequence, no block"],["wait() (must block)","N/A","~10,000+ cycles","Context switch to kernel"],["broadcast() (no waiters)","~30 cycles","N/A","Slightly more than signal"],["broadcast() (N waiters)","N/A","~5,000×N cycles","Must wake all N threads"]],"caption":"Condition Variable Performance Characteristics","headers":["Operation","No Contention","Contention","Notes"]},"type":"table"},{"data":{"icon":"Zap","title":"Design for the Fast Path","content":"Structure your code so that the common case avoids blocking. For example, in a producer-consumer scenario, keep the buffer large enough that producers rarely fill it completely. This means pthread_cond_signal() usually finds no waiters (fast) and producers never block (fastest). The slow path exists for overflow protection, not normal operation.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":6},{"id":"common-mistakes","title":"Common Mistakes and Pitfalls","content":[{"data":{"content":"Even experienced developers make mistakes with condition variables. Understanding common pitfalls prevents subtle, hard-to-debug concurrency issues."},"type":"text"},{"data":{"left":[{"data":{"items":["Using pthread_cond_t without initialization","Forgetting to check pthread_cond_init() return value","Using stack-allocated cond var after function returns"],"title":{"icon":"XCircle","text":"Mistake: Uninitialized Usage","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"accent"},"type":"list"}],"right":[{"data":{"items":["Always use PTHREAD_COND_INITIALIZER or pthread_cond_init()","Check return values in production code","Ensure lifetime exceeds all potential users"],"title":{"icon":"CheckCircle","text":"Correct: Proper Initialization","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}]},"type":"two-column"},{"data":{"code":"$81","fileName":"common_mistakes.c","showLineNumbers":true},"type":"code"},{"data":{"icon":"AlertCircle","title":"The Cardinal Rule: Always Use While, Never If","content":"POSIX explicitly permits 'spurious wakeups'—pthread_cond_wait() may return without a corresponding signal. This can happen due to OS scheduling decisions, signal handling, or implementation details. The ONLY safe pattern is to recheck the condition in a while loop after every wait return. Using 'if' instead of 'while' is a latent bug.","variant":"error"},"type":"callout"},{"data":{"items":["**Different Mutexes with Same Cond Var** — Undefined behavior. A condition variable must always be used with the same mutex.","**If Instead of While** — Spurious wakeups cause condition to be false after wait returns. Always use while.","**Signal Without Holding Mutex** — Technically allowed, but creates race conditions with state modifications. Best practice: always signal while holding the mutex.","**Destroying with Waiters** — Undefined behavior. Ensure all threads have exited wait before destroying.","**Forgetting to Initialize** — Uninitialized condition variables cause undefined behavior. Always initialize."],"title":{"icon":"AlertCircle","text":"Critical Pitfalls Summary","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"glass"},"type":"list"}],"titleType":"number","titleNumber":7},{"id":"summary","title":"Summary","content":[{"data":{"content":"We have explored `pthread_cond_t` comprehensively—from the problem it solves to its initialization, attributes, destruction, and common pitfalls. This foundation prepares us for understanding the condition variable operations in detail."},"type":"text"},{"data":{"type":"ordered","items":["**Purpose** — Condition variables enable threads to efficiently wait for arbitrary conditions to become true, eliminating wasteful polling.","**The pthread_cond_t Type** — An opaque POSIX type that must be initialized, is always used with a mutex, and must be properly destroyed.","**Static Initialization** — Use PTHREAD_COND_INITIALIZER for global/static condition variables with default attributes.","**Dynamic Initialization** — Use pthread_cond_init() for heap-allocated or attribute-customized condition variables.","**Attributes** — pthread_condattr_t configures process-sharing and clock selection (prefer CLOCK_MONOTONIC for timeouts).","**Destruction** — Call pthread_cond_destroy() when done; ensure no threads are waiting before destroying.","**Critical Rules** — Always use while (not if) for wait loops; use only one mutex per condition variable; handle initialization errors."],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"icon":"CheckCircle","title":"Foundation Established","content":"You now understand pthread_cond_t as the POSIX condition variable type—its purpose, initialization patterns, attributes, and destruction requirements. The next page dives deep into pthread_cond_wait()—the operation that atomically releases a mutex and waits for a signal, forming the heart of condition variable usage.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":8}],"isLocked":false},{"id":"seed_0bb8c07ec37f85a3a67ae0adcffd1e09","title":"pthread_cond_wait","order":1,"content":null,"isLocked":true},{"id":"seed_27ba9db8a78cc428cf062d4cbe81d353","title":"pthread_cond_signal","order":2,"content":null,"isLocked":true},{"id":"seed_6a842bd8c11969be2c910f1525c4d35b","title":"pthread_cond_broadcast","order":3,"content":null,"isLocked":true},{"id":"seed_dd1154ffe836921ac9313ea6f35dc68d","title":"Proper Usage Patterns","order":4,"content":null,"isLocked":true}]}}