hpx::supervision::query_state#
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::query_state(hpx::id_type const &locality, hpx::id_type const &target)#
Query the last known lifecycle state of a target actor on a possibly remote locality.
The function query_state() asynchronously retrieves the most recently published lifecycle event for target, as observed by the supervision manager running on locality.
Note
If target is not local to locality, the query is forwarded to the actor’s home locality, adding about one parcel round-trip of latency.
Note
The returned lifecycle_state::ec may carry a staleness error code, indicating that the returned state may be stale if a preceding observer parcel has not yet been delivered.
Note
The lifecycle_state::event_sequence_number allows clients to detect gaps, e.g. if an observer callback was skipped due to a network failure.
- Parameters
locality – [in] The locality on which the supervision manager responsible for target is running.
target – [in] The actor (or component) whose state is queried.
- 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 last event recorded for target (i.e., the most recent value in the runtime’s event log), together with its timestamp and sequence number.
-
lifecycle_state hpx::supervision::query_state(hpx::launch::sync_policy, hpx::id_type const &locality, hpx::id_type const &target, hpx::error_code &ec = hpx::throws)#
Query the last known lifecycle state of a target actor on a possibly remote locality, blocking until the result is available.
This is the synchronous equivalent of query_state(hpx::id_type const&, hpx::id_type const&).
Note
The returned lifecycle_state::ec may carry a staleness error code, indicating that the returned state may be stale if a preceding observer parcel has not yet been delivered.
- Parameters
locality – [in] The locality on which the supervision manager responsible for target is running.
target – [in] The actor (or component) whose state is queried.
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 last event recorded for target, together with its timestamp and sequence number.
-
lifecycle_state hpx::supervision::query_state(hpx::id_type const &target, hpx::error_code &ec = hpx::throws)#
Query the last known lifecycle state of a target actor on the local locality.
- Parameters
target – [in] The actor (or component) whose state is queried. Must be local to the calling locality.
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
The last event recorded locally for target, together with its timestamp and sequence number.
-
hpx::future<lifecycle_state> hpx::supervision::query_state(registry const &handle)#
Query the last known lifecycle state of the local locality, as tracked by handle.
Convenience overload of hpx::supervision::query_state(hpx::id_type const&, hpx::id_type const&) that resolves both the locality and the target to hpx::find_here() instead of requiring the caller to name them explicitly. Forwards to
hpx::supervision::query_state(hpx::find_here(), hpx::find_here()).- Parameters
handle – [in] The registry (typically returned by init()) whose locality’s state is queried.
- Returns
A future holding the last event recorded for the local locality, together with its timestamp, sequence number, and epoch (see lifecycle_state::epoch — in particular, useful for recovering the epoch init() started this locality’s lifecycle tracking at, for use with publish_event()).
-
lifecycle_state hpx::supervision::query_state(hpx::launch::sync_policy policy, registry const &handle, hpx::error_code &ec = hpx::throws)#
Query the last known lifecycle state of the local locality, as tracked by handle, blocking until the result is available.
This is the synchronous equivalent of query_state(registry const&).
- Parameters
policy – Tag selecting the blocking overload of query_state().
handle – [in] The registry whose locality’s state is queried.
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 last event recorded for the local locality.
-
hpx::future<lifecycle_state> hpx::supervision::query_state(registry const &handle, discovered_peer const &peer)#
Query the last known lifecycle state of a discovered peer’s locality.
Convenience overload of hpx::supervision::query_state(hpx::id_type const&, hpx::id_type const&) that resolves both the locality and the target to peer.locality instead of requiring the caller to name them explicitly — mirroring the self-query overload above, but issued against peer.locality’s own supervision manager instead of the local one. Forwards to
hpx::supervision::query_state(peer.locality, peer.locality).- Parameters
handle – [in] Unused beyond overload resolution and symmetry with the self-query overload above; peer alone carries everything this call needs.
peer – [in] The peer (typically returned by discover_peers()/ discover_and_join()) whose state is queried.
- Returns
A future holding the last event recorded for peer.locality, as observed by the supervision manager running on peer.locality.
-
lifecycle_state hpx::supervision::query_state(hpx::launch::sync_policy policy, registry const &handle, discovered_peer const &peer, hpx::error_code &ec = hpx::throws)#
Query the last known lifecycle state of a discovered peer’s locality, blocking until the result is available.
This is the synchronous equivalent of query_state(registry const&, discovered_peer const&).
- Parameters
policy – Tag selecting the blocking overload of query_state().
handle – [in] Unused beyond overload resolution; see the asynchronous overload.
peer – [in] The peer whose state is queried.
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 peer.locality does not hold a valid registry client, unless ec was pre-initialized to something other than hpx::throws.
- Returns
The last event recorded for peer.locality.