Struct TaskHandle 

pub struct TaskHandle<T> { /* private fields */ }

A handle to a spawned task that can be used to await its result.

TaskHandle<T> is returned by Scope::spawn() and related methods. It provides:

• The task ID for identification and debugging
• A way to await the task’s result via join()

Ownership

The TaskHandle does not own the task - the task is owned by its region. If the TaskHandle is dropped, the task continues running. The handle is just a way to observe the result.

Cancel Safety

If join() is cancelled, the handle can be retried. The task’s result will be available once the task completes.

Example

let handle = scope.spawn(&mut state, cx, async { 42 });
let result = handle.join(cx).await?;
assert_eq!(result, 42);

Implementations

impl<T> TaskHandle<T>

pub fn task_id(&self) -> TaskId

Returns the task ID of the spawned task.

pub fn is_finished(&self) -> bool

Returns true if the task’s result is ready.

pub fn join<'a>(&'a self, cx: &'a Cx) -> JoinFuture<'a, T>

Waits for the task to complete and returns its result.

This method yields until the spawned task completes, then returns its output value.

Errors

Returns Err(JoinError::Cancelled) if the task was cancelled. Returns Err(JoinError::Panicked) if the task panicked.

Cancel Safety

If this method is cancelled (the returned future is dropped), the task is automatically aborted. This ensures that “stopping waiting” translates to “stopping the task”, preventing orphan tasks in races and timeouts.

Example

let handle = scope.spawn(&mut state, cx, async { 42 });
match handle.join(cx).await {
    Ok(value) => println!("Task returned: {value}"),
    Err(JoinError::Cancelled(r)) => println!("Task was cancelled: {r}"),
    Err(JoinError::Panicked(p)) => println!("Task panicked: {p}"),
}

pub fn join_with_drop_reason<'a>( &'a self, cx: &'a Cx, reason: CancelReason, ) -> JoinFuture<'a, T>

Waits for the task to complete, aborting with a specific reason if dropped.

This is like join(), but allows specifying the cancellation reason that should be used if the join future is dropped before completion. This is useful for combinators like race that want to attribute cancellation to “losing the race”.

pub fn try_join(&self) -> Result<Option<T>, JoinError>

Attempts to get the task’s result without waiting.

Returns

• Ok(Some(result)) if the task has completed
• Ok(None) if the task is still running
• Err(JoinError) if the task was cancelled or panicked

pub fn abort(&self)

Aborts the task (requests cancellation).

This is a request - the task may not stop immediately. The task will observe the cancellation at its next checkpoint.

pub fn abort_with_reason(&self, reason: CancelReason)

Aborts the task (requests cancellation) with an explicit reason.

The reason is only set if none is already present, to avoid clobbering more specific cancellation attribution.

Trait Implementations

impl<T: Debug> Debug for TaskHandle<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.