Timeouts with Condition Variables

From Infinite to Bounded Waiting

The function pthread_cond_wait blocks a thread until it is signaled. If no signal ever comes, the thread waits forever. pthread_cond_timedwait provides an escape hatch. It behaves just like pthread_cond_wait but adds a deadline.

Let's look at its signature and compare it to the one we already know.

int pthread_cond_wait(pthread_cond_t *restrict cond, pthread_mutex_t *restrict mutex);

int pthread_cond_timedwait(pthread_cond_t *restrict cond, 
                           pthread_mutex_t *restrict mutex,
                           const struct timespec *restrict abstime);

The new element is the third argument, abstime. This is a pointer to a struct timespec that specifies an absolute time in the future when the wait should expire. It is not a relative duration.

Specifying the Absolute Timeout

To use pthread_cond_timedwait, you must provide a deadline. This involves two steps:

1. Get the current time.
2. Add your desired wait duration to the current time to calculate the future deadline.

The struct timespec has two fields:

• tv_sec: Whole seconds since the Epoch (00:00:00 UTC, January 1, 1970).
• tv_nsec: Nanoseconds within the current second.

The modern and most precise POSIX function to get the current time is clock_gettime(). We typically use it with the CLOCK_REALTIME clock, which represents the system's wall-clock time.

Here's how you would calculate a deadline 5 seconds in the future:

#include <time.h> // For clock_gettime and struct timespec

// ... inside a function ...

struct timespec deadline;

// Get the current wall-clock time
clock_gettime(CLOCK_REALTIME, &deadline);

// Add 5 seconds to the current time
deadline.tv_sec += 5; 

This deadline struct can now be passed to pthread_cond_timedwait.

Why an Absolute Time?

You might wonder why the API demands an absolute deadline instead of a simpler relative duration (e.g., "wait for 5 seconds"). This design choice is a deliberate and crucial feature to prevent a subtle race condition.

In short, by using an absolute deadline, the wait time is correct even if the thread is preempted. Furthermore, inside our while loop, if a spurious wakeup occurs, we can reuse the same deadline for the next call to pthread_cond_timedwait without any recalculation.

Handling the Timeout in Your Code

When pthread_cond_timedwait returns, you must check its return value to know what happened.

• A return value of 0: Success. The condition variable was signaled, and the thread was woken up normally. The predicate might be true, but you still need to check it, just as with pthread_cond_wait.
• A return value of ETIMEDOUT: The deadline passed before the condition was signaled. This is the timeout case.
• Other non-zero values: An error occurred (e.g., invalid arguments).

Let's see how to integrate this into our "wait-in-a-loop" pattern.

Combining the robust clock_gettime approach with this error handling gives us a canonical pattern. Let's imagine a consumer thread trying to get an item from a queue but willing to wait only 2 seconds.

// Assume 'mutex' and 'cond_not_empty' are initialized
// Assume 'is_queue_empty()' is our predicate function

pthread_mutex_lock(&mutex);

// Calculate the deadline BEFORE the loop
struct timespec deadline;
clock_gettime(CLOCK_REALTIME, &deadline);
deadline.tv_sec += 2; // Wait for 2 seconds

int wait_result = 0;
while (is_queue_empty() && wait_result != ETIMEDOUT) {
    // The wait_result will be 0 on signal/spurious wakeup, ETIMEDOUT on timeout
    wait_result = pthread_cond_timedwait(&cond_not_empty, &mutex, &deadline);
}

// After the loop, check WHY we exited
if (wait_result == ETIMEDOUT) {
    printf("Timed out waiting for an item.\n");
} else {
    // We exited because the queue is not empty.
    // We can safely get the item now.
    printf("Item available, proceeding to consume.\n");
    // ... code to get item from queue ...
}

pthread_mutex_unlock(&mutex);

This logic is robust. It correctly handles signals, spurious wakeups, and timeouts, all while using the efficient absolute time mechanism.

// BUGGY CODE
struct timespec deadline;
int rc = 0;

pthread_mutex_lock(&mutex);
while (!work_done && rc != ETIMEDOUT) {
    // Recalculating the deadline inside the loop
    clock_gettime(CLOCK_REALTIME, &deadline);
    deadline.tv_sec += 1;
    rc = pthread_cond_timedwait(&cond, &mutex, &deadline);
}
pthread_mutex_unlock(&mutex);

Conclusion

You have now added a powerful and essential tool to your concurrency toolkit. pthread_cond_timedwait allows you to break out of potentially infinite waits, making your programs more robust and responsive.

Key Takeaways:

• pthread_cond_timedwait adds a timeout capability to pthread_cond_wait.
• It requires an absolute time deadline via a struct timespec, not a relative duration.
• You should calculate the deadline before the wait loop using clock_gettime(CLOCK_REALTIME, ...) and addition.
• The use of absolute time prevents race conditions and avoids the need to recalculate the timeout after a spurious wakeup.
• Always check the return value: 0 means a signal was likely received, while ETIMEDOUT indicates the deadline passed.

Preview of the Next Lesson:
We have now fully covered the essential tools for complex synchronization: mutexes for mutual exclusion, and condition variables for coordination (with and without timeouts). In the next lesson, we will synthesize all of this knowledge to tackle a classic concurrency problem. We will design the complete logic for a thread-safe bounded buffer, which is the heart of the producer-consumer pattern.