gatling/
lib.rs

1//! gatling — the constellation's **ONE** shared no-barrier worker-pool engine.
2//!
3//! Extracted into its own leaf crate so every codec (`lgz`, `ljar`, `lbzip2`,
4//! `lzip-parallel`, …) *and* the `znippy-zoomies` root crate can depend on the
5//! same engine without a dependency cycle: this crate depends on no codec, so
6//! there is no cycle and no reason for any codec to hand-roll a private thread
7//! pool (the sin the rayon-free law forbids).
8//!
9//! - [`gatling`]: generic no-barrier worker-pool engine (split → N decode →
10//!   in-order collect → sink), parameterised by a [`gatling::Codec`] + a
11//!   [`gatling::Sink`]. Its [`gatling::io`] submodule is the **async** sibling —
12//!   a no-barrier, bounded, ordered async task pool for I/O-bound fan-out; its
13//!   [`gatling::ordered`] submodule is the item-oriented ordered-sink variant.
14//! - [`gatling_forkjoin`]: the fork-join gatling — `gatling_for_each` /
15//!   `gatling_for_each_balanced` / `gatling_run`: all `n` units are known now,
16//!   so N workers drain a shared atomic cursor at full tilt (no reader thread).
17//! - [`background`]: the depth-1 gatling — a single background [`background::Job`]
18//!   for producer/consumer *overlap* (double-buffering a spill/sort/write stage
19//!   behind the next decode pass). The sanctioned home for the one background
20//!   `thread::spawn` non-engine crates would otherwise hand-roll.
21//! - [`gatling::revolver`]: zero-allocation slot pool for 1-reader / N-worker
22//!   streaming — the buffer substrate the streaming engine fans over. Folded in
23//!   as a `gatling` submodule (was the top-level `chunk_revolver` module); still
24//!   re-exported crate-root as [`chunk_revolver`] for API compatibility.
25//!
26//! `znippy-zoomies` re-exports these modules unchanged (`pub use gatling::…`) so
27//! external consumers' `znippy_zoomies::gatling` / `::gatling_forkjoin` /
28//! `::chunk_revolver` paths keep working.
29
30/// **Introspection / emit marker** — record one functional-status row for the
31/// nornir test matrix. Wraps `nornir_testmatrix::functional_status` behind the
32/// `testmatrix` feature (a compiled-out `#[inline]` no-op otherwise, with no
33/// nornir dep in the default build). `component` is the reporting surface (e.g.
34/// `"gatling_forkjoin"`), `check` what it verified, `ok` the verdict, `detail` a
35/// short human note. The gatling engines call this so `nornir test --features
36/// testmatrix` SEES each gatling run.
37#[inline]
38pub fn functional_status(component: &str, check: &str, ok: bool, detail: &str) {
39    #[cfg(feature = "testmatrix")]
40    nornir_testmatrix::functional_status(component, check, ok, detail);
41    #[cfg(not(feature = "testmatrix"))]
42    {
43        let _ = (component, check, ok, detail);
44    }
45}
46
47pub mod background;
48pub mod gatling;
49pub mod gatling_forkjoin;
50
51/// Backwards-compatible alias for the slot pool, now folded in as
52/// [`gatling::revolver`]. Preserves the historical `gatling::chunk_revolver`
53/// (and, through the znippy-zoomies re-export, `znippy_zoomies::chunk_revolver`)
54/// path for external consumers.
55pub use crate::gatling::revolver as chunk_revolver;
56
57/// Parallel-writer gatling — the shared extract/decode/**write** fan-out that
58/// removes the single ordered writer from the critical path (independent files,
59/// or independent regions of one pre-sized stream). Unix-only: it uses
60/// positional `pread`/`pwrite` (`std::os::unix::fs::FileExt`) so N workers read
61/// and write disjoint regions concurrently with no shared file offset.
62#[cfg(unix)]
63pub mod parwrite;
gatling/lib.rs

gatling/
lib.rs
