arty_executor/lib.rs
1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4// TODO(doc-coverage): remove once `missing_docs` is promoted to [workspace.lints.rust].
5#![deny(missing_docs)]
6#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
7
8//! Single-threaded async task executor for the Arty Runtime.
9//!
10//! `arty_executor` is an internal part of the [`arty`](https://docs.rs/arty) crate.
11//! It registers, polls, wakes, cancels, and completes tasks. It also reports telemetry
12//! and contains task panics. Applications use `arty` instead of this crate.
13//!
14//! `arty` uses this crate to run async tasks. Application code uses the task and join
15//! APIs from `arty`.
16//!
17//! # Design
18//!
19//! The executor runs on one thread. Run one executor on each thread that needs to execute
20//! tasks. Only one executor can be alive on a thread. You can create a replacement after
21//! you drop the previous executor. A runtime integration supplies a [`TaskCompletion`]
22//! target when it registers a task.
23//!
24//! A task ends when its future returns `Poll::Ready`, when it panics, or when
25//! executor shutdown cancels it. The executor does not provide methods to
26//! remove or cancel one task.
27//!
28//! During steady operation, the executor reuses task storage and does not allocate.
29//!
30//! A cloned task waker can outlive its task. After task completion or cancellation,
31//! the waker does nothing and cannot delay executor shutdown.
32//!
33//! The executor contains task panics. Use
34//! [`ExecutorBuilder::panic_policy`](crate::ExecutorBuilder::panic_policy) to select
35//! whether a task panic starts executor shutdown.
36
37mod builder;
38mod cycle_outcome;
39mod executor;
40mod executor_context;
41mod executor_shared;
42mod panic;
43mod panic_policy;
44mod shutdown;
45mod task;
46mod task_handle;
47mod task_list;
48mod task_options;
49mod task_set;
50mod telemetry;
51mod wake;
52
53pub use builder::*;
54pub use cycle_outcome::*;
55pub use executor::*;
56pub(crate) use executor_shared::*;
57pub use panic::*;
58pub use panic_policy::*;
59pub use shutdown::*;
60pub use task::TaskCompletion;
61pub(crate) use task::*;
62pub(crate) use task_handle::*;
63pub(crate) use task_list::*;
64pub use task_options::*;
65pub use task_set::*;
66pub(crate) use wake::*;