Expand description
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 await
ed:
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.
Configuring tasks
A new task can be configured before it is spawned via the Builder
type,
which currently allows you to set the name for the child task:
use async_std::task;
task::Builder::new().name("child1".to_string()).spawn(async {
println!("Hello, world!");
});
The Task
type
Tasks are represented via the Task
type, which you can get in one of
two ways:
- By spawning a new task, e.g., using the
task::spawn
function, and callingtask
on theJoinHandle
. - By requesting the current task, using the
task::current
function.
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.
Naming tasks
Tasks are able to have associated names for identification purposes. By default, spawned
tasks are unnamed. To specify a name for a task, build the task with Builder
and pass
the desired task name to Builder::name
. To retrieve the task name from within the
task, use Task::name
.
Macros
Extracts the successful type of a Poll<T>
.
Structs
An error returned by LocalKey::try_with
.
Task builder that configures the settings of a new task.
The Context
of an asynchronous task.
A handle that awaits the result of a task.
The key for accessing a task-local value.
A handle to a task.
A unique identifier for a task.
A Waker
is a handle for waking up a task by notifying its executor that it
is ready to be run.
Enums
Indicates whether a value is available or if the current task has been scheduled to receive a wakeup instead.
Functions
Spawns a task and blocks the current thread on its result.
Returns a handle to the current task.
Sleeps for the specified amount of time.
Spawns a task.
Spawns a blocking task.
Spawns a task onto the thread-local executor.
Returns a handle to the current task if called within the context of a task created by block_on
,
spawn
, or Builder::spawn
, otherwise returns None
.
Cooperatively gives up a timeslice to the task scheduler.