Skip to content
Tutorials Center
My learning

Topics

Lesson 135 of 171 ยท Concurrency

Condition Variables

Learn std::condition_variable in C++ - wait with a predicate, notify_one and notify_all, spurious and lost wakeups, a producer-consumer queue, timeouts and stop tokens.

Mutexes stop threads from touching shared data at the same time, but they don't help a thread wait for something to happen: "wait until the queue has an item", "wait until the download finished", "wait until all workers are ready". You could loop, locking the mutex and checking a flag over and over, but that either burns CPU time (a busy loop) or adds delay (a loop with sleep_for). Neither is acceptable in a server or a game.

A condition variable solves this. A thread that needs a condition goes to sleep on the condition variable, using no CPU at all, and another thread that changes the shared state wakes it with a notification. In this lesson you'll learn the one correct way to wait (with a predicate), why spurious and lost wakeups exist, how to build a thread-safe producer-consumer queue with shutdown, how to wait with timeouts and stop tokens, and which C++20 tools (std::latch, std::barrier, semaphores) replace condition variables for common patterns.

The pattern: a mutex, a condition and a condition variable

std::condition_variable from <condition_variable> always works together with a std::mutex and some shared state that the mutex protects. The waiting side and the notifying side follow fixed recipes:

Waiting thread:

  1. Lock the mutex with a std::unique_lock (not lock_guard: the wait must be able to unlock it).
  2. Call cv.wait(lock, predicate). It checks the predicate; if it's false, it atomically unlocks the mutex and sleeps. When woken, it relocks the mutex and checks the predicate again, and only returns once the predicate is true.
  3. Use the shared state, which is still protected by the lock.

Notifying thread:

  1. Lock the mutex and change the shared state.
  2. Unlock (or let the lock guard end).
  3. Call cv.notify_one() (wake one waiter) or cv.notify_all() (wake every waiter).
C++ Waiting for a ready signal

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The two "main: notified" and "worker: got ..." lines may appear in either order: after the notification both threads are runnable. But the worker can never print the configuration before it's set, because it only gets past wait once ready is true, and it reads config under the same mutex that main held while writing it.

The predicate overload is just a shorthand for this loop, which you'll see in older code:

C++
std::unique_lock lock{mutex};
while (!ready) {          // re-check after every wakeup
    ready_cv.wait(lock);  // unlocks, sleeps, relocks
}

Why the predicate is mandatory: spurious and lost wakeups

Never call wait(lock) without checking a condition. Two problems make a bare wait wrong:

  • Spurious wakeups. A waiting thread may wake up even though nobody notified it. The standard explicitly allows this, because it makes efficient implementations possible on every operating system. Also, by the time a notified thread gets the mutex back, another thread may have consumed what it was woken for. Either way, the thread must check the condition again.
  • Lost wakeups. A notification only wakes threads that are already waiting; it isn't stored. If the notifier runs first and the waiter calls wait afterwards, a bare wait sleeps forever. With a predicate, the waiter checks ready first, sees it's already true and doesn't sleep at all.

That second point is also why the state must change under the mutex, even if it's a simple bool. If the notifier set ready = true without the lock, it could happen right between the waiter's check and the moment it goes to sleep, and the notification would be lost. (An unlocked write to a shared bool would also be a data race.)

C++ Notifying before anyone waits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The last line always prints counter = 3: the waiter might wake up after the first or second notification (or not at all until the third), but each time it re-checks counter >= 3 and goes back to sleep if it's false.

A producer-consumer queue

The most important use of condition variables is a blocking queue: producer threads push work items, consumer threads pop them, and each side sleeps when it can't proceed. A bounded queue also makes producers wait when it's full, which stops a fast producer from filling all memory. That needs two conditions: "not empty" for consumers and "not full" for producers. Using two condition variables means each notification wakes the right kind of thread.

A real queue also needs a way to shut down: when producers are finished, close() wakes every consumer, and pop() returns an empty std::optional once the queue is closed and drained.

C++ A bounded blocking queue

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

All 1,000 items are consumed exactly once and the sums match, every run. How the work is split among the three consumers depends on scheduling and changes between runs. A few details make this queue correct:

  • Every wait has a predicate that includes closed_, so closing wakes and releases every waiting thread.
  • close() uses notify_all, because all waiters must react. push and pop use notify_one, because one new item (or one free slot) can only help one thread.
  • Notifying after unlocking avoids waking a thread that would immediately block on the still-locked mutex. Notifying while still holding the lock is also correct, just slightly less efficient.
  • Values are moved out of the queue under the lock, then the work happens outside it, in the consumer loop.

Waiting with a timeout

Sometimes you want to wait only so long: "wait up to 100 ms for a reply, then retry", or "give up on the job if no worker picks it up". Condition variables have timed versions that take chrono types:

  • cv.wait_for(lock, duration, predicate) and cv.wait_until(lock, time_point, predicate) return bool: the predicate's value at the end. false means the time ran out with the condition still false.
  • Without a predicate they return std::cv_status::timeout or std::cv_status::no_timeout, but then you're back to handling spurious wakeups yourself, so prefer the predicate versions.
