skip to content

In C++20, how does std::condition_variable_any::wait(lock, stop_token, pred) let a std::jthread parser stop while blocked, and what does its bool mean?

level: seniorimportance: nice to knowfreq 26%

answer

  1. only the _any variant has it
  2. a stop request wakes the waiter
  3. returns pred(), not "stopped"
  4. drain, then exit

basics

~20 s

A stop request on the token wakes the blocked thread, and std::jthread's destructor makes one. The overload returns pred(): false means it stopped with nothing to do; true means the predicate holds, even if a stop was requested.

solid answer

~40 s

C++20 gave `std::condition_variable_any` three overloads taking a `std::stop_token`: `wait(lock, stoken, pred)`, `wait_until` and `wait_for`. `std::condition_variable` has none. The standard specifies `wait` as: while no stop is requested, return `true` if `pred()` holds, otherwise wait; once a stop is requested, `return pred();`. A request on the token wakes the waiter, so a parser running in a `std::jthread` exits when the jthread is destroyed, since its destructor calls `request_stop()` and then `join()`. The return value is the predicate, not a stop flag: `false` means stop requested and no work left; `true` means there is work — possibly with a stop pending — so the loop takes it, which naturally drains the queue before exiting.

code

cpp · 32 lines
cpp
#include <chrono>
#include <condition_variable>
#include <deque>
#include <iostream>
#include <mutex>
#include <stop_token>
#include <string>
#include <thread>
using namespace std::chrono_literals;

std::mutex m;
std::condition_variable_any cv;   // the stop_token overloads live only here
std::deque<std::string> packets;

int main() {
    std::jthread parser([](std::stop_token st) {
        for (;;) {
            std::unique_lock<std::mutex> lk(m);
            if (!cv.wait(lk, st, [] { return !packets.empty(); })) {
                std::cout << "stop requested, queue empty: parser exits\n";
                return;
            }
            std::string p = std::move(packets.front());
            packets.pop_front();
            lk.unlock();
            std::cout << "parsed " << p << '\n';
        }
    });
    { std::lock_guard<std::mutex> g(m); packets.push_back("packet 0"); }
    cv.notify_one();
    std::this_thread::sleep_for(100ms);
}   // ~jthread: request_stop() wakes the wait, then join()

go deeper

for a junior

Know that std::jthread can ask its thread to stop and that std::condition_variable_any has a wait that wakes on that request.

for a middle

Write the parser loop with wait(lock, token, pred), and read the bool as the predicate's value: false means stopped with nothing to do.

for a senior

Decide drain-or-drop on shutdown from the bool, know which type has the overloads, and know what condition_variable_any may cost in a given library.

for a principal

Standardise cancellation on stop_token and jthread for worker threads instead of ad-hoc stopping flags, where the codebase's baseline is C++20.

