hpx::supervision::register_activity_observer#

Defined in header hpx/supervision.hpp.

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

See also:

hpx::future<hpx::id_type> hpx::supervision::register_activity_observer(hpx::id_type const &locality, activity_callback const &callback, std::optional<std::uint64_t> epoch_filter = std::nullopt)#

Register a callback to observe activity-state transitions of all targets tracked on a possibly remote locality.

Note

For every target tracked on locality that is already activity_state::active at registration time, the new observer synchronously receives one replay notification (carrying activity_transition::already_active) as part of registration, taken under the same lock that serializes activity-state transitions. This guarantees the observer sees exactly one notification for each such target’s current activity state: either the replay, or a live transition that raced with registration, but never both and never neither.

Note

If locality is the local locality, callbacks (including the registration-time replay) are invoked synchronously from within the call that triggered the transition (best effort; the callback must not block indefinitely).

Note

If locality is remote, callbacks are invoked asynchronously via a dedicated parcel, with retry semantics (e.g., 3 attempts over 500 ms before logging failure).

Note

The callback must not throw; exceptions thrown from it are logged and do not affect the observer registration.

Parameters

  • locality – [in] The locality on which the callback should be registered.

  • callback – [in] The callback invoked whenever any target tracked on locality transitions between activity_state::inactive and activity_state::active.

  • epoch_filter – [in] If set, restricts notifications to transitions recorded under this epoch; transitions recorded under any other epoch are silently skipped for this observer. This also applies to the registration-time replay described below. If std::nullopt (the default), the observer is notified regardless of epoch.

Throws

hpx::exception – if locality does not represent a locality. The returned future becomes exceptional if the operation fails.

Returns

A future holding the global id of the observer handle. This handle must be passed to unregister_activity_observer() in order to stop receiving notifications.

hpx::id_type hpx::supervision::register_activity_observer(hpx::launch::sync_policy, hpx::id_type const &locality, activity_callback const &callback, std::optional<std::uint64_t> epoch_filter = std::nullopt, hpx::error_code &ec = hpx::throws)#

Register a callback to observe activity-state transitions of all targets tracked on a possibly remote locality, blocking until the registration has completed.

This is the synchronous equivalent of register_activity_observer(hpx::id_type const&, activity_callback const&, std::optional<std::uint64_t>).

Parameters

  • locality – [in] The locality on which the callback should be registered.

  • callback – [in] The callback invoked whenever any target tracked on locality transitions between activity_state::inactive and activity_state::active.

  • epoch_filter – [in] If set, restricts notifications to transitions recorded under this epoch; see the asynchronous overload for details, including how this applies to the registration-time replay.

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Throws

hpx::exception – if locality does not represent a locality, unless ec was not pre-initialized to hpx::throws.

Returns

The global id of the observer handle. This handle must be passed to unregister_activity_observer() in order to stop receiving notifications.

hpx::id_type hpx::supervision::register_activity_observer(activity_callback const &callback, std::optional<std::uint64_t> epoch_filter = std::nullopt, hpx::error_code &ec = hpx::throws)#

Register a callback to observe activity-state transitions of all targets tracked on the local locality.

Note

As for the remote overloads, for every target on the local locality that is already activity_state::active at registration time, one activity_transition:: already_active replay notification is delivered synchronously as part of this call, taken under the same lock that serializes activity-state transitions, so the observer can neither miss nor double-receive any active target’s current activity state.

Parameters

  • callback – [in] The callback invoked whenever any target tracked on the local locality transitions between activity_state::inactive and activity_state::active.

  • epoch_filter – [in] If set, restricts notifications to transitions recorded under this epoch, including the registration-time replay; see the remote overload for details. If std::nullopt (the default), the observer is notified regardless of epoch.

  • ec – [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Throws

hpx::exception – if the operation fails, unless ec was initialized to hpx::throws.

Returns

The global id of the observer handle. This handle must be passed to unregister_activity_observer() in order to stop receiving notifications.