Struct JoinHandle

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

An owned permission to join a task (await its termination).

This is equivalent to the standard library’s std::thread::JoinHandle type, but for asynchronous tasks rather than OS threads.

A JoinHandle detaches the associated task when it is dropped, which means that there is no longer any handle to the task and no way to await its termination.

JoinHandles implement Future, so a task’s output can be awaited by .awaiting its JoinHandle.

This struct is returned by the Scheduler::spawn and Scheduler::spawn_allocated methods, and the task::Builder::spawn and task::Builder::spawn_allocated methods.

Implementations

impl<T> JoinHandle<T>

pub fn task_ref(&self) -> TaskRef

Returns a TaskRef referencing the task this JoinHandle is associated with.

This increases the task’s reference count; its storage is not deallocated until all such TaskRefs are dropped.

pub fn is_complete(&self) -> bool

Returns true if this task has completed.

Tasks are considered completed when the spawned Future has returned Poll::Ready, or if the task has been canceled by the cancel() method.

Note: This method can return false after cancel() has been called. This is because calling cancel begins the process of cancelling a task. The task is not considered canceled until it has been polled by the scheduler after calling cancel().

pub fn cancel(&self) -> bool

Forcibly cancel the task.

Canceling a task sets a flag indicating that it has been canceled and should terminate. The next time a canceled task is polled by the scheduler, it will terminate instead of polling the inner Future. If the task has a JoinHandle, that JoinHandle will complete with a JoinError. The task then will be deallocated once all JoinHandles and TaskRefs referencing it have been dropped.

This method returns true if the task was canceled successfully, and false if the task could not be canceled (i.e., it has already completed, has already been canceled, cancel culture has gone TOO FAR, et cetera).

pub fn id(&self) -> TaskId

Returns a TaskId that uniquely identifies this task.

The returned ID does not increment the task’s reference count, and may persist even after the task it identifies has completed and been deallocated.

Trait Implementations

impl<T> Debug for JoinHandle<T>

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

Formats the value using the given formatter.

impl<T> Drop for JoinHandle<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Future for JoinHandle<T>

type Output = Result<T, JoinError<T>>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T> PartialEq<&JoinHandle<T>> for TaskId

fn eq(&self, other: &&JoinHandle<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<&JoinHandle<T>> for TaskRef

fn eq(&self, other: &&JoinHandle<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<&TaskId> for JoinHandle<T>

fn eq(&self, other: &&TaskId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<&TaskRef> for JoinHandle<T>

fn eq(&self, other: &&TaskRef) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<JoinHandle<T>> for TaskId

fn eq(&self, other: &JoinHandle<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<JoinHandle<T>> for TaskRef

fn eq(&self, other: &JoinHandle<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<TaskId> for JoinHandle<T>

fn eq(&self, other: &TaskId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<TaskRef> for JoinHandle<T>

fn eq(&self, other: &TaskRef) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq> PartialEq for JoinHandle<T>

fn eq(&self, other: &JoinHandle<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Eq> Eq for JoinHandle<T>

impl<T> StructuralPartialEq for JoinHandle<T>