Skip to content

futures::stop_token

Futures / Cancellation / stop_token

Defined in header <futures/stop_token.hpp>

class stop_token;

Token to check if a stop request has been made.

Description

The stop_token class provides the means to check if a stop request has been made or can be made, for its associated std::stop_source object. It is essentially a thread-safe "view" of the associated stop-state.

Public Functions

Constructors Description
(constructor) Constructs an empty stop_token with no associated stop-state.
(function)
(destructor) = default Destroys the stop_token object.
(function)
operator= Copy-assigns the associated stop-state of other to that of *this
(function)
Modifiers Description
swap Exchanges the associated stop-state of *this and other.
(function)
Observers Description
stop_requested const Checks whether the associated stop-state has been requested to stop.
(function)
stop_possible const Checks whether associated stop-state can be requested to stop.
(function)

Friends

Friends Description
stop_source
(private friend class)

Public Functions

function stop_token

Defined in header <futures/stop_token.hpp>

(1)
stop_token() = default;
(2)
stop_token(stop_token const & other) = default;
(3)
stop_token(stop_token && other) noexcept;
  1. Constructs an empty stop_token with no associated stop-state.
  2. Copy constructor.
  3. Move constructor.

Parameters

  • other - another stop_token object to construct this stop_token object

Description

(2) Constructs a stop_token whose associated stop-state is the same as that of other.

(3) Constructs a stop_token whose associated stop-state is the same as that of other; other is left empty

Post-Conditions

  • (1) *this and other share the same associated stop-state and compare equal
  • (2) *this has other's previously associated stop-state, and other.stop_possible() is false
  • (3) stop_possible() and stop_requested() are both false

Exception Safety

  • (1) Basic exception guarantee.
  • (2) Basic exception guarantee.

  • (3) Throws nothing.

function ~stop_token

Defined in header <futures/stop_token.hpp>

~stop_token() = default;

Destroys the stop_token object.

Post-Conditions

If *this has associated stop-state, releases ownership of it.

Exception Safety

Basic exception guarantee.

function operator=

Defined in header <futures/stop_token.hpp>

(1)
stop_token &
operator=(stop_token const & other) noexcept;
(2)
stop_token &
operator=(stop_token && other) noexcept;
  1. Copy-assigns the associated stop-state of other to that of *this
  2. Move-assigns the associated stop-state of other to that of *this

Parameters

  • other - Another stop_token object to share the stop-state with to or acquire the stop-state from

Description

(1) Equivalent to stop_token(other).swap(*this)

(2) After the assignment, *this contains the previous associated stop-state of other, and other has no associated stop-state

Equivalent to stop_token(std::move(other)).swap(*this)

Exception Safety

Throws nothing.

function swap

Defined in header <futures/stop_token.hpp>

void
swap(stop_token & other) noexcept;

Exchanges the associated stop-state of *this and other.

Parameters

  • other - stop_token to exchange the contents with

Exception Safety

Throws nothing.

function stop_requested

Defined in header <futures/stop_token.hpp>

bool
stop_requested() const noexcept;

Checks whether the associated stop-state has been requested to stop.

Return value

true if the stop_token object has associated stop-state and it received a stop request, false otherwise.

Description

Checks if the stop_token object has associated stop-state and that state has received a stop request. A default constructed stop_token has no associated stop-state, and thus has not had stop requested

Exception Safety

Throws nothing.

function stop_possible

Defined in header <futures/stop_token.hpp>

bool
stop_possible() const noexcept;

Checks whether associated stop-state can be requested to stop.

Return value

false if the stop_token object has no associated stop-state, or it did not yet receive a stop request and there are no associated std::stop_source object(s); true otherwise

Description

Checks if the stop_token object has associated stop-state, and that state either has already had a stop requested or it has associated std::stop_source object(s).

A default constructed stop_token has no associated stop-state, and thus cannot be stopped. the associated stop-state for which no std::stop_source object(s) exist can also not be stopped if such a request has not already been made.

Notes

If the stop_token object has associated stop-state and a stop request has already been made, this function still returns true.

Exception Safety

Throws nothing.

Friends

friend stop_source

Defined in header <futures/stop_token.hpp>

friend
class stop_source(stop_source);


Updated on 2023-01-04