Visual walkthrough — std - condition_variable

Step 0 — The three words we will use (earn the vocabulary first)

Before any diagram, three plain-word definitions. Nothing below uses a word not defined here.

Keep these four pictures in your head: worker, key, waiting-room-with-doorbell, shared box. Everything else is these four moving.

Step 1 — The naive attempt, and why it burns

WHAT. The consumer wants a number from the queue. The first idea any beginner writes:

while (queue.empty()) { /* keep looping */ }   // busy-wait

WHY it's tempting. It's literally the English sentence "while it's empty, keep checking." It works.

WHY it's wrong. Look at the picture. The consumer is checking empty() millions of times a second. Each check does nothing useful — the box is still empty — but the CPU is pinned at 100%. On a machine with one core, the consumer never lets the producer run, so the box stays empty forever. This is called a busy-wait, and it's the disease we are about to cure.

Step 2 — The shared box, guarded by one key

WHAT. We set up the shared state and its guard:

std::queue<int> q;          // the shared box of numbers
std::mutex      m;          // the ONE key to touch q
std::condition_variable cv; // the waiting room + doorbell
bool done = false;          // "producer has finished" flag

WHY. Two workers must never touch q at the same instant — that is a Race Condition. The rule: hold the key m before touching q or done. The cv is separate: it does not protect anything, it only parks and wakes sleepers.

PICTURE. The box q sits inside a locked room. The single key m hangs on a hook. Off to the side is the waiting room cv with its doorbell. Nobody is holding the key yet.

Step 3 — The consumer takes the key, then finds the box empty

WHAT.

std::unique_lock<std::mutex> lk(m);          // grab the key
cv.wait(lk, []{ return !q.empty() || done; }); // check, maybe sleep

Let us name the pieces of that second line, term by term: $\text{cv.wait}(\underset{\text{the key it holds}}{\underbrace{\text{lk}}},\underset{\text{the predicate }P()=\text{"is there work OR are we done?"}}{\underbrace{[]\{\text{return }!\text{q.empty()}||\text{done};\}}})$

WHY a unique_lock and not a lock_guard? In one step wait must let go of the key (so the producer can grab it) and later take it back. That is unlock-then-relock — a std::unique_lock can do both; a std::lock_guard can only lock once and never let go. So the waiter must use unique_lock.

WHY a predicate P()? P() is the honest question "should I be awake?" Right now the box is empty and done is false, so P() is false. Because P() is false, wait decides: there is no point staying awake → it releases the key and sleeps.

PICTURE. The consumer holds the key, peeks in the box, sees it empty. P() reads false — shown in amber.

Step 4 — The atomic magic: wait drops the key and sleeps

WHAT. Because P() was false, wait(lk) performs three things as one indivisible move: $\underset{\text{key goes back on the hook}}{\underbrace{\text{unlock}(lk)}}\to \underset{\text{enter waiting room, 0\% CPU}}{\underbrace{\text{sleep}}}\to \underset{\text{take key back on wake}}{\underbrace{\text{(later) re-lock}(lk)}}$

WHY "atomic" matters. Between "check P()" and "go to sleep" there must be no gap. If there were a gap, the producer could ring the doorbell in that gap — and the consumer, not yet asleep, would miss it and sleep forever. This is the lost wakeup race (see also Spurious Wakeup for the opposite problem). The standard promises: releasing the key and starting to sleep happen together, so a notify can never slip into a crack.

PICTURE. The consumer's face is now asleep in the waiting room. The key m is back on the hook — free for the producer. The CPU meter reads 0%.

Step 5 — The producer works and rings the doorbell

WHAT.

{
    std::lock_guard<std::mutex> lk(m);  // grab the free key
    q.push(0);                          // put a number in the box
}                                       // release key HERE (scope ends)
cv.notify_one();                        // ring the doorbell

WHY the producer may use lock_guard. The producer only needs to lock, mutate, unlock once. It never sleeps, so it never needs unlock/relock — the simpler std::lock_guard is correct here.

WHY release the key before notifying? If we ring the bell while still holding the key, the woken consumer instantly tries to grab the key, finds it taken, and blocks again — a pointless bounce. Releasing first means the consumer wakes to an available key. (This is an optimization; notifying under the lock is also correct.)

PICTURE. Producer holds the key, drops 0 into the box, hangs the key back, then presses the amber doorbell. A wake-signal travels to the waiting room.

Step 6 — The consumer wakes, re-checks, and only then works

WHAT. The doorbell wakes the sleeper. wait now re-locks the key and re-evaluates P(): $P()=\text{!q.empty()}||\text{done}=\text{true}(\text{box has }0)$ So wait returns, the consumer holds the key, and drains the box.

WHY re-check at all — didn't the bell mean "go"? No. Two things can lie to you:

1. A spurious wakeup — the OS may wake a sleeper with nobody having rung the bell. See Spurious Wakeup.
2. A stolen wakeup — with several consumers, another one may grab the single item first, leaving this one with an empty box.

The predicate loop is the safety net. Formally the predicate overload is a loop: $\text{cv.wait(lk, P)}\equiv \text{while(!P()) cv.wait(lk);}$ Term by term: while P() is still false, go back to sleep; only escape when P() is genuinely true. This is why we never use if here.

PICTURE. Consumer awake, key in hand, P() now green/true, pulling 0 out of the box.

Step 7 — The edge cases you must not skip

Real code hits corners. Here are all of them, each with its own frame.

Case A — Spurious wakeup (nobody rang the bell). The consumer wakes on its own. It re-locks, evaluates P() = false (box still empty), and the while sends it straight back to sleep. No harm done — because we looped.

Case B — Notify with no one waiting (the lost notify). A condition_variable has no memory. If the producer rings the bell while the consumer is not yet in the waiting room, that ring vanishes into the void. This is fine only because the number is already sitting in the box — when the consumer finally checks P(), the box (the shared flag) tells the truth. Lesson: correctness lives in the shared state, never in the ring.

Case C — Shutdown (done = true, notify_all). When the producer finishes:

{ std::lock_guard<std::mutex> lk(m); done = true; }
cv.notify_all();   // wake EVERY sleeper so they can exit

notify_all wakes all consumers; each sees P() true via done, drains anything left, and exits. Using notify_one here could leave other consumers asleep forever — a Deadlock-like hang.

The one-picture summary

This single frame compresses Steps 2–7: the key passing between producer and consumer, the sleep-with-key-released move, the doorbell, and the re-check loop.

🇮🇳 Yeh note Hinglish mein padho → · See also Producer-Consumer Pattern, std::future and std::promise, std::atomic.