33 Concurrency support library [thread]

33.3 Stop tokens [thread.stoptoken]

33.3.4 Class stop_source [stopsource]

33.3.4.1 General [stopsource.general]

1
#
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();
1
#
Effects: Initialises *this to have ownership of a new stop state.
2
#
Postconditions: stop_possible() is true and stop_requested() is false.
3
#
Throws: bad_alloc if memory cannot be allocated for the stop state.
🔗
explicit stop_source(nostopstate_t) noexcept;
4
#
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;
5
#
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;
6
#
Postconditions: *this contains the value of rhs prior to the start of construction and rhs.stop_possible() is false.
🔗
~stop_source();
7
#
Effects: Releases ownership of the stop state, if any.
🔗
stop_source& operator=(const stop_source& rhs) noexcept;
8
#
Effects: Equivalent to: stop_source(rhs).swap(*this).
9
#
Returns: *this.
🔗
stop_source& operator=(stop_source&& rhs) noexcept;
10
#
Effects: Equivalent to: stop_source(std​::​move(rhs)).swap(*this).
11
#
Returns: *this.
🔗
void swap(stop_source& rhs) noexcept;
12
#
Effects: Exchanges the values of *this and rhs.

33.3.4.3 Members [stopsource.mem]

🔗
[[nodiscard]] stop_token get_token() const noexcept;
1
#
Returns: stop_token() if stop_possible() is false; otherwise a new associated stop_token object.
🔗
[[nodiscard]] bool stop_possible() const noexcept;
2
#
Returns: true if *this has ownership of a stop state; otherwise, false.
🔗
[[nodiscard]] bool stop_requested() const noexcept;
3
#
Returns: true if *this has ownership of a stop state that has received a stop request; otherwise, false.
🔗
bool request_stop() noexcept;
4
#
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]
5
#
Postconditions: stop_possible() is false or stop_requested() is true.
6
#
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;
1
#
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;
2
#
Effects: Equivalent to: x.swap(y).