hpx::supervision::register_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::supervision::publish_event

• hpx::supervision::query_state

• hpx::supervision::unregister_observer

• hpx::supervision::remove_target

• hpx::supervision::register_activity_observer

• hpx::supervision::unregister_activity_observer

• hpx::supervision::check_admission

• hpx::supervision::await_terminal

• hpx::supervision::is_valid_transition

hpx::future<hpx::id_type> hpx::supervision::register_observer(hpx::id_type const &locality, hpx::id_type const &target, lifecycle_callback const &callback, std::optional<std::uint64_t> epoch_filter = std::nullopt)

Register a callback to observe lifecycle events published by a target actor running on a possibly remote locality.

Note

If locality is the locality target is running on, the callback is invoked synchronously from within the publish call (best effort; the callback must not block indefinitely).

Note

If locality differs from the locality target is running on, the callback is 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.

• target – [in] The actor (or component) to observe.

• callback – [in] The callback invoked whenever target publishes a lifecycle event.

• epoch_filter – [in] If set, restricts notifications to events published under this epoch; events published under any other epoch are silently skipped for this observer. If std::nullopt (the default), the observer is notified regardless of epoch.

Throws

hpx::exception – if locality does not represent a locality, or if target does not represent a valid target. 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_observer() in order to stop receiving notifications.

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

Register a callback to observe lifecycle events published by a target actor running on a possibly remote locality, blocking until the registration has completed.

This is the synchronous equivalent of register_observer(hpx::id_type const&, hpx::id_type const&, lifecycle_callback const&).

Parameters

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

• target – [in] The actor (or component) to observe.

• callback – [in] The callback invoked whenever target publishes a lifecycle event.

• epoch_filter – [in] If set, restricts notifications to events published under this epoch; see the asynchronous overload for details.

• 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, or if target does not represent a valid target, unless ec was not pre-initialized to hpx::throws.

Returns

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

hpx::id_type hpx::supervision::register_observer(hpx::id_type const &target, lifecycle_callback const &callback, std::optional<std::uint64_t> epoch_filter = std::nullopt, hpx::error_code &ec = hpx::throws)

Register a callback to observe lifecycle events published by a target actor on the local locality.

Note

The callback is invoked synchronously from within the publish call (best effort; the callback must not block indefinitely) and must not throw; exceptions thrown from it are logged and do not affect the observer registration.

Parameters

• target – [in] The actor (or component) to observe. Must be local to the calling locality.

• callback – [in] The callback invoked whenever target publishes a lifecycle event.

• epoch_filter – [in] If set, restricts notifications to events published under this epoch; events published under any other epoch are silently skipped for this observer. 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 target does not represent a valid target, unless ec was initialized to hpx::throws.

Returns

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