hpx/synchronization/stop_token.hpp#

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

Functions

template<typename Callback>
stop_callback(stop_token, Callback) -> stop_callback<Callback>#

The stop_callback class template provides an RAII object type that registers a callback function for an associated hpx::stop_token object, such that the callback function will be invoked when the hpx::stop_token’s associated hpx::stop_source is requested to stop. Callback functions registered via stop_callback’s constructor are invoked either in the same thread that successfully invokes request_stop() for a hpx::stop_source of the stop_callback’s associated hpx::stop_token; or if stop has already been requested prior to the constructor’s registration, then the callback is invoked in the thread constructing the stop_callback. More than one stop_callback can be created for the same hpx::stop_token, from the same or different threads concurrently. No guarantee is provided for the order in which they will be executed, but they will be invoked synchronously; except for stop_callback(s) constructed after stop has already been requested for the hpx::stop_token, as described previously. If an invocation of a callback exits via an exception then hpx::terminate is called. hpx::stop_callback is not CopyConstructible, CopyAssignable, MoveConstructible, nor MoveAssignable. The template param Callback type must be both invocable and destructible. Any return value is ignored.

inline void swap(stop_token &lhs, stop_token &rhs) noexcept#
inline void swap(stop_source &lhs, stop_source &rhs) noexcept#

Variables

constexpr nostopstate_t nostopstate = {}#

This is a constant object instance of hpx::nostopstate_t for use in constructing an empty hpx::stop_source, as a placeholder value in the non-default constructor.

struct nostopstate_t#
#include <stop_token.hpp>

Unit type intended for use as a placeholder in hpx::stop_source non-default constructor, that makes the constructed hpx::stop_source empty with no associated stop-state.

Public Functions

explicit nostopstate_t() = default#
template<typename Callback>
class stop_callback
class stop_source#
#include <stop_token.hpp>

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

Note

For the purposes of hpx::jthread cancellation the stop_source object should be retrieved from the hpx::jthread object using get_stop_source(); or stop should be requested directly from the hpx::jthread object using request_stop(). This will then use the same associated stop-state as that passed into the hpx::jthread’s invoked function argument (i.e., the function being executed on its thread). For other uses, however, a stop_source can be constructed separately using the default constructor, which creates new stop-state.

Public Functions

inline stop_source()#
inline explicit stop_source(nostopstate_t) noexcept#
inline stop_source(stop_source const &rhs) noexcept#
stop_source(stop_source&&) noexcept = default#
inline stop_source &operator=(stop_source const &rhs) noexcept#
stop_source &operator=(stop_source&&) noexcept = default#
inline ~stop_source()#
inline void swap(stop_source &s) noexcept#

swaps two stop_source objects

inline stop_token get_token() const noexcept#

returns a stop_token for the associated stop-state

inline bool stop_possible() const noexcept#

checks whether associated stop-state can be requested to stop

inline bool stop_requested() const noexcept#

checks whether the associated stop-state has been requested to stop

inline bool request_stop() noexcept#

makes a stop request for the associated stop-state, if any

Private Members

hpx::intrusive_ptr<detail::stop_state> state_#

Friends

inline friend bool operator==(stop_source const &lhs, stop_source const &rhs) noexcept#
inline friend bool operator!=(stop_source const &lhs, stop_source const &rhs) noexcept#
class stop_token#
#include <stop_token.hpp>

The stop_token class provides the means to check if a stop request has been made or can be made, for its associated hpx::stop_source object. It is essentially a thread-safe “view” of the associated stop-state. The stop_token can also be passed to the constructor of hpx::stop_callback, such that the callback will be invoked if the stop_token’s associated hpx::stop_source is requested to stop. And stop_token can be passed to the interruptible waiting functions of hpx::condition_variable_any, to interrupt the condition variable’s wait if stop is requested.

Note

