futures::stop_source

Futures / Cancellation / stop_source

^{Defined in header <futures/stop_token.hpp>}

class stop_source;

Object used to issue a stop request.

Description

The stop_source class provides the means to issue a stop request, such as for std::jthread cancellation. A stop request made for one stop_source object is visible to all stop_sources and std::stop_tokens of the same associated stop-state; any std::stop_callback(s) registered for associated std::stop_token(s) will be invoked, and any std::condition_variable_any objects waiting on associated std::stop_token(s) will be awoken.

Public Functions

Constructors	Description
(constructor)	Constructs a stop_source with new stop-state. ^(function)
(destructor) = default	Destroys the stop_source object. ^(function)
operator=	Copy-assigns the stop-state of other. ^(function)

Modifiers	Description
request_stop	Makes a stop request for the associated stop-state, if any. ^(function)
swap	Swaps two stop_source objects. ^(function)

Non-member functions	Description
get_token const	Returns a stop_token for the associated stop-state. ^(function)
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
operator==	Returns a stop_token for the associated stop-state. ^{(public friend bool)}
operator!=	Returns a stop_token for the associated stop-state. ^{(public friend bool)}

Public Functions

function stop_source

^{Defined in header <futures/stop_token.hpp>}

(1)

stop_source();

(2)

explicit stop_source(nostopstate_t) noexcept;

(3)

stop_source(stop_source const & other) = default;

(4)

stop_source(stop_source && other) noexcept;

Constructs a stop_source with new stop-state.
Constructs an empty stop_source with no associated stop-state.
Copy constructor.
Move constructor.

Parameters

other - another stop_source object to construct this stop_source object with

Description

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

(4) Constructs a stop_source 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
(4) stop_possible() is true and stop_requested() is false

Exception Safety

(1) Basic exception guarantee.
(2) Throws nothing.
(3) Basic exception guarantee.
(4) Throws nothing.

function ~stop_source

^{Defined in header <futures/stop_token.hpp>}

~stop_source() = default;

Destroys the stop_source object.

Description

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_source &
operator=(stop_source && other) noexcept;

(2)

stop_source &
operator=(stop_source const & other) noexcept;

Copy-assigns the stop-state of other.
Move-assigns the stop-state of other.

Parameters

other - another stop_source object acquire the stop-state from

Description

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

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

Post-Conditions

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

Exception Safety

Throws nothing.

function request_stop

^{Defined in header <futures/stop_token.hpp>}

bool
request_stop() noexcept;

Makes a stop request for the associated stop-state, if any.

Return value

true if the stop_source object has a stop-state and this invocation made a stop request (the underlying atomic value was successfully changed), otherwise false

Description

Issues a stop request to the stop-state, if the stop_source object has a stop-state, and it has not yet already had stop requested.

The determination is made atomically, and if stop was requested, the stop-state is atomically updated to avoid race conditions, such that:

stop_requested() and stop_possible() can be concurrently invoked on other stop_tokens and stop_sources of the same stop-state
request_stop() can be concurrently invoked on other stop_source objects, and only one will actually perform the stop request.

Exception Safety

Throws nothing.

function swap

^{Defined in header <futures/stop_token.hpp>}

void
swap(stop_source & other) noexcept;

Swaps two stop_source objects.

Parameters

other - stop_source to exchange the contents with

Exception Safety

Throws nothing.

function get_token

^{Defined in header <futures/stop_token.hpp>}

stop_token
get_token() const noexcept;

Returns a stop_token for the associated stop-state.

Return value

A stop_token object, which will be empty if this->stop_possible() == false

Description

Returns a stop_token object associated with the stop_source's stop-state, if the stop_source has stop-state, otherwise returns a default-constructed (empty) stop_token.

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 a stop-state, and it has received a stop request, false otherwise

Description

Checks if the stop_source object has a stop-state and that state has received a stop request.

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

true if the stop_source object has a stop-state, otherwise false

Description

Checks if the stop_source object has a stop-state.

Notes

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

Exception Safety

Throws nothing.

Friends

friend operator==

^{Defined in header <futures/stop_token.hpp>}

friend
bool operator==(stop_source const & a, stop_source const & b);

Returns a stop_token for the associated stop-state.

Return: A stop_token object, which will be empty if this->stop_possible() == false

Description

Returns a stop_token object associated with the stop_source's stop-state, if the stop_source has stop-state, otherwise returns a default-constructed (empty) stop_token.

friend operator!=

^{Defined in header <futures/stop_token.hpp>}

friend
bool operator!=(stop_source const & a, stop_source const & b);

Returns a stop_token for the associated stop-state.

Return: A stop_token object, which will be empty if this->stop_possible() == false

Description

Returns a stop_token object associated with the stop_source's stop-state, if the stop_source has stop-state, otherwise returns a default-constructed (empty) stop_token.

_{Updated on 2023-01-04}