33 Concurrency support library [thread]

33.3 Stop tokens [thread.stoptoken]

33.3.1 Introduction [thread.stoptoken.intro]

Subclause [thread.stoptoken] describes components that can be used to asynchronously request that an operation stops execution in a timely manner, typically because the result is no longer required.
Such a request is called a stop request.
stop_source, stop_token, and stop_callback implement semantics of shared ownership of a stop state.
Any stop_source, stop_token, or stop_callback that shares ownership of the same stop state is an associated stop_source, stop_token, or stop_callback, respectively.
The last remaining owner of the stop state automatically releases the resources associated with the stop state.
A stop_token can be passed to an operation which can either
  • actively poll the token to check if there has been a stop request, or
  • register a callback using the stop_callback class template which will be called in the event that a stop request is made.
A stop request made via a stop_source will be visible to all associated stop_token and stop_source objects.
Once a stop request has been made it cannot be withdrawn (a subsequent stop request has no effect).
Callbacks registered via a stop_callback object are called when a stop request is first made by any associated stop_source object.
Calls to the functions request_stop, stop_requested, and stop_possible do not introduce data races.
A call to request_stop that returns true synchronizes with a call to stop_requested on an associated stop_token or stop_source object that returns true.
Registration of a callback synchronizes with the invocation of that callback.

33.3.2 Header <stop_token> synopsis [thread.stoptoken.syn]

