pub struct RemoteHandle { /* private fields */ }Expand description
Handle to a remote task, analogous to TaskHandle.
RemoteHandle is returned by spawn_remote and provides:
- The remote task ID for identification and tracing
- The target node and computation name for debugging
join()to await the remote resultabort(&Cx)to request cancellation of the remote task
§Region Ownership
The RemoteHandle is owned by the local region. When the region closes,
all remote handles participate in quiescence: the region waits for remote
tasks to complete (or escalates via cancellation/lease expiry).
§Current Contract
The handle is the local, region-owned proxy for the remote lifecycle defined in this module. Attached runtimes drive it via the explicit spawn/ack/cancel/result/lease protocol. When no runtime is attached, the handle resolves through the configured deterministic fallback instead of silently spawning detached work.
Implementations§
Source§impl RemoteHandle
impl RemoteHandle
Sourcepub fn remote_task_id(&self) -> RemoteTaskId
pub fn remote_task_id(&self) -> RemoteTaskId
Returns the remote task ID.
Sourcepub fn local_task_id(&self) -> Option<TaskId>
pub fn local_task_id(&self) -> Option<TaskId>
Returns the local proxy task ID, if one was assigned.
Sourcepub fn computation(&self) -> &ComputationName
pub fn computation(&self) -> &ComputationName
Returns the computation name.
Sourcepub fn owner_region(&self) -> RegionId
pub fn owner_region(&self) -> RegionId
Returns the owning region.
Sourcepub fn state(&self) -> RemoteTaskState
pub fn state(&self) -> RemoteTaskState
Returns the current observed state of the remote task.
Sourcepub fn is_finished(&self) -> bool
pub fn is_finished(&self) -> bool
Returns true if a terminal remote result has been buffered locally.
A merely closed result channel does not count as finished here. The
sender may have disappeared before the remote lifecycle reached a
terminal state, and callers still need close() / abort() to fence
and drain the remote task in that case.
Sourcepub async fn close(&mut self, cx: &Cx) -> Outcome<RemoteOutcome, RemoteError>
pub async fn close(&mut self, cx: &Cx) -> Outcome<RemoteOutcome, RemoteError>
Requests cancellation and drains the remote lifecycle to a terminal state.
This is the explicit close operation for a remote handle: it forwards a best-effort cancellation request when a runtime is attached, then awaits the terminal remote result so origin-side runtime state can be cleared.
§Errors
Unlike join, once close() starts draining it ignores
caller cancellation so runtime bookkeeping is always finalized before
returning. If the terminal result was already consumed, it returns
PolledAfterCompletion.
Sourcepub async fn join(&mut self, cx: &Cx) -> Outcome<RemoteOutcome, RemoteError>
pub async fn join(&mut self, cx: &Cx) -> Outcome<RemoteOutcome, RemoteError>
Waits for the remote task to complete and returns its result.
This method yields until the remote task completes (or fails/cancels), unless the caller context is cancelled first.
§Errors
Returns RemoteError if the remote task failed, was cancelled,
the lease expired, or a terminal result was already consumed.
Sourcepub fn try_join(&mut self) -> Result<Option<RemoteOutcome>, RemoteError>
pub fn try_join(&mut self) -> Result<Option<RemoteOutcome>, RemoteError>
Attempts to get the remote task’s result without waiting.
§Returns
Ok(Some(result))if the remote task has completedOk(None)if the remote task is still runningErr(RemoteError)if the remote task failed
Sourcepub fn abort(&self, cx: &Cx)
pub fn abort(&self, cx: &Cx)
Requests cancellation of the remote task using the caller’s remote capability.
This is a request — the remote node may not stop immediately.
The cancellation propagates via the remote protocol when the provided
context carries an attached RemoteRuntime.
If the context does not have a remote capability, or if it is configured for deterministic Phase 0 fallback without an attached runtime, this is a no-op.