Module async_std::task

Types and traits for working with asynchronous tasks.

This module is similar to std::thread, except it uses asynchronous tasks in place of threads.

The task model

An executing asynchronous Rust program consists of a collection of native OS threads, on top of which multiple stackless coroutines are multiplexed. We refer to these as "tasks". Tasks can be named, and provide some built-in support for synchronization.

Communication between tasks can be done through channels, Rust's message-passing types, along with other forms of tasks synchronization and shared-memory data structures. In particular, types that are guaranteed to be threadsafe are easily shared between tasks using the atomically-reference-counted container, Arc.

Fatal logic errors in Rust cause thread panic, during which a thread will unwind the stack, running destructors and freeing owned resources. If a panic occurs inside a task, there is no meaningful way of recovering, so the panic will propagate through any thread boundaries all the way to the root task. This is also known as a "panic = abort" model.

Spawning a task

A new task can be spawned using the task::spawn function:

use async_std::task;

task::spawn(async {
    // some work here
});

In this example, the spawned task is "detached" from the current task. This means that it can outlive its parent (the task that spawned it), unless this parent is the root task.

The root task can also wait on the completion of the child task; a call to spawn produces a JoinHandle, which implements Future and can be awaited:

use async_std::task;

let child = task::spawn(async {
    // some work here
});
// some work here
let res = child.await;

The await operator returns the final value produced by the child task.

Task-local storage

This module also provides an implementation of task-local storage for Rust programs. Task-local storage is a method of storing data into a global variable that each task in the program will have its own copy of. Tasks do not share this data, so accesses do not need to be synchronized.

A task-local key owns the value it contains and will destroy the value when the task exits. It is created with the task_local! macro and can contain any value that is 'static (no borrowed pointers). It provides an accessor function, with, that yields a shared reference to the value to the specified closure. Task-local keys allow only shared access to values, as there would be no way to guarantee uniqueness if mutable borrows were allowed.

Macros

ready

Extracts the successful type of a Poll<T>.

Structs

Context	The Context of an asynchronous task.
JoinError	Task failed to execute to completion.
JoinHandle	An owned permission to join on a task (await its termination).
LocalKey	A key for task-local data.
LocalSet	A set of tasks which are executed on the same thread.
Waker	A Waker is a handle for waking up a task by notifying its executor that it is ready to be run.

Enums

Poll	Indicates whether a value is available or if the current task has been scheduled to receive a wakeup instead.

Functions

block_in_place	Runs the provided blocking function without blocking the executor.
block_on	Spawns a task and blocks the current thread on its result.
sleep	Sleeps for the specified amount of time.
spawn	Spawns a new asynchronous task, returning a JoinHandle for it.
spawn_blocking	Runs the provided closure on a thread where blocking is acceptable.
spawn_local	Spawns a !Send future on the local task set.
yield_now	Yields execution back to the Tokio runtime.
yield_now	Cooperatively gives up a timeslice to the task scheduler.