strided_exec/
lib.rs

1//! Splittable CPU placement for the strided stack.
2//!
3//! `strided-exec` is the single place that starts tasks. Kernels never see a
4//! scheduler type: they take an [`Exec`], a token for `budget` slots of a
5//! [`Pool`], and split it with [`Exec::fork`], [`Exec::for_ranges`],
6//! [`Exec::broadcast`] or [`Exec::external`].
7//!
8//! * A [`Pool`] is built once by its owner with [`Pool::builder`].
9//! * [`Exec::new`] mints a token from a pool; [`Exec::serial`] needs none.
10//! * A token is not `Clone`/`Copy`; entries consume it; splits conserve slots.
11//! * Serial, budget-one and one-task entries run inline and never reach any
12//!   scheduler, so the process-global Rayon pool is never started implicitly.
13//!
14//! # Features
15//!
16//! * `parallel` (default): run on a private pool. Without it the same types
17//!   exist, every pool has width 1 and every entry runs inline.
18//! * `ledger`: test support, see the `ledger` module (compiled only with this feature).
19//!
20//! # Examples
21//!
22//! ```
23//! use std::sync::atomic::{AtomicUsize, Ordering};
24//! use strided_exec::{Exec, Pool};
25//!
26//! let pool = Pool::builder().threads(4).build()?;
27//! let mut exec = Exec::new(&pool, 4)?;
28//!
29//! // Phase 1: data-parallel loop.
30//! let total = AtomicUsize::new(0);
31//! exec.reborrow().for_ranges(1000, 64.try_into().unwrap(), |r| {
32//!     total.fetch_add(r.len(), Ordering::Relaxed);
33//! });
34//! assert_eq!(total.into_inner(), 1000);
35//!
36//! // Phase 2: two independent parts, each with its share of the slots.
37//! exec.fork(2, |_i, child| {
38//!     assert!(child.budget().get() <= 2);
39//! });
40//! # Ok::<(), strided_exec::Error>(())
41//! ```
42
43mod error;
44mod exec;
45#[cfg(feature = "ledger")]
46pub mod ledger;
47mod pool;
48mod sched;
49mod split;
50mod track;
51
52pub use error::{Error, Refused};
53pub use exec::Exec;
54pub use pool::{Pool, PoolBuilder};
55
56#[cfg(test)]
57mod tests;
strided_exec/lib.rs

strided_exec/
lib.rs
