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. An exception thrown from it does not unregister the observer, but it is recorded as target having failed (see below).

Note

If locality differs from the locality the callback lives on, and sending a notification to the callback fails with hpx::error::locality_was_disconnected (e.g. its locality was killed), the observer is unregistered. Such a failure does not change the lifecycle state recorded for target. Any other delivery failure, including an exception thrown by the callback itself, is recorded as target having failed.

Note

A failed send is told apart from an exception thrown by the callback by the locality the error was raised on. A callback that rethrows a hpx::error::locality_was_disconnected error raised on locality (e.g. by a call it made back to locality) is therefore taken for a failed send, and the observer is unregistered although it is still reachable.

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. An exception thrown from it does not unregister the observer, but it is recorded as target having failed.

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.