hpx::supervision::await_terminal#

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<lifecycle_state> hpx::supervision::await_terminal(hpx::id_type const &locality, hpx::id_type const &target, std::uint64_t epoch = 0, std::optional<std::chrono::steady_clock::duration> timeout = std::nullopt)#

Asynchronously wait for a target actor on a possibly remote locality to reach a terminal lifecycle event (completed or failed) within a given epoch.

The function await_terminal() is a one-shot, blocking-free counterpart to register_observer() for the specific case of waiting on the terminal transition: unlike an observer, it does not need to be explicitly unregistered, but it also only ever resolves once, for the exact (target, epoch) pair passed in.

Note

below for this call only. If std::nullopt (the default), locality’s current default timeout is used instead.

Note

below).

Note

locality bounds the lifetime of every waiter it registers on behalf of an outstanding call, so dropping the returned future without target ever reaching a terminal event under epoch does not leak the corresponding waiter entry indefinitely: it is swept and invalidated at or after timeout elapses, enforced by a background timer on locality independently of any further activity for target, so an idle target’s waiter is not left to accumulate until some later, unrelated call happens to sweep it. Callers that need a tighter bound than timeout should still race the returned future against an external timeout.

Parameters

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

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

  • epoch – [in] The epoch target must reach a terminal event under for the returned future to resolve. If target’s epoch is later superseded by a higher epoch (see the epoch semantics of publish_event) before it reaches a terminal event under epoch, the returned future becomes exceptional (see

  • timeout – [in] Overrides the server-enforced timeout described in

Throws

  • below) – instead of ever resolving with a value.

  • hpx::exception – if locality does not represent a locality, or if target does not represent a valid target. The returned future becomes exceptional with a hpx::error::stale_state exception, naming target, epoch, and the epoch that superseded it, if target’s epoch advances past epoch before reaching a terminal event under it. It also becomes exceptional with a hpx::error::future_cancelled exception if neither of the above happens before timeout elapses (see

Returns

A future that becomes ready, holding the lifecycle_state recorded for target, as soon as target reaches a terminal event under epoch. If target has already reached a terminal event under epoch at the time of the call, the returned future is ready immediately.

lifecycle_state hpx::supervision::await_terminal(hpx::launch::sync_policy, hpx::id_type const &locality, hpx::id_type const &target, std::uint64_t epoch = 0, std::optional<std::chrono::steady_clock::duration> timeout = std::nullopt, hpx::error_code &ec = hpx::throws)#

Wait for a target actor on a possibly remote locality to reach a terminal lifecycle event, blocking until it does.

This is the synchronous equivalent of await_terminal(hpx::id_type const&, hpx::id_type const&, std::uint64_t).

Note

This call blocks until target reaches a terminal event, its epoch is superseded, or timeout elapses.

Parameters

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

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

  • epoch – [in] The epoch target must reach a terminal event under. See the asynchronous overload for details.

  • timeout – [in] Overrides the server-enforced timeout described in the asynchronous overload for this call only. If std::nullopt (the default), locality’s current default timeout is used instead.

  • 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. Also throws (or sets ec to) a hpx::error::stale_state exception, naming target, epoch, and the epoch that superseded it, if target’s epoch advances past epoch before reaching a terminal event under it. Also throws (or sets ec to) a hpx::error::future_cancelled exception if neither of the above happens before timeout elapses.

Returns

The lifecycle_state recorded for target once it reaches a terminal event under epoch.

hpx::future<lifecycle_state> hpx::supervision::await_terminal(hpx::id_type const &target, std::uint64_t epoch = 0, std::optional<std::chrono::steady_clock::duration> timeout = std::nullopt)#

Asynchronously wait for a target actor on the local locality to reach a terminal lifecycle event within a given epoch.

Note

As for the remote overloads, the returned future becomes exceptional with hpx::error::stale_state if epoch is superseded, or with hpx::error::future_cancelled if timeout elapses first.

Parameters

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

  • epoch – [in] The epoch target must reach a terminal event under. See the remote overload for details.

  • timeout – [in] Overrides the server-enforced timeout described in the asynchronous overload for this call only. If std::nullopt (the default), the local locality’s default timeout is used instead.

Returns

A future that becomes ready, holding the lifecycle_state recorded for target, as soon as target reaches a terminal event under epoch. See the remote overload for how the returned future behaves if target’s epoch is superseded before reaching a terminal event under epoch.

lifecycle_state hpx::supervision::await_terminal(hpx::launch::sync_policy, hpx::id_type const &target, std::uint64_t epoch = 0, std::optional<std::chrono::steady_clock::duration> timeout = std::nullopt, hpx::error_code &ec = hpx::throws)#

Synchronously wait for a local supervised target to reach a terminal lifecycle state (completed or failed).

This overload is restricted to targets that are guaranteed to be local to the calling locality. Because no dispatch/AGAS round-trip is required, it is cheaper than the remote hpx::launch::sync_policy overload and simply blocks the calling thread on the underlying local future.

Parameters

  • target – The id of the supervised entity to wait on. Must refer to a component that is local to this locality.

  • epoch – The join/generation epoch the caller expects target to still be part of. Passing an epoch that no longer matches the target’s current epoch may cause the wait to resolve immediately with a mismatch-related error.

  • timeout – Optional upper bound on how long to wait before giving up. If not supplied, uses the local supervision manager’s default timeout.

  • ec – Used to report errors instead of throwing an exception. When target does not represent a valid id, hpx::error::bad_parameter is reported. If the wait is cancelled due to timeout elapsing without a terminal state being reached, hpx::error::future_cancelled is reported.

Throws

hpx::exception – if ec is hpx::throws (the default) and an error is encountered; otherwise sets ec to reflect the error and returns.

Returns

The terminal lifecycle_state observed for target, or a default-constructed lifecycle_state if an error occurred and ec was used to report it.