arty_executor 0.5.0

Single-threaded async task executor for the Arty runtime.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

// TODO(doc-coverage): remove once `missing_docs` is promoted to [workspace.lints.rust].
#![deny(missing_docs)]
#![cfg_attr(coverage_nightly, feature(coverage_attribute))]

//! Async task executor for the Arty Runtime.
//!
//! `arty_executor` is an internal implementation detail of the [`arty`](https://docs.rs/arty)
//! crate. It is responsible for every stage of task execution, including registration, polling,
//! wake processing, cancellation, completion, telemetry, and panic handling. Applications should
//! use `arty` instead of depending on this crate directly.
//!
//! The purpose of the executor is to ensure that async tasks registered with the executor make
//! progress, quickly and efficiently reacting to `await` statements that complete.
//!
//! The executor is the internal building block through which `arty` implements task execution.
//! Application code interacts with `arty`'s own task and join APIs and has no direct interaction
//! with this crate.
//!
//! # Design tenets
//!
//! The executor is single-threaded. If you want to execute tasks on multiple threads, you need to
//! run multiple executors on different threads. The [`remote`] module provides pooled channels for
//! the common runtime-integration scenario of returning task results to a different thread.
//!
//! Tasks cannot be taken out of the executor - the only way for them to end is to either end
//! naturally (with the future returning `Poll::Ready`) or for the executor to be shut down. Not
//! only is there no "remove" function but similarly, there is no "cancel" function - once a task
//! has started executing, the only thing that can terminate it is the task itself, by completing.
//!
//! In a steady state, the executor is allocation-free, as all memory used by the executor is
//! reused for new tasks when old ones complete.
//!
//! Cloned task wakers may outlive their tasks. After completion or cancellation, an escaped waker
//! remains callable but becomes an inert no-op and cannot delay executor shutdown.
//!
//! Join handles may outlive the executor and report shutdown cancellation through [`JoinError`].
//! A panic in a directly registered executor task remains fail-fast.

mod builder;
mod constants;
mod cycle_outcome;
mod executor;
mod executor_core;
mod join_handle;
mod panic;
mod ptr_hash;
pub mod remote;
mod task;
mod task_options;
mod task_ref;
mod task_set;
mod telemetry;
mod wake;

pub use builder::*;
pub(crate) use constants::*;
pub use cycle_outcome::*;
pub use executor::*;
pub(crate) use executor_core::*;
pub use join_handle::*;
pub use panic::*;
pub(crate) use ptr_hash::*;
pub(crate) use task::*;
pub use task_options::*;
pub(crate) use task_ref::*;
pub use task_set::*;
pub(crate) use wake::*;

#[cfg(test)]
#[cfg_attr(coverage_nightly, coverage(off))]
mod testing;

#[cfg(all(debug_assertions, test))]
mod wake_diagnostic;
#[cfg(all(debug_assertions, test))]
pub(crate) use wake_diagnostic::*;

#[cfg(test)]
#[cfg_attr(coverage_nightly, coverage(off))]
mod task_mock;
#[cfg(test)]
pub(crate) use task_mock::*;