hpx::supervision::publish_event#

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<publish_result> hpx::supervision::publish_event(hpx::id_type const &locality, hpx::id_type const &target, hpx::supervision::event ev, std::uint64_t epoch = 0)#

Publish a lifecycle event for a target actor on a possibly remote locality.

The function publish_event() asynchronously notifies the supervision manager running on locality that target has reached the lifecycle state ev. Registered observers of target are notified as a result.

Note

Publishing is not idempotent: publishing the same event twice creates two distinct records with different timestamps.

Note

Events are immediately visible to observers on the same locality as target; remote observers become aware of the event within about 1-2 parcel round-trips to the AGAS authority managing the actor’s registration.

Parameters

  • locality – [in] The locality on which the supervision manager responsible for target is running.

  • target – [in] The actor (or component) for which the event is published.

  • ev – [in] The lifecycle event to publish for target.

  • epoch – [in] The epoch this publication belongs to. Publications are compared against the target’s current epoch: publications for a lower epoch are rejected as stale no-ops, publications for a higher epoch reset the target’s sequence number and become the new current epoch, and publications for the current epoch are applied normally (subject to terminal-state latching).

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 that becomes ready once the event has been recorded by the supervision manager on locality, holding publish_result::applied, publish_result::already_terminal if target had already reached a terminal event (completed or failed) within epoch, or publish_result::stale_epoch if epoch is lower than the target’s current epoch.

publish_result hpx::supervision::publish_event(hpx::launch::sync_policy, hpx::id_type const &locality, hpx::id_type const &target, hpx::supervision::event ev, std::uint64_t epoch = 0, hpx::error_code &ec = hpx::throws)#

Publish a lifecycle event for a target actor on a possibly remote locality, blocking until the operation has completed.

This is the synchronous equivalent of publish_event(hpx::id_type const&, hpx::id_type const&, event).

Note

Publishing non-terminal events is not idempotent: publishing the same event twice creates two distinct records with different timestamps. event::completed and event::failed are latched: the first terminal publication for a target wins, and every later terminal publication for that target is a no-op that returns publish_result::already_terminal.

Parameters

  • locality – [in] The locality on which the supervision manager responsible for target is running.

  • target – [in] The actor (or component) for which the event is published.

  • ev – [in] The lifecycle event to publish for target.

  • epoch – [in] The epoch this publication belongs to. See the asynchronous remote overload for the epoch-scoped semantics.

  • 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. As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec.

Returns

publish_result::applied, publish_result::already_terminal if target had already reached a terminal event (completed or failed) within epoch, or publish_result::stale_epoch if epoch is lower than the target’s current epoch.

publish_result hpx::supervision::publish_event(hpx::id_type const &target, hpx::supervision::event ev, std::uint64_t epoch = 0, hpx::error_code &ec = throws)#

Publish a lifecycle event for a target actor on the local locality.

This overload publishes ev directly through the local supervision manager without going through AGAS or a remote parcel. It is intended to be called from within an actor or action running on the same locality as target.

Note

Publishing non-terminal events is not idempotent: publishing the same event twice creates two distinct records with different timestamps. event::completed and event::failed are latched: the first terminal publication for a target wins, and every later terminal publication for that target is a no-op that returns publish_result::already_terminal.

Note

Local observers of target are notified synchronously as part of this call.

Parameters

  • target – [in] The actor (or component) for which the event is published. Must be local to the calling locality.

  • ev – [in] The lifecycle event to publish for target.

  • epoch – [in] The epoch this publication belongs to. See the asynchronous remote overload for the epoch-scoped semantics.

  • 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 not pre-initialized to hpx::throws.

Returns

publish_result::applied, publish_result::already_terminal if target had already reached a terminal event (completed or failed) within epoch, or publish_result::stale_epoch if epoch is lower than the target’s current epoch.

hpx::future<publish_result> hpx::supervision::publish_event(registry const &handle, event ev, std::uint64_t epoch = 0)#

Publish a lifecycle event for the local locality tracked by handle.

Convenience overload of hpx::supervision::publish_event(hpx::id_type const&, hpx::id_type const&, event, std::uint64_t) that resolves both locality and target to hpx::find_here() instead of requiring the caller to name them explicitly. Forwards to hpx::supervision::publish_event( hpx::find_here(), hpx::find_here(), ev, epoch).

Parameters

  • handle – [in] The registry (typically returned by init()) whose locality the event is published for.

  • ev – [in] The lifecycle event to publish.

  • epoch – [in] The epoch this publication belongs to. Typically obtained from a prior query_state(hpx::launch::sync, handle).epoch call. See the raw-id overload for the epoch-scoped semantics.

Returns

A future that becomes ready once the event has been recorded, holding the same publish_result values as the raw-id overload.

publish_result hpx::supervision::publish_event(hpx::launch::sync_policy policy, registry const &handle, event ev, std::uint64_t epoch = 0, hpx::error_code &ec = hpx::throws)#

Publish a lifecycle event for the local locality tracked by handle, blocking until the operation has completed.

This is the synchronous equivalent of publish_event(registry const&, event, std::uint64_t).

Parameters

  • policy – [in] Tag selecting the blocking overload of publish_event().

  • handle – [in] The registry whose locality the event is published for.

  • ev – [in] The lifecycle event to publish.

  • epoch – [in] The epoch this publication belongs to. See the asynchronous overload.

  • 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 handle does not hold a valid registry client, unless ec was pre-initialized to something other than hpx::throws.

Returns

The same publish_result values as the raw-id overload.