32 Thread support library [thread]

32.3 Stop tokens [thread.stoptoken]

32.3.3 Class stop_­token [stoptoken]

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;
    [[nodiscard]] friend bool operator!=(const stop_token& lhs, const stop_token& rhs) noexcept;
    friend void swap(stop_token& lhs, stop_token& rhs) noexcept;
  };
}

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

stop_token() noexcept;
Postconditions: stop_­possible() is false and stop_­requested() is false.
Note
:
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
:
*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.

32.3.3.2 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.

32.3.3.3 Comparisons [stoptoken.cmp]

[[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.
[[nodiscard]] bool operator!=(const stop_token& lhs, const stop_token& rhs) noexcept;
Returns: !(lhs==rhs).

32.3.3.4 Specialized algorithms [stoptoken.special]

friend void swap(stop_token& x, stop_token& y) noexcept;
Effects: Equivalent to: x.swap(y).