C++ Reference ยท Concurrency
C++ std::stop_token and std::stop_source
Reference for std::stop_token, stop_source and stop_callback (C++20): ask a thread to stop cooperatively, check stop_requested and register cancellation callbacks.
C++20 adds a small, thread-safe cancellation mechanism to <stop_token>. It has three parts. A std::stop_source owns a shared "stop state" and can request a stop with request_stop(). A std::stop_token is a cheap, copyable read-only view of that state; code checks stop_requested() and ends its work when it becomes true. A std::stop_callback registers a function that runs when a stop is requested.
Cancellation here is cooperative: nothing is interrupted. The worker has to look at the token regularly. std::jthread wires this up for you: it owns a stop_source and passes a stop_token to the thread function.
std::stop_source src; std::stop_token tok = src.get_token(); src.request_stop(); bool stop = tok.stop_requested(); // true
Try it
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.
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.
Syntax
class stop_source { public: stop_source(); // creates a new stop state explicit stop_source(std::nostopstate_t) noexcept; stop_token get_token() const noexcept; bool request_stop() noexcept; // true if this call made the request bool stop_requested() const noexcept; bool stop_possible() const noexcept; }; class stop_token { public: bool stop_requested() const noexcept; bool stop_possible() const noexcept; }; template<class Callback> class stop_callback { public: template<class C> explicit stop_callback(const stop_token& st, C&& cb); template<class C> explicit stop_callback(stop_token&& st, C&& cb); };
| Name | Description |
|---|---|
get_token() |
Returns a token that observes this source's state. |
request_stop() |
Sets the stop flag and runs registered callbacks. Returns true only for the call that actually changed the state. |
stop_requested() |
true once a stop has been requested. |
stop_possible() |
false for a default token or when no source can still request a stop. |
stop_callback |
Registers the callable in the constructor; deregisters in the destructor. |
Returns: the bool functions as described. Errors: none are thrown by the stop operations. If a callback throws, std::terminate is called.
Usage notes
- Cooperative only. A thread that never checks its token is never stopped. Check at loop boundaries and before blocking steps.
- Thread safe. All three classes may be used from several threads without extra locking.
- Callbacks run in the thread that calls
request_stop(), or immediately in the constructor if a stop was already requested. Keep them short and non-throwing. - Destroying a
stop_callbackwaits if its callback is currently running in another thread, unless it is destroyed from within the callback itself. - Interruptible waiting:
std::condition_variable_any::wait(lock, stop_token, pred)returns when a stop is requested, so a worker blocked on a queue can be shut down cleanly. - A request is permanent. There is no way to reset a stop state; create a new
stop_source. - Copies share state. Copying a token or a source refers to the same stop state.
- Available since C++20 (libstdc++ 10 and newer for
<stop_token>).