A stop_token object is not generally constructed independently, but rather retrieved from a hpx::jthread or hpx::stop_source. This makes it share the same associated stop-state as the hpx::jthread or hpx::stop_source.

Public Types

template<typename Callback>
using callback_type = stop_callback<Callback>#

Public Functions

stop_token() noexcept = default#
inline stop_token(stop_token const &rhs) noexcept#
stop_token(stop_token&&) noexcept = default#
inline stop_token &operator=(stop_token const &rhs) noexcept#
stop_token &operator=(stop_token&&) noexcept = default#
~stop_token() = default#
inline void swap(stop_token &s) noexcept#

swaps two stop_token objects

inline bool stop_requested() const noexcept#

checks whether the associated stop-state has been requested to stop

inline bool stop_possible() const noexcept#

checks whether associated stop-state can be requested to stop

Private Functions

inline explicit stop_token(hpx::intrusive_ptr<detail::stop_state> const &state) noexcept#

Private Members

hpx::intrusive_ptr<detail::stop_state> state_#

Friends

friend class stop_callback
friend class stop_source
inline friend bool operator==(stop_token const &lhs, stop_token const &rhs) noexcept#
inline friend bool operator!=(stop_token const &lhs, stop_token const &rhs) noexcept#
namespace experimental
namespace p2300_stop_token#

Functions

template<typename Callback>
in_place_stop_callback(in_place_stop_token, Callback) -> in_place_stop_callback<Callback>#
template<typename Callback>
class in_place_stop_callback
class in_place_stop_source#

Public Functions

inline in_place_stop_source() noexcept#
inline ~in_place_stop_source()#
in_place_stop_source(in_place_stop_source const&) = delete#
in_place_stop_source(in_place_stop_source&&) noexcept = delete#
in_place_stop_source &operator=(in_place_stop_source const&) = delete#
in_place_stop_source &operator=(in_place_stop_source&&) noexcept = delete#
inline in_place_stop_token get_token() const noexcept#
inline bool request_stop() noexcept#
inline bool stop_requested() const noexcept#
inline bool stop_possible() const noexcept#

Private Functions

inline bool register_callback(hpx::detail::stop_callback_base *cb) noexcept#
inline void remove_callback(hpx::detail::stop_callback_base *cb) noexcept#

Private Members

hpx::detail::stop_state state_#

Friends

friend class in_place_stop_token
friend class in_place_stop_callback
class in_place_stop_token#

Public Types

template<typename Callback>
using callback_type = in_place_stop_callback<Callback>#

Public Functions

inline constexpr in_place_stop_token() noexcept#
in_place_stop_token(in_place_stop_token const &rhs) noexcept = default#
inline in_place_stop_token(in_place_stop_token &&rhs) noexcept#
in_place_stop_token &operator=(in_place_stop_token const &rhs) noexcept = default#
inline in_place_stop_token &operator=(in_place_stop_token &&rhs) noexcept#
inline bool stop_requested() const noexcept#
inline bool stop_possible() const noexcept#
inline void swap(in_place_stop_token &rhs) noexcept#

Private Functions

inline explicit in_place_stop_token(in_place_stop_source const *source) noexcept#

Private Members

in_place_stop_source const *source_#

Friends

friend class in_place_stop_source
friend class in_place_stop_callback
inline friend constexpr friend bool operator== (in_place_stop_token const &lhs, in_place_stop_token const &rhs) noexcept
inline friend void swap(in_place_stop_token &x, in_place_stop_token &y) noexcept#
struct never_stop_token#

Public Types

template<typename>
using callback_type = callback_impl#

Public Static Functions

static inline constexpr bool stop_requested() noexcept#
static inline constexpr bool stop_possible() noexcept#

Friends

inline friend constexpr friend bool operator== (never_stop_token const &, never_stop_token const &) noexcept
struct callback_impl#

Public Functions

template<typename Callback>
inline explicit constexpr callback_impl(never_stop_token, Callback&&) noexcept#