Skip to content
Tutorials Center
My learning

Topics

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.

C++
std::stop_source src;
std::stop_token tok = src.get_token();
src.request_stop();
bool stop = tok.stop_requested();   // true

Try it

C++ Stopping a worker with a token

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.

C++ stop_callback and jthread

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

C++
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_callback waits 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>).