Struct Task

pub struct Task<T>(/* private fields */);

This is the same as a JoinHandle, except that the future will be cancelled when the task is dropped.

Implementations

impl<T> Task<T>

pub fn detach_on_drop(self) -> JoinHandle<T>

Returns a JoinHandle which will have detach-on-drop semantics.

impl Task<()>

pub fn detach(self)

Detach this task so that it can run independently in the background.

Note: This is usually not what you want. This API severs the control flow from the caller. This can result in flaky tests and makes it impossible to return values (including errors).

If your goal is to run multiple tasks concurrently, use Scope.

You can also use other futures combinators such as:

• [futures::future::join]
• [futures::future::select]
• [futures::select]

or their error-aware variants

• [futures::future::try_join]
• [futures::future::try_select]

or their stream counterparts

• [futures::stream::StreamExt::for_each]
• [futures::stream::StreamExt::for_each_concurrent]
• [futures::stream::TryStreamExt::try_for_each]
• [futures::stream::TryStreamExt::try_for_each_concurrent]

can meet your needs.

impl<T: Send + 'static> Task<T>

pub fn spawn(future: impl Future<Output = T> + Send + 'static) -> Task<T>

Spawn a new task on the global scope of the current executor.

The task may be executed on any thread(s) owned by the current executor. See Task::local for an equivalent that ensures locality.

The passed future will live until either (a) the future completes, (b) the returned Task is dropped while the executor is running, or (c) the executor is destroyed; whichever comes first.

Code that uses scopes is encouraged to spawn on a shorter lived scope or explicitly call Scope::global() for spawning.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

impl<T: 'static> Task<T>

pub fn local(future: impl Future<Output = T> + 'static) -> Task<T>

Spawn a new task on the global scope of the thread local executor.

The passed future will live until either (a) the future completes, (b) the returned Task is dropped while the executor is running, or (c) the executor is destroyed; whichever comes first.

NOTE: This is not supported with a [SendExecutor] and will cause a runtime panic. Use Task::spawn instead.

Code that uses scopes is encouraged to spawn on a shorter lived scope or explicitly call Scope::global() for spawning.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

impl<T: 'static> Task<T>

pub fn cancel(self) -> impl Future<Output = Option<T>>

Cancel a task and returns a future that resolves once the cancellation is complete. The future can be ignored in which case the task will still be cancelled.

Trait Implementations

impl<T: Debug> Debug for Task<T>

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

Formats the value using the given formatter.

impl<T> Drop for Task<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<JoinHandle<T>> for Task<T>

fn from(value: JoinHandle<T>) -> Self

Converts to this type from the input type.

impl<T: 'static> Future for Task<T>

type Output = 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.