skip to content

A C++20 transcoder worker is blocked in read() and cannot poll its std::stop_token; how does std::stop_callback let a cancel request unblock it?

level: seniorimportance: should knowfreq 30%

answer

  1. polling fails while blocked
  2. register code with the stop state
  3. runs on the requesting thread
  4. already stopped means run now
  5. destructor waits for a running callback

basics

~20 s

A std::stop_callback on the worker's token runs its callable on the first request_stop(), synchronously on the requesting thread, or at once in its constructor if a stop was already requested. The callable unblocks the read, for example by closing the pipe's write end.

solid answer

~40 s

A worker blocked in `read()` cannot check `stop_requested()`. So inside the worker, before blocking, construct `std::stop_callback cb(st, [fd] { close(fd); });`. On the first `request_stop()` on an associated `std::stop_source` or `std::jthread`, every registered callback runs **synchronously on the thread that requested the stop**, here the UI thread. If a stop was already requested when the callback is constructed, it runs immediately in the constructor, on the worker, so there is no lost-wakeup window. The callable must unblock the operation without throwing, since an exception escaping it calls `std::terminate`, and it should be short because it runs on the canceller's thread. `~stop_callback` deregisters, and blocks if the callback is mid-run on another thread, so its captures stay alive. Scope it inside the worker, around the blocking call.

code

cpp · 23 lines
cpp
#include <iostream>
#include <stop_token>
#include <thread>
#include <unistd.h>   // POSIX pipe, read, close

int main() {
    int fds[2];
    if (pipe(fds) != 0) return 1;

    std::jthread reader([rd = fds[0], wr = fds[1]](std::stop_token st) {
        // read() blocks, so the worker cannot poll st; register a callback
        // that unblocks it by closing the write end (read then sees EOF).
        std::stop_callback on_stop(st, [wr] { close(wr); });
        char buf[256];
        ssize_t n = read(rd, buf, sizeof buf);   // blocks until data or EOF
        std::cout << "read returned " << n << ", stop_requested="
                  << st.stop_requested() << '\n';
        close(rd);
    });

    std::cout << "main: user pressed Cancel\n";
    reader.request_stop();   // runs on_stop's callback here, on this thread
}

go deeper

for a junior

Know that a stop token can only be checked, so a thread stuck in a blocking call needs something else to wake it.

for a middle

Explain how std::stop_callback registers code with the stop state and runs it when the stop is requested.

for a senior

Reason about the race between registration and cancellation, which thread runs the callable, and why the callback object is scoped around the blocking call.

for a principal

Choose a cancellation contract for blocking dependencies: callbacks that unblock, timeouts, or wrapping libraries that cannot be cancelled at all.

## Why polling is not enough The cooperative model of C++20 stop tokens works well for loops: check `st.stop_requested()` between chunks of work. It fails as soon as the worker blocks. A transcoder thread waiting in a POSIX `read()` on a pipe, a socket receive, or a long library call cannot check anything until the call returns, and it may never return on its own. Something on **another thread** has to make the blocking call return, and it has to happen at the moment the stop is requested. ## What std::stop_callback does `std::stop_callback<F>` (C++20, `<stop_token>`) registers a callable with the stop state behind a `std::stop_token`: - **Registration in the constructor.** If no stop has been requested yet, the callable is added to the stop state's list. If a stop **has** already been requested, the callable is evaluated immediately, in the constructor, on the constructing thread. - **Invocation on request.** The first `request_stop()` atomically marks the state as stopped and then synchronously runs every registered callback, on the thread that called `request_stop()`. The order among several callbacks is unspecified. - **Deregistration in the destructor.** `~stop_callback` removes the callable. If the callable is executing concurrently on another thread, the destructor **blocks** until it returns; if it is executing on the current thread, it does not block. - **Exceptions.** If the callable exits via an exception, `std::terminate` is called. - **Not copyable or movable.** The object's address is registered, so it stays where it was built; CTAD lets you write `std::stop_callback cb(st, lambda);`. ## Why there is no lost wakeup The race to fear is: the worker checks the token, finds no stop, then the user cancels, then the worker blocks forever. With a callback the order no longer matters. If the cancel comes before registration, the constructor runs the callable at once and the `read()` returns end-of-file immediately. If it comes after, `request_stop()` runs the callable and the blocked `read()` returns. Registration also **synchronizes with** the invocation, so state captured at construction is visible to the callable. ## Writing the callable 1. **Make it unblock, not clean up.** Close the write end of a pipe, shut down a socket, set a flag and notify, or call the library's own cancel function. Leave the real cleanup to the worker. 2. **Keep it short and non-throwing.** It runs on the canceller's thread, often the UI thread, and an escaping exception terminates the process. 3. **Capture what outlives the callback object.** Because the destructor waits for a running callback, captured locals of the worker are safe as long as the `stop_callback` is declared after them in the same scope. 4. **Expect it to run at most once.** Callbacks run on the first stop request only; a stop cannot be withdrawn and requested again. ## Which requests trigger it Any `request_stop()` on a source associated with the token triggers the callbacks: the jthread's own source, a copy of it obtained with `get_stop_source()`, or a shared `std::stop_source` whose token was passed in. Only the **first** request runs them; it returns `true`, and every later call returns `false` and does nothing. That makes the callable naturally idempotent from the caller's side, and it lets tests drive cancellation deterministically: build a `std::stop_source` in the test, pass its token to the code under test, call `request_stop()` at the moment the test chooses, and assert that the blocked call returned. ## Placement in the transcoder Construct the `std::stop_callback` inside the worker, immediately before the blocking call, in the smallest scope that encloses it. When the worker leaves that scope normally, the destructor deregisters, and a later cancel no longer touches a descriptor the worker has already closed or reused. Registering it in the UI thread instead would leave it alive after the worker finished, closing whatever file descriptor now has that number. ## How it compares | Technique | Works while blocked | Runs on | |---|---|---| | Polling `stop_requested()` | no | the worker | | `std::stop_callback` | yes | the thread calling `request_stop()`, or the constructor's thread if already stopped | | `condition_variable_any::wait` with a token | yes, for that wait | the worker, after it wakes | The interruptible condition-variable wait is the right tool when the worker waits for a condition; the callback is the general escape hatch for every other blocking call.

  • Which thread runs a std::stop_callback's callable?
    If the stop is requested after registration, the thread that calls `request_stop()` runs it, synchronously, before `request_stop()` returns. If the stop was already requested when the `std::stop_callback` is constructed, the constructing thread runs it inside the constructor. It never runs on a library-owned background thread.
  • What happens when the worker's stop_callback is destroyed while the UI thread is running its callable?
    The destructor blocks until the callable returns, so the callable never sees its captures destroyed under it. If the callable is running on the destroying thread itself, the destructor does not block. This is why the callback should be declared after the locals it captures.
  • Why not register the callback from the UI thread instead of inside the worker?
    Its lifetime would no longer match the blocking call. After the worker finishes and closes its descriptor, a later cancel would still run the callable and close whatever descriptor now has that number. Constructing it inside the worker, around the blocking call, deregisters it the moment that call is over.

  • A stop_callback runs on a background thread owned by the standard library.
  • If the stop was requested before registration, the callback never runs.
  • request_stop() returns before the registered callbacks have run.
  • An exception thrown in a stop callback propagates to the request_stop() caller.
  • Polling stop_requested() is enough even when the worker blocks in read().

Assumes C++20, which added std::stop_token, std::stop_source and std::stop_callback; C++26 adds inplace_stop_token and related types alongside them.