v0.18.20: separate read/write pipeline depths

src/io/pipeline.rs

@@ -44,19 +44,19 @@ use std::thread::{self, JoinHandle};
 use crate::error::Error;
 
 /// Default channel depth for callers without a specific reason to
-/// pick another value.
+/// pick another value. Kept conservative (4) — most callers should
-///
+/// use READ_PIPELINE_DEPTH or WRITE_PIPELINE_DEPTH instead.
-/// Empirically tuned for sweep and mux — both want enough slack that
+pub const DEFAULT_PIPELINE_DEPTH: usize = 4;
-/// short consumer stalls don't immediately back up onto the producer,
+
-/// but not so much that a producer outpacing the consumer accumulates
+/// Read pipeline depth. Larger buffer compensates for drive variability
-/// arbitrary buffered work. `16` matches the depth needed for UHD-scale
+/// and NFS sync_file_range stalls; keeps ISO reader thread fed even when
-/// mux where WritebackFile sync_file_range on NFS can stall the consumer;
+/// consumer blocks on write.
-/// sweep uses [`DEFAULT_PIPELINE_DEPTH`] directly, mux should use this
+pub const READ_PIPELINE_DEPTH: usize = 32;
-/// or deeper if ISO read is moved to a separate producer thread. Patch
+
-/// should usually use [`WRITE_THROUGH_DEPTH`] (`1`) instead — write-through
+/// Write pipeline depth. Smaller buffer reduces backpressure risk when
-/// gives clean back-pressure between every read attempt and the matching
+/// sync_file_range blocks; prevents producer from accumulating too much
-/// write, which matters when the consumer is updating the mapfile in lockstep.
+/// work while consumer waits for NFS to drain.
-pub const DEFAULT_PIPELINE_DEPTH: usize = 32;
+pub const WRITE_PIPELINE_DEPTH: usize = 16;
 
 /// Channel depth for write-through pipelines. Each `send` fully
 /// drains before the next can enqueue. Use this when the producer

src/lib.rs

@@ -133,11 +133,14 @@ pub use halt::Halt;
 // consumer and surfaces its `close()` output. Callers implement `Sink`
 // to define per-item behaviour and end-of-stream finalisation.
 //
-// `DEFAULT_PIPELINE_DEPTH` (=4) is the depth sweep + mux use; patch
+// `DEFAULT_PIPELINE_DEPTH` (=4) is for callers without specific needs;
-// uses `WRITE_THROUGH_DEPTH` (=1) so each read fully drains before the
+// most should use READ_PIPELINE_DEPTH or WRITE_PIPELINE_DEPTH instead.
-// next can enqueue. Returning `Flow::Stop` from `apply` ends the
+// Patch uses `WRITE_THROUGH_DEPTH` (=1). Returning `Flow::Stop` from
-// consumer cleanly (still calls `close()`).
+// `apply` ends the consumer cleanly (still calls `close()`).
-pub use io::pipeline::{DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, Sink, WRITE_THROUGH_DEPTH};
+pub use io::pipeline::{
+    DEFAULT_PIPELINE_DEPTH, Flow, Pipeline, READ_PIPELINE_DEPTH, Sink, WRITE_PIPELINE_DEPTH,
+    WRITE_THROUGH_DEPTH,
+};
 
 // ─── Drive events (low-level callbacks) ─────────────────────────────────────
 pub use event::{Event, EventKind};