namespace std { // [stoptoken], class stop_token class stop_token; // [stopsource], class stop_source class stop_source; // no-shared-stop-state indicator struct nostopstate_t { explicit nostopstate_t() = default; }; inline constexpr nostopstate_t nostopstate{}; // [stopcallback], class template stop_callback template<class Callback> class stop_callback; }

33.3.3 Class stop_token [stoptoken]

33.3.3.1 General [stoptoken.general]

The class stop_token provides an interface for querying whether a stop request has been made (stop_requested) or can ever be made (stop_possible) using an associated stop_source object ([stopsource]).
A stop_token can also be passed to a stop_callback ([stopcallback]) constructor to register a callback to be called when a stop request has been made from an associated stop_source.
namespace std { class stop_token { public: // [stoptoken.cons], constructors, copy, and assignment stop_token() noexcept; stop_token(const stop_token&) noexcept; stop_token(stop_token&&) noexcept; stop_token& operator=(const stop_token&) noexcept; stop_token& operator=(stop_token&&) noexcept; ~stop_token(); void swap(stop_token&) noexcept; // [stoptoken.mem], stop handling [[nodiscard]] bool stop_requested() const noexcept; [[nodiscard]] bool stop_possible() const noexcept; [[nodiscard]] friend bool operator==(const stop_token& lhs, const stop_token& rhs) noexcept; friend void swap(stop_token& lhs, stop_token& rhs) noexcept; }; }

33.3.3.2 Constructors, copy, and assignment [stoptoken.cons]

stop_token() noexcept;
Postconditions: stop_possible() is false and stop_requested() is false.
[Note 1: 
Because the created stop_token object can never receive a stop request, no resources are allocated for a stop state.
— end note]
stop_token(const stop_token& rhs) noexcept;
Postconditions: *this == rhs is true.
[Note 2: 
*this and rhs share the ownership of the same stop state, if any.
— end note]
stop_token(stop_token&& rhs) noexcept;
Postconditions: *this contains the value of rhs prior to the start of construction and rhs.stop_possible() is false.
~stop_token();
Effects: Releases ownership of the stop state, if any.
stop_token& operator=(const stop_token& rhs) noexcept;
Effects: Equivalent to: stop_token(rhs).swap(*this).
Returns: *this.
stop_token& operator=(stop_token&& rhs) noexcept;
Effects: Equivalent to: stop_token(std​::​move(rhs)).swap(*this).
Returns: *this.
void swap(stop_token& rhs) noexcept;
Effects: Exchanges the values of *this and rhs.

33.3.3.3 Members [stoptoken.mem]

[[nodiscard]] bool stop_requested() const noexcept;
Returns: true if *this has ownership of a stop state that has received a stop request; otherwise, false.
[[nodiscard]] bool stop_possible() const noexcept;
Returns: false if:
  • *this does not have ownership of a stop state, or
  • a stop request was not made and there are no associated stop_source objects;
otherwise, true.

33.3.3.4 Non-member functions [stoptoken.nonmembers]

[[nodiscard]] bool operator==(const stop_token& lhs, const stop_token& rhs) noexcept;
Returns: true if lhs and rhs have ownership of the same stop state or if both lhs and rhs do not have ownership of a stop state; otherwise false.
friend void swap(stop_token& x, stop_token& y) noexcept;
Effects: Equivalent to: x.swap(y).

33.3.4 Class stop_source [stopsource]

33.3.4.1 General [stopsource.general]

The class stop_source implements the semantics of making a stop request.
A stop request made on a stop_source object is visible to all associated stop_source and stop_token ([stoptoken]) objects.
Once a stop request has been made it cannot be withdrawn (a subsequent stop request has no effect).
namespace std { // no-shared-stop-state indicator struct nostopstate_t { explicit nostopstate_t() = default; }; inline constexpr nostopstate_t nostopstate{}; class stop_source { public: // [stopsource.cons], constructors, copy, and assignment stop_source(); explicit stop_source(nostopstate_t) noexcept; stop_source(const stop_source&) noexcept; stop_source(stop_source&&) noexcept; stop_source& operator=(const stop_source&) noexcept; stop_source& operator=(stop_source&&) noexcept; ~stop_source(); void swap(stop_source&) noexcept; // [stopsource.mem], stop handling [[nodiscard]] stop_token get_token() const noexcept; [[nodiscard]] bool stop_possible() const noexcept; [[nodiscard]] bool stop_requested() const noexcept; bool request_stop() noexcept; [[nodiscard]] friend bool operator==(const stop_source& lhs, const stop_source& rhs) noexcept; friend void swap(stop_source& lhs, stop_source& rhs) noexcept; }; }

33.3.4.2 Constructors, copy, and assignment [stopsource.cons]

stop_source();
Effects: Initialises *this to have ownership of a new stop state.
Postconditions: stop_possible() is true and stop_requested() is false.
Throws: bad_alloc if memory cannot be allocated for the stop state.
explicit stop_source(nostopstate_t) noexcept;
Postconditions: stop_possible() is false and stop_requested() is false.
[Note 1: 
No resources are allocated for the state.
— end note]
stop_source(const stop_source& rhs) noexcept;
Postconditions: *this == rhs is true.
[Note 2: 
*this and rhs share the ownership of the same stop state, if any.
— end note]
stop_source(stop_source&& rhs) noexcept;
Postconditions: *this contains the value of rhs prior to the start of construction and rhs.stop_possible() is false.
~stop_source();
Effects: Releases ownership of the stop state, if any.
stop_source& operator=(const stop_source& rhs) noexcept;
Effects: Equivalent to: stop_source(rhs).swap(*this).
Returns: *this.
stop_source& operator=(stop_source&& rhs) noexcept;
Effects: Equivalent to: stop_source(std​::​move(rhs)).swap(*this).
Returns: *this.
void swap(stop_source& rhs) noexcept;
Effects: Exchanges the values of *this and rhs.

33.3.4.3 Members [stopsource.mem]

[[nodiscard]] stop_token get_token() const noexcept;
Returns: stop_token() if stop_possible() is false; otherwise a new associated stop_token object.
[[nodiscard]] bool stop_possible() const noexcept;
Returns: true if *this has ownership of a stop state; otherwise, false.
[[nodiscard]] bool stop_requested() const noexcept;
Returns: true if *this has ownership of a stop state that has received a stop request; otherwise, false.
bool request_stop() noexcept;
Effects: If *this does not have ownership of a stop state, returns false.
Otherwise, atomically determines whether the owned stop state has received a stop request, and if not, makes a stop request.
The determination and making of the stop request are an atomic read-modify-write operation ([intro.races]).
If the request was made, the callbacks registered by associated stop_callback objects are synchronously called.
If an invocation of a callback exits via an exception then terminate is invoked ([except.terminate]).
[Note 1: 
A stop request includes notifying all condition variables of type condition_variable_any temporarily registered during an interruptible wait ([thread.condvarany.intwait]).
— end note]
Postconditions: stop_possible() is false or stop_requested() is true.
Returns: true if this call made a stop request; otherwise false.

33.3.4.4 Non-member functions [stopsource.nonmembers]

[[nodiscard]] friend bool operator==(const stop_source& lhs, const stop_source& rhs) noexcept;
Returns: true if lhs and rhs have ownership of the same stop state or if both lhs and rhs do not have ownership of a stop state; otherwise false.
friend void swap(stop_source& x, stop_source& y) noexcept;
Effects: Equivalent to: x.swap(y).

33.3.5 Class template stop_callback [stopcallback]

33.3.5.1 General [stopcallback.general]

namespace std { template<class Callback> class stop_callback { public: using callback_type = Callback; // [stopcallback.cons], constructors and destructor template<class C> explicit stop_callback(const stop_token& st, C&& cb) noexcept(is_nothrow_constructible_v<Callback, C>); template<class C> explicit stop_callback(stop_token&& st, C&& cb) noexcept(is_nothrow_constructible_v<Callback, C>); ~stop_callback(); stop_callback(const stop_callback&) = delete; stop_callback(stop_callback&&) = delete; stop_callback& operator=(const stop_callback&) = delete; stop_callback& operator=(stop_callback&&) = delete; private: Callback callback; // exposition only }; template<class Callback> stop_callback(stop_token, Callback) -> stop_callback<Callback>; }
Mandates: stop_callback is instantiated with an argument for the template parameter Callback that satisfies both invocable and destructible.
Preconditions: stop_callback is instantiated with an argument for the template parameter Callback that models both invocable and destructible.

33.3.5.2 Constructors and destructor [stopcallback.cons]

template<class C> explicit stop_callback(const stop_token& st, C&& cb) noexcept(is_nothrow_constructible_v<Callback, C>); template<class C> explicit stop_callback(stop_token&& st, C&& cb) noexcept(is_nothrow_constructible_v<Callback, C>);
Constraints: Callback and C satisfy constructible_from<Callback, C>.
Preconditions: Callback and C model constructible_from<Callback, C>.
Effects: Initializes callback with std​::​forward<C>(cb).
If st.stop_requested() is true, then std​::​forward<Callback>(callback)() is evaluated in the current thread before the constructor returns.
Otherwise, if st has ownership of a stop state, acquires shared ownership of that stop state and registers the callback with that stop state such that std​::​forward<Callback>(callback)() is evaluated by the first call to request_stop() on an associated stop_source.
Throws: Any exception thrown by the initialization of callback.
Remarks: If evaluating std​::​forward<Callback>(callback)() exits via an exception, then terminate is invoked ([except.terminate]).
~stop_callback();
Effects: Unregisters the callback from the owned stop state, if any.
The destructor does not block waiting for the execution of another callback registered by an associated stop_callback.
If callback is concurrently executing on another thread, then the return from the invocation of callback strongly happens before ([intro.races]) callback is destroyed.
If callback is executing on the current thread, then the destructor does not block ([defns.block]) waiting for the return from the invocation of callback.
Releases ownership of the stop state, if any.