async_std/task/
mod.rs

1//! Types and traits for working with asynchronous tasks.
2//!
3//! This module is similar to [`std::thread`], except it uses asynchronous tasks in place of
4//! threads.
5//!
6//! [`std::thread`]: https://doc.rust-lang.org/std/thread
7//!
8//! ## The task model
9//!
10//! An executing asynchronous Rust program consists of a collection of native OS threads, on top of
11//! which multiple stackless coroutines are multiplexed. We refer to these as "tasks".  Tasks can
12//! be named, and provide some built-in support for synchronization.
13//!
14//! Communication between tasks can be done through channels, Rust's message-passing types, along
15//! with [other forms of tasks synchronization](../sync/index.html) and shared-memory data
16//! structures. In particular, types that are guaranteed to be threadsafe are easily shared between
17//! tasks using the atomically-reference-counted container, [`Arc`].
18//!
19//! Fatal logic errors in Rust cause *thread panic*, during which a thread will unwind the stack,
20//! running destructors and freeing owned resources. If a panic occurs inside a task, there is no
21//! meaningful way of recovering, so the panic will propagate through any thread boundaries all the
22//! way to the root task. This is also known as a "panic = abort" model.
23//!
24//! ## Spawning a task
25//!
26//! A new task can be spawned using the [`task::spawn`][`spawn`] function:
27//!
28//! ```no_run
29//! use async_std::task;
30//!
31//! task::spawn(async {
32//!     // some work here
33//! });
34//! ```
35//!
36//! In this example, the spawned task is "detached" from the current task. This means that it can
37//! outlive its parent (the task that spawned it), unless this parent is the root task.
38//!
39//! The root task can also wait on the completion of the child task; a call to [`spawn`] produces a
40//! [`JoinHandle`], which implements `Future` and can be `await`ed:
41//!
42//! ```
43//! use async_std::task;
44//!
45//! # async_std::task::block_on(async {
46//! #
47//! let child = task::spawn(async {
48//!     // some work here
49//! });
50//! // some work here
51//! let res = child.await;
52//! #
53//! # })
54//! ```
55//!
56//! The `await` operator returns the final value produced by the child task.
57//!
58//! ## Task-local storage
59//!
60//! This module also provides an implementation of task-local storage for Rust
61//! programs. Task-local storage is a method of storing data into a global
62//! variable that each task in the program will have its own copy of.
63//! Tasks do not share this data, so accesses do not need to be synchronized.
64//!
65//! A task-local key owns the value it contains and will destroy the value when the
66//! task exits. It is created with the [`task_local!`] macro and can contain any
67//! value that is `'static` (no borrowed pointers). It provides an accessor function,
68//! [`with`], that yields a shared reference to the value to the specified
69//! closure. Task-local keys allow only shared access to values, as there would be no
70//! way to guarantee uniqueness if mutable borrows were allowed.
71//!
72//! [`Arc`]: ../sync/struct.Arc.html
73//! [`spawn`]: fn.spawn.html
74//! [`JoinHandle`]: struct.JoinHandle.html
75//! [`join`]: struct.JoinHandle.html#method.join
76//! [`panic!`]: https://doc.rust-lang.org/std/macro.panic.html
77//! [`Task`]: struct.Task.html
78//! [`task_local!`]: ../macro.task_local.html
79//! [`with`]: struct.LocalKey.html#method.with
80
81cfg_std! {
82    #[doc(inline)]
83    pub use std::task::{Context, Poll, Waker};
84
85    pub use ready::ready;
86    pub use yield_now::yield_now;
87    mod ready;
88    mod yield_now;
89}
90
91cfg_default! {
92    pub use block_on::block_on;
93    pub use sleep::sleep;
94    pub use tokio::task::*;
95
96    mod block_on;
97    mod sleep;
98
99}
async_std/task/mod.rs

async_std/task/
mod.rs
