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

constexpr 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> state) noexcept

Private Members

hpx::intrusive_ptr<detail::stop_state> state_

Friends

friend class stop_callback

friend class stop_source

inline friend constexpr friend bool operator== (stop_token const &lhs, stop_token const &rhs) noexcept

inline friend constexpr 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 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, never_stop_token) noexcept

inline friend constexpr friend bool operator!= (never_stop_token, never_stop_token) noexcept

struct callback_impl

Public Functions

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