hpx/supervision_dispatch/server/registry.hpp#

Defined in header hpx/supervision_dispatch/server/registry.hpp.

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

namespace hpx
namespace supervision#

Fenced action dispatch for the supervision subsystem.

This header provides the machinery to dispatch an HPX action to a target component while enforcing supervision “fencing” semantics: once a target has latched a terminal event for a given epoch, no further actions for that epoch may execute against it. Dispatch performs a cheap, non-authoritative admission check on the caller’s locality and an authoritative re-check on the target’s own locality (via hpx::colocated), immediately before invoking the wrapped action, closing the race between admission and invocation.

Types and functions implementing HPX’s supervision and fenced dispatch facilities.

Functions

inline bool operator==(joined_peer const &lhs, joined_peer const &rhs) noexcept#
inline bool operator!=(joined_peer const &lhs, joined_peer const &rhs) noexcept#
std::ostream &operator<<(std::ostream &strm, joined_peer const &peer)#
struct joined_peer#
#include <registry.hpp>

Pairs the two values a caller obtains from a successful registry::join() and needs to perform a fenced dispatch.

See also

dispatch_work()

See also

server::registry::join()

Public Members

hpx::id_type target#

The real, colocatable destination for the wrapped action.

The peer’s locality id (i.e. peer_locality, the value originally passed into registry::join()). Forwarded to hpx::colocated() and used as the destination of hpx::sync(act, target, ts...) inside dispatch_work().

std::uint64_t join_epoch = 0#

The epoch at which this peer was joined.

Recorded by registry::join() and used to identify which registry entry a later registry::leave() call refers to - so that a racing re-join of the same peer locality (which mints a fresh join_epoch of its own) cannot be mistaken for the join this joined_peer was returned from.

namespace server#
struct peer_snapshot#
#include <registry.hpp>

Plain-data view of a single joined peer, safe to hand out to callers outside the registry (unlike peer_entry, does not expose the ready/evict_pending bookkeeping used internally to coordinate concurrent join()/evict_peer() calls).

Public Members

hpx::id_type peer_locality#

The peer locality this entry was joined against.

std::uint64_t join_epoch#

The epoch at which peer_locality was joined.

class registry : public hpx::components::component_base<registry>#

Public Functions

registry()#
joined_peer join(hpx::id_type const &peer_locality)#

Joins a peer locality and creates or reuses its local supervision state.

Parameters

peer_locality – The peer locality to observe.

std::vector<peer_snapshot> snapshot_peers() const#

Returns a point-in-time snapshot of all fully joined, non-evicting peers.

Intended for a future failure-detection poller (or other local consumers) that needs a stable, lock-safe list of peers to iterate over without reaching into peers_ directly. Entries mid-join (ready == false) or already scheduled for eviction (evict_pending == true) are excluded, so a poller never observes a half-registered or torn-down peer.

Returns

A snapshot of every peer entry with ready == true and evict_pending == false at the time of the call.

void leave(hpx::id_type const &peer_locality, std::uint64_t join_epoch)#

Removes a previously joined peer.

Parameters

  • peer_locality – The peer locality to leave.

  • join_epoch – Must match the join epoch currently recorded for peer_locality (i.e. the epoch returned by the corresponding join()). If peer_locality has since been re-joined (fresh epoch) or already evicted, this call is a no-op.

Protected Functions

std::tuple<hpx::id_type, std::uint64_t, bool> reserve_ownership(hpx::id_type const &peer_locality)#
std::pair<hpx::id_type, hpx::id_type> register_observers(hpx::id_type const &peer_locality, std::uint64_t join_epoch)#
void evict_peer(hpx::id_type const &peer_locality, std::uint64_t join_epoch, hpx::id_type keep_alive, bool preserve_terminal_state)#

Protected Static Functions

static void cleanup_peer(hpx::id_type const &peer_locality, hpx::id_type const &lifecycle_observer, hpx::id_type const &activity_observer, bool preserve_terminal_state)#

Unregisters a peer’s observers and, unless preserve_terminal_state is set, removes its locally tracked supervision state.

Performs the actual peer teardown deferred by evict_peer(): unregisters lifecycle_observer and activity_observer on peer_locality, and removes peer_locality's locally tracked supervision state unless preserve_terminal_state is true, in which case that state - which was last set to the peer’s terminal event by register_observers()’s lifecycle callback - is left in place as a tombstone rather than reset to “unknown”. This lets any admission check still in flight against peer_locality (e.g. check_admission()) keep observing the fenced/terminal outcome after eviction has run, instead of racing against it. A subsequent join() re-seeding this locality with a fresh epoch naturally overwrites the tombstone. Kept separate from evict_peer() because evict_peer() only posts this work as a task (via hpx::post()) rather than performing it inline.

Parameters

  • peer_locality – The locality that owns the observers, and whose local supervision state is removed.

  • lifecycle_observer – The lifecycle observer id to unregister.

  • activity_observer – The activity observer id to unregister.

  • preserve_terminal_state – If true, leave peer_locality’s local supervision state in place instead of removing it.

Private Members

mutable hpx::spinlock mtx_#
hpx::lcos::local::detail::condition_variable cond_#
std::map<hpx::id_type, peer_entry> peers_#
struct peer_entry#

Internal bookkeeping for a single joined (or joining) peer.

Not exposed outside the registry; see peer_snapshot for the plain-data subset safe to hand to external callers.

Public Functions

inline explicit peer_entry(hpx::id_type const &peer_locality)#

Public Members

const hpx::id_type peer_locality#

The locality that owns this peer’s. Surfaced read-only via peer_snapshot::peer_locality.

hpx::id_type lifecycle_observer#

The observer id registered on peer_locality to receive this peer’s terminal lifecycle notification (drives evict_peer() via hpx::post()).

hpx::id_type activity_observer#

The observer id registered on peer_locality to receive this peer’s activity notifications (used to keep peer_locality’s local state current between terminal events).

std::uint64_t join_epoch = 0#

The epoch at which this peer was joined, recorded by join() and used by evict_peer() (instead of shadow) to identify and used by evict_peer() to identify which entry a deferred eviction refers to.

bool ready = false#

False while a join() call has reserved ownership of this peer’s locality (i.e. is in the process of performing the remote observer registrations) but has not yet filled in the rest of the entry. Concurrent join() calls for the same peer wait on cond_ instead of racing to register duplicate observers.

bool evict_pending = false#

True once a terminal notification has been observed for this peer but eviction has not yet completed (deferred via hpx::post() to evict_peer()). Ensures a terminal notification racing ahead of join() completion is deferred instead of dropped, and lets snapshot_peers() exclude a peer that is already tearing down.

bool evict_preserve_terminal_state = false#

The preserve_terminal_state argument evict_peer() was called with when it set evict_pending above, remembered so that join()’s deferred cleanup_peer() call (once the join in progress completes) preserves or drops peer_locality’s local supervision state consistently with what the racing terminal notification requested.