v0.17.10: bounded-cache writeback pipeline for big sequential writes

Pass 1 sweep speed on a healthy disc previously dipped from ~15 MB/s
to ~1 MB/s every ~30 s on a host with default Linux dirty-page
settings. Empirical cause: the kernel's vm.dirty_ratio (~20% of RAM)
lets hundreds of MB of dirty pages accumulate, then bursts a flush at
99% disk utilisation that blocks app writes for ~1 s. Confirmed on
the BU40N test bed — dirty pages grew 112 → 563 MB between bursts;
lowering vm.dirty_bytes to 64 MB at the host sysctl level eliminated
the dips. Shipping the equivalent inside libfreemkv so users do not
need to tune the host kernel.

- New crate::io::Writer: drop-in File wrapper (impl Write + Seek).
  Wraps a per-platform WritebackPipeline that on Linux schedules
  sync_file_range(WRITE) + lagging sync_file_range(WAIT_AFTER) +
  posix_fadvise(DONTNEED) in 32 MB chunks, bounding dirty cache at
  ~64 MB. macOS and Windows ship a no-op stub.
- Disc::sweep wraps its output File in Writer. Loop body unchanged.
- Module is purpose-built so any large sequential output (patch,
  mux) can adopt the same wrapper as a one-line change later.

src/io/writeback/linux.rs

@@ -0,0 +1,95 @@
+//! Linux writeback pipeline using `sync_file_range` + `posix_fadvise`.
+//!
+//! Pathology this fixes: the kernel's default `vm.dirty_ratio` (~20 %
+//! of RAM) lets dirty pages accumulate to hundreds of MB during a
+//! big sequential write, then bursts a flush at 99 % disk utilisation.
+//! While the burst runs, app writes block on the writeback queue —
+//! observed empirically as instantaneous speed dropping from ~15 MB/s
+//! to ~1 MB/s every ~30 s during a Pass 1 sweep.
+//!
+//! Strategy: every `chunk_bytes` of new sequential output, kick async
+//! writeback (`SYNC_FILE_RANGE_WRITE`) on the just-completed chunk and
+//! finalise the *previous* chunk via `WAIT_AFTER` + `posix_fadvise
+//! (DONTNEED)`. By the time we finalise, that previous chunk has had
+//! a full chunk's worth of work to flush — the wait is near-instant.
+//! Dirty cache stays bounded at ~2 × `chunk_bytes` and writes drain
+//! continuously instead of in bursts.
+
+use std::fs::File;
+use std::os::unix::io::{AsRawFd, RawFd};
+
+pub(crate) struct WritebackPipeline {
+    fd: RawFd,
+    chunk_bytes: u64,
+    last_flush_pos: u64,
+    pending: Option<(u64, u64)>,
+}
+
+impl WritebackPipeline {
+    pub(crate) fn new(file: &File, start_pos: u64, chunk_bytes: u64) -> Self {
+        Self {
+            fd: file.as_raw_fd(),
+            chunk_bytes,
+            last_flush_pos: start_pos,
+            pending: None,
+        }
+    }
+
+    /// Caller advanced the file position to `pos`. If a chunk boundary
+    /// was crossed, kick async writeback for the just-completed chunk
+    /// and finalise the previous one.
+    pub(crate) fn note_progress(&mut self, pos: u64) {
+        if pos < self.last_flush_pos.saturating_add(self.chunk_bytes) {
+            return;
+        }
+        unsafe {
+            let chunk_off = self.last_flush_pos as i64;
+            let chunk_len = (pos - self.last_flush_pos) as i64;
+            libc::sync_file_range(self.fd, chunk_off, chunk_len, libc::SYNC_FILE_RANGE_WRITE);
+            if let Some((prev_off, prev_len)) = self.pending.take() {
+                libc::sync_file_range(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::SYNC_FILE_RANGE_WAIT_AFTER,
+                );
+                libc::posix_fadvise(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::POSIX_FADV_DONTNEED,
+                );
+            }
+            self.pending = Some((chunk_off as u64, chunk_len as u64));
+        }
+        self.last_flush_pos = pos;
+    }
+
+    /// Caller is about to seek away from the current write region.
+    /// Drain any in-flight chunk and reset tracking.
+    pub(crate) fn handle_seek(&mut self, new_pos: u64) {
+        self.finalize();
+        self.last_flush_pos = new_pos;
+    }
+
+    /// Drain any in-flight chunk. Idempotent. Call before `sync_all()`
+    /// or when discarding the pipeline.
+    pub(crate) fn finalize(&mut self) {
+        if let Some((prev_off, prev_len)) = self.pending.take() {
+            unsafe {
+                libc::sync_file_range(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::SYNC_FILE_RANGE_WAIT_AFTER,
+                );
+                libc::posix_fadvise(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::POSIX_FADV_DONTNEED,
+                );
+            }
+        }
+    }
+}

src/io/writeback/noop.rs

@@ -0,0 +1,18 @@
+//! No-op writeback pipeline for non-Linux targets. macOS and Windows
+//! page cache policies have not been shown to exhibit the Linux
+//! accumulate-then-burst flush pathology for our access pattern.
+//! If that changes, replace this stub with a real implementation
+//! (e.g. `F_NOCACHE` on macOS, `FILE_FLAG_WRITE_THROUGH` on Windows).
+
+use std::fs::File;
+
+pub(crate) struct WritebackPipeline;
+
+impl WritebackPipeline {
+    pub(crate) fn new(_file: &File, _start_pos: u64, _chunk_bytes: u64) -> Self {
+        Self
+    }
+    pub(crate) fn note_progress(&mut self, _pos: u64) {}
+    pub(crate) fn handle_seek(&mut self, _new_pos: u64) {}
+    pub(crate) fn finalize(&mut self) {}
+}