gatling/src/revolver/mod.rs
//! Zero-allocation slot pool for 1-reader / N-worker streaming pipelines.
//!
//! Reachable as [`gatling::revolver`](crate::gatling::revolver) — folded in as a
//! `gatling` submodule (the buffer substrate the streaming engine fans over),
//! alongside `gatling::io` / `gatling::ordered`. The former top-level
//! `chunk_revolver` module name survives as a crate-root re-export alias
//! ([`crate::chunk_revolver`]) so external consumers are unaffected.
//!
//! Moved verbatim into znippy-zoomies from the former standalone `chunk-revolver`
//! crate. One reader thread fills pre-allocated fixed-size slots; N workers borrow
//! each slot as `&[u8]` (zero-copy) via [`get_chunk_slice`](crate::gatling::revolver::get_chunk_slice)
//! and process it.
//!
//! **Two modes.** `revolver.rs` is the original fixed-slot pool: 1 write = 1
//! whole slot, non-blocking `try_get_chunk`, recycled by `return_chunk`.
//! `coalesce.rs` adds the coalescing / reference-counted mode
//! (`ChunkRevolver::with_coalescing`): many variable-width payloads packed
//! into ONE slot, a blocking `ChunkRevolver::claim_slot` for backpressure,
//! and a per-slot reference count so the slot returns to the free list only
//! after the last worker calls `Returner::release_one`. The two are mutually
//! exclusive by construction — arming the coalescing mode drains the ring free
//! lists, so `try_get_chunk` on such a pool can only return `None`.
//!
//! **Status (2026-08):** this is a public, exported primitive with no in-tree
//! *runtime* consumer today — the codec CLIs stream through the `gatling` /
//! `gatling::ordered` engines, and znippy still runs a *fork* of this pool
//! (`znippy-common`'s "Magazine"). It is NOT dead code: it is the CANONICAL
//! slot pool that `.nornir/chunk_revolver-unsorted.md` designates as the
//! survivor of that consolidation. Phase 1 (this crate — the coalescing mode)
//! is DONE; Phase 2 (flip znippy's `slot_packer.rs` onto it and delete the
//! fork) is open, znippy-side. Behaviour is pinned by
//! `tests/chunk_revolver.rs` + `tests/chunk_revolver_coalescing.rs` and timed
//! by `benches/revolver_coalescing.rs`. Do not delete without retiring that
//! plan first.
#![allow(
unsafe_code,
reason = "raw pointer slot pool — safety documented per site"
)]
mod coalesce;
mod revolver;
mod ring;
pub use coalesce::{Filler, PackedSlice, Returner};
pub use revolver::{Chunk, ChunkRevolver, SendPtr, get_chunk_slice};
pub use ring::{HUGE, LARGE, MEDIUM, MINI};