moirai_scheduler/lib.rs
1//! # Work-Stealing Primitives
2//!
3//! Lock-free work-stealing deques and NUMA-topology primitives. These are the
4//! reusable building blocks consumed by the canonical runtime scheduler
5//! (`moirai_executor`'s `ThreadScheduler`); this crate intentionally provides
6//! no scheduler of its own.
7//!
8//! ## Deques
9//!
10//! Three lock-free work-stealing deques, all single-owner / multi-thief:
11//! - [`ChaseLevDeque`] — the canonical Chase-Lev deque: O(1) wait-free local
12//! push/pop for the owner, lock-free steal for thieves, dynamic resizing,
13//! and `bottom`/`top` isolated to separate cache lines to avoid false sharing.
14//! - [`SplitDeque`] — a private owner stack backed by a shared deque, reducing
15//! steal contention when spawn rate greatly exceeds steal rate.
16//!
17//! Correctness is covered by exactly-once concurrency stress tests and bounded
18//! `loom` models of the Chase-Lev transfer and resize-exclusion protocols.
19//!
20//! ## NUMA primitives
21//!
22//! [`numa`] exposes [`AdaptiveBackoff`](numa::AdaptiveBackoff) for
23//! spin/yield/sleep backoff in stealing loops. Hardware topology is answered
24//! by `themis::CpuTopology` directly, not mirrored here (ADR-037).
25
26#![allow(clippy::redundant_closure)]
27#![allow(clippy::collapsible_if)]
28#![allow(clippy::cast_abs_to_unsigned)]
29#![deny(missing_docs)]
30
31pub mod deque;
32pub mod numa;
33
34pub use deque::{
35 ChaseLevDeque, ChaseLevStealer, DeferredAccessGuard, DeferredReclaim, DeferredState,
36 DequeCapacity, DequeCapacityError, DequeReclaimPolicy, DequeReclaimState,
37 SharedEpochAccessGuard, SharedEpochReclaim, SharedEpochState, SplitDeque, StealResult,
38 StolenBatch,
39};