Expand description
Async task executor for the Arty Runtime.
arty_executor is an internal implementation detail of the 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.
Modules§
- remote
- Pooled cross-thread task result delivery.
Structs§
- Executor
- The async task executor for a single thread.
- Executor
Builder - Builds an instance of
Executor. - Join
Error - A task failed to return its result.
- Join
Handle - A handle that can be used to await the completion of a task and to receive its result
R. - Task
Options - Lifecycle metadata for a task registered with
TaskSet. - TaskSet
- Represents the set of tasks currently registered with an executor and allows new tasks to be registered.
Enums§
- Cycle
Outcome - The outcome of executing one processing cycle of the async task executor.
- Task
Placement - Describes how the submitter selected this executor for a task.
Functions§
- discard_
task_ panic_ payload - Disposes a captured task panic without allowing its destructor to start another unwind.
Type Aliases§
- Task
Panic Payload - A panic captured while executing or disposing an executor task.