indicatrix_dispatch/lib.rs
1//! Sample-range and work-item scheduling for indicatrix render lanes.
2//!
3//! This crate is the scheduler a render coordinator runs: several backends ("lanes":
4//! a joined remote worker, the coordinator's own CPU/GPU, anything implementing
5//! [`WorkerLane`]) contribute disjoint absolute sample ranges to ONE image, and their
6//! per-chunk radiance sums are merged into one buffer with an exact sample count.
7//!
8//! It holds no networking, no GUI and no GPU code. It depends only on the protocol
9//! crate (for [`indicatrix_net::SceneState`]) and `glam`, so it can be linked into the
10//! worker binary as well as the desktop app.
11//!
12//! # Why merging by plain addition is sound
13//!
14//! A path sample is identified by `(global_pixel_index, absolute_sample_index)` and
15//! nothing else, on every backend. Any set of backends tracing **disjoint** sample
16//! ranges of the **same scene at the same resolution** therefore merges by per-pixel
17//! addition, divided by the total count. Disjointness is the whole correctness
18//! guarantee, and [`SampleCursor`] provides it by construction.
19//!
20//! # Contents
21//!
22//! - [`SampleCursor`]: the atomic claim point handing out disjoint sample ranges.
23//! - [`WorkerLane`], [`ChunkResult`], [`SampleRange`]: what a lane is and returns.
24//! - [`RateModel`], [`ChunkPolicy`]: per-lane throughput calibration and chunk sizing.
25//! - [`LanePool`]: N lanes against one cursor for one image epoch, with failure
26//! reclaim, backoff, retirement, cancellation and events.
27//! - [`Merger`]: the deterministic, chunk-start-ordered merge of chunk sums.
28//! - [`ItemQueue`]: whole-item distribution (batches) over N lanes.
29//! - [`CancelToken`]: a cloneable cancellation flag.
30
31mod cancel;
32mod item_queue;
33mod lane;
34mod merge;
35mod pool;
36mod rate;
37mod sample_cursor;
38
39pub use cancel::CancelToken;
40pub use item_queue::{FailOutcome, ItemQueue, ItemTicket, QueueCounts};
41pub use lane::{ChunkResult, SampleRange, WorkerLane};
42pub use merge::{MergeError, Merger};
43pub use pool::{LanePool, MergerMismatch, PoolConfig, PoolEvent, PoolOutcome, PoolStatus};
44pub use rate::{ChunkPolicy, DEFAULT_MAX_CHUNK_SAMPLES, RateModel, marginal_rate};
45pub use sample_cursor::SampleCursor;