C++ wait_for with a deadline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The fast server answers well within its 100 ms budget; the slow one misses its 50 ms deadline, so wait_for returns false and we report a timeout. (The program still waits for the slow server's thread at the end, because the jthread joins when main returns.) Use wait_until with a fixed deadline when you wait in a loop, so repeated waits don't keep extending the total time.

Stopping waiters with std::stop_token (C++20)

A thread blocked in wait can't check a stop token because it's asleep. std::condition_variable_any (which works with any lockable type) has a C++20 overload that solves this: cv.wait(lock, stop_token, predicate). It wakes up when the predicate becomes true or when stop is requested, and returns the predicate's value. That makes std::jthread workers that wait on a condition easy to cancel.

C++ A cancellable worker with condition_variable_any

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

When main ends, the jthread destructor requests stop. That wakes the worker from wait even though no notification was sent, the call returns false because there are no jobs, and the worker exits cleanly. The sleeps give the worker time to handle each job before the next one arrives, so the output normally shows the three jobs in order and 3 handled; the shutdown path itself doesn't depend on timing.

Higher-level tools in C++20

Condition variables are the general-purpose building block. For three common patterns, C++20 offers ready-made, harder-to-misuse types:

Type Header Purpose
std::latch <latch> A one-shot countdown: threads call count_down(), others wait() until it reaches zero. "Start when all 8 workers are ready."
std::barrier <barrier> A reusable meeting point: each phase, all threads arrive_and_wait(), an optional completion function runs, and the next phase starts.
std::counting_semaphore<N>, std::binary_semaphore <semaphore> A counter of permits: acquire() takes one (waiting if none are left), release() gives one back. "At most 3 downloads at a time."
C++
std::latch all_ready{4};
for (int i = 0; i < 4; ++i) {
    workers.emplace_back([&all_ready] {
        prepare();
        all_ready.count_down();   // one more worker ready
    });
}
all_ready.wait();                 // main continues once all 4 have counted down

Use these when they fit; reach for a condition variable when you need a custom condition, such as a queue. For handing a single result from one thread to another, std::promise and std::future are simpler still.

Common mistakes

  • Waiting without a predicate. Spurious and lost wakeups make a bare wait unreliable. Always use the predicate overloads (or an explicit while loop).
  • Changing the condition without holding the mutex. Even for a bool, change it under the same mutex the waiter uses, or the notification can slip between the waiter's check and its sleep.
  • Using std::lock_guard with wait. It doesn't compile: wait needs a std::unique_lock<std::mutex> that it can unlock and relock.
  • notify_one when several threads must react, such as on shutdown. Use notify_all.
  • Doing the work while holding the lock. Take the item out under the lock, unlock, then process it.
  • Destroying a condition variable while threads still wait on it. Join (or wake and finish) all waiters first, which jthread and a close() method make easy.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does cv.wait(lock, [&] { return ready; }); do when ready is already true?

    The predicate is checked first. If it is already true, wait returns at once with the lock still held. This is what protects against lost wakeups.
  2. 2. Why must a waiting thread re-check its condition after waking up?

    Waking up only means "check again". The predicate overload of wait does the re-checking for you.
  3. 3. A notifier sets a shared bool ready = true WITHOUT locking the mutex, then calls notify_one(). What can go wrong?

    The waiter checks the predicate and goes to sleep under the mutex. Changing the state under the same mutex prevents the change and notification from slipping into that gap.
  4. 4. In a blocking queue, which call should close() use to wake the consumers?

    Every waiting consumer needs to wake up, see closed_ and return. notify_one would leave the others asleep forever.
  5. 5. bool ok = cv.wait_for(lock, 50ms, pred); returns false. What does that mean?

    The predicate overloads of wait_for and wait_until return the final value of the predicate, so false means the condition did not become true in time.

Summary

  • A condition variable lets threads sleep until shared state changes; it always pairs with a std::mutex and a condition protected by that mutex.
  • Wait with cv.wait(unique_lock, predicate): it unlocks while sleeping, relocks on wakeup and returns only when the predicate holds, which handles spurious and lost wakeups.
  • Change the state under the mutex, then call notify_one() (one thread can make progress) or notify_all() (everyone must react, such as on shutdown).
  • A bounded blocking queue uses two condition variables (not empty, not full) and a closed flag for clean shutdown.
  • wait_for/wait_until with a predicate return false on timeout; condition_variable_any::wait(lock, stop_token, pred) lets jthread workers be cancelled while waiting.
  • For countdowns, phases and permit counting, prefer C++20's std::latch, std::barrier and std::counting_semaphore.

Next: Atomics and the Memory Model, where you'll synchronize simple values without any locks at all.