## The shutdown problem A parser thread that pops packets from a queue spends most of its life blocked in a condition-variable wait. Shutting it down means waking it and telling it to leave. With `std::condition_variable` the classic answer is a `stopping` flag added to the predicate, set under the mutex, followed by `notify_all()`; forget the notify, or set the flag without the mutex, and the parser never wakes. C++20 made cancellation a library concept — `std::stop_source`, `std::stop_token`, `std::stop_callback`, and `std::jthread`, which owns a stop source and whose destructor requests a stop and joins — and wired it into `std::condition_variable_any`. ## The stop-token overloads `std::condition_variable_any` gained: - `template<class Lock, class Predicate> bool wait(Lock& lock, stop_token stoken, Predicate pred);` - `wait_until(lock, stoken, abs_time, pred)` and `wait_for(lock, stoken, rel_time, pred)`, which also return `bool`. The draft states their effects precisely. For `wait`, it registers the condition variable to be notified on a stop request for the duration of the call, then behaves as: ```cpp while (!stoken.stop_requested()) { if (pred()) return true; wait(lock); } return pred(); ``` So a stop request both **wakes** the waiter (the call registered itself to be notified on a stop request) and **ends the loop**. There is no overload without a predicate: a stop-aware wait must re-evaluate the condition, so the library insists on one. `std::condition_variable` has no such overloads, and calling one on it fails to compile with "no matching member function for call to 'wait'". ## Reading the bool | Stop requested? | `pred()` | Returns | What the parser should do | |---|---|---|---| | no | `true` | `true` | take the item | | yes | `true` | `true` | take the item; the next call will see the stop again | | yes | `false` | `false` | exit | The draft's note says the returned value "indicates whether the predicate evaluated to `true` regardless of whether there was a stop request". Code that treats `true` as "notified" and `false` as "stopped" is right; code that checks `stoken.stop_requested()` first and exits throws away queued packets, which may or may not be what the shutdown policy wants. With the loop in the example, the parser drains everything already queued, then sees `false` and returns. ## `std::condition_variable_any` beyond stop tokens - It accepts any **BasicLockable** lock — anything with `lock()` and `unlock()`: `std::unique_lock<std::mutex>`, a `std::shared_lock<std::shared_mutex>` for readers waiting on read-mostly data, a lock over `std::recursive_mutex`, or a user-defined lock. - The standard notes that with a lock that is not a standard mutex or `unique_lock` over one, the user is responsible for the synchronization the predicate needs. - It can cost more than `std::condition_variable`. That is an implementation matter: libc++, for example, keeps an internal `std::shared_ptr<std::mutex>` that every wait and notify locks, in addition to the caller's lock. ## The pre-C++20 alternative, for comparison 1. Add `bool stopping = false;` to the queue, guarded by the queue's mutex. 2. Wait with `[&]{ return stopping || !q.empty(); }`. 3. On shutdown, lock, set `stopping = true`, unlock, `notify_all()`. 4. After waking, decide whether to drain or exit by looking at both fields. It works with `std::condition_variable` and is still common in C++17 code. The stop-token version removes steps 1 and 3 from every queue and ties shutdown to the thread object's lifetime instead of to a hand-written `stop()` call someone may forget. ## Declaration order decides shutdown order `std::jthread`'s destructor calls `request_stop()` and then `join()`. Members of a class are destroyed in reverse order of declaration, so a class that owns the queue, its mutex, its `std::condition_variable_any` and the parser `std::jthread` must declare the jthread **last**. It is then destroyed first: it requests the stop, the parser wakes, drains and returns, and the join completes while the mutex and condition variable are still alive. Declared first, the jthread would be destroyed last, after the condition variable it is blocked on — a destructor running while a thread waits on the object, which the standard makes undefined behaviour. ## Edge cases - A token with no associated stop state (`stop_possible()` is `false`) never wakes the waiter by itself; the call then behaves like the ordinary predicate wait. - The producer must still change the queue under the mutex; the stop machinery handles cancellation, not the lost wake-up on ordinary pushes.

  • Can you pass a std::stop_token to std::condition_variable::wait?
    No. Only `std::condition_variable_any` has the stop_token overloads; on `std::condition_variable` the call does not compile. With the plain type you add a stopping flag to the predicate, set it under the mutex and call `notify_all`, or switch the queue to `std::condition_variable_any`.
  • Why do the stop_token overloads all require a predicate?
    A stop request wakes the thread, and the caller then has to know whether it woke with work to do. Returning `pred()` answers exactly that, and the loop inside the overload also absorbs spurious wake-ups. A predicate-free stop-aware wait would leave every caller to recheck both the token and the state by hand.

  • std::condition_variable has a wait overload taking a std::stop_token
  • A true result means the wait ended because a stop was requested
  • std::jthread's destructor detaches instead of requesting a stop
  • condition_variable_any costs exactly the same as condition_variable in every library
  • A stop request discards whatever the queue still holds

Assumes C++20 or later: std::jthread, std::stop_token and the stop_token wait overloads of std::condition_variable_any were added in C++20.