auralis_task/lib.rs
1//! auralis-task: Scoped async task runtime with explicit [`TaskScope`]
2//! hierarchy, iterative cancellation, and priority scheduling.
3//!
4//! # Architecture
5//!
6//! - **Global executor** — a [`thread_local!`] singleton with
7//! high- and low-priority queues.
8//! - **`TaskScope`** — owns spawned futures; dropping a scope cancels
9//! all descendant scopes and their tasks **iteratively** (no
10//! recursion), preventing stack overflows in deeply nested UI trees.
11//! - **`set_deferred`** — safe signal mutation from [`Drop`] contexts.
12//! - **Pluggable storage** — [`ScopeStore`] and [`Executor::new_instance`]
13//! enable multi-request isolation for SSR or multi-threaded runtimes.
14//!
15//! # Quick example
16//!
17//! ```
18//! use auralis_task::{TaskScope, spawn_global};
19//!
20//! let scope = TaskScope::new();
21//! scope.spawn(async { /* ... */ });
22//! ```
23//!
24//! # Design decisions
25//!
26//! The crate shares `auralis_signal`'s single-threaded-by-default
27//! philosophy (`Rc` over `Arc`, `RefCell` over `Mutex`). For
28//! multi-threaded use-cases, create an isolated [`Executor`] instance
29//! per thread or per request. See the repository design docs for the
30//! full rationale.
31
32#![forbid(unsafe_code)]
33#![warn(missing_docs, clippy::all, clippy::pedantic)]
34#![allow(clippy::module_name_repetitions)]
35
36mod executor;
37mod scope;
38
39#[cfg(feature = "debug")]
40mod debug;
41
42#[cfg(feature = "debug")]
43pub use debug::dump_task_tree;
44pub use executor::{
45 init_flush_scheduler, init_time_source, remove_panic_hook, reset_executor_for_test,
46 schedule_callback, set_deferred, set_global_time_budget, set_panic_hook, spawn_global,
47 spawn_global_with_priority, with_executor, yield_now, Executor, PanicInfo, ScheduleFlush,
48 TimeSource, YieldNow,
49};
50#[cfg(test)]
51pub use executor::{TestScheduleFlush, TestTimeSource};
52#[cfg(feature = "debug")]
53pub use scope::scope_debug_label;
54pub use scope::{
55 clear_scope_registry, current_scope, find_scope, set_scope_store, with_current_scope,
56 CallbackHandle, ScopeStore, TaskScope,
57};
58
59#[cfg(feature = "ssr-tokio")]
60pub use scope::init_scope_store_tokio;
61
62/// Task priority.
63///
64/// High-priority tasks are dequeued before low-priority ones within a
65/// single flush cycle.
66#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
67pub enum Priority {
68 /// Dequeued first during flush.
69 High,
70 /// Dequeued after all high-priority tasks.
71 Low,
72}