libfreemkv/docs/byte-prefetcher.md

# `byte_prefetcher` — design notes and test rationale

`BytePrefetcher` (`src/io/byte_prefetcher.rs`) is the `std::io::Read`
analogue of `crate::sector::PrefetchedSectorSource`. It spawns a
producer thread that fills a bounded pool of `Vec<u8>` chunks from the
underlying reader and ships them through a channel; the consumer pulls
filled chunks, uses them, and sends the empty `Vec<u8>` back through a
recycle channel so the producer can re-fill in place. Result: zero
allocations and zero cross-thread frees in the steady-state hot loop.

This is the byte-stream half of the freemkv mux highway —
`BytePrefetcher` feeds `crate::mux::demux_thread::DemuxThread` for
`m2ts://` (the only in-tree caller today, via `crate::mux::resolve`),
and works for any stream whose source is an `io::Read` rather than a
`SectorSource`.

## `PrefetchShell`

Drop blocks the calling thread until the producer exits. To guarantee
a prompt exit, drop the forward receiver and the recycle sender first
so the producer observes channel disconnection (or cancel the `Halt`
passed to `BytePrefetcher::new`, which the producer polls at
`POLL_INTERVAL` granularity even while parked on a channel op).

## Test coverage rationale

- **`recycle_depth_is_forward_depth_plus_one`** — `RECYCLE_DEPTH` must
  be one MORE than `FORWARD_DEPTH` per its own doc comment: the
  producer needs at least one buffer to fill while the consumer holds
  the other `FORWARD_DEPTH`-worth in flight. A `+` -> `*`/`-` mutation
  on `FORWARD_DEPTH + 1` would under-size the recycle channel (e.g.
  `FORWARD_DEPTH * 1 == FORWARD_DEPTH`, one short), which starves the
  producer of a spare buffer.

- **`into_channels_drop_releases_producer`** — the CRITICAL
  regression: after `into_channels`, dropping the returned forward
  receiver + recycle sender must let the producer observe
  disconnection and exit, so dropping the `PrefetchShell` (which
  joins the producer) returns promptly. With the old clone+forget the
  leaked endpoints kept the producer blocked and this join hung
  forever.

- **`delivers_all_bytes_in_order_across_chunks`** — CORE CONTRACT: the
  prefetcher must deliver every source byte, in order, exactly once —
  never silently truncate or duplicate. Source is 5000 bytes; chunk
  size 1024 forces multiple chunks (4 full + 1 short of 904). The
  reassembled stream must equal the source. Mutation: replacing
  `buf.truncate(n)` with a no-op would over-report bytes on the final
  short read and this fails.

- **`short_read_truncates_to_actual_length`** — a reader that returns
  fewer bytes than requested per call must NOT leave stale tail bytes
  in the delivered chunk. Cursor over 10 bytes with a 4096 chunk
  yields a single 10-byte chunk; the consumer must see exactly 10
  bytes, not 4096. Grounds `buf.truncate(n)`. Mutation: delete the
  truncate and the chunk would carry 4086 zero bytes of padding,
  failing the length assert.

- **`empty_source_yields_clean_eof_no_batches`** — EOF semantics: an
  empty source (Cursor over `[]`) yields `read() == Ok(0)` on the
  first call, which the producer treats as EOF and returns, dropping
  tx. The consumer sees RecvError (zero batches), NOT an Err batch and
  NOT a zero-length Ok batch. Grounds the `Ok(0) => return` arm.
  Mutation: changing `Ok(0) => return` to `Ok(0) => continue` would
  spin forever (test times out).

- **`read_error_is_propagated_as_err_batch`** — a reader that fails
  mid-stream must surface the `io::Error` as an `Err` batch on the
  forward channel, not swallow it. We deliver one good chunk then an
  error. The consumer must see the good bytes followed by the error.
  Mutation: changing `let _ = tx.send(Err(e)); return;` to a plain
  `return` would drop the error silently and this fails.

- **`read_panic_surfaces_as_err_batch_not_clean_eof`** — PANIC
  propagation: a reader that PANICS mid-stream must NOT be read as a
  clean EOF at the demux boundary. The producer's `catch_unwind` sends
  an explicit `Err` sentinel before the thread unwinds, so the
  consumer sees the good bytes followed by an error batch — never a
  silent truncation. Without the `catch_unwind` the panic would just
  drop `tx`, the consumer would see RecvError (== clean EOF) and the
  partial output would be finalized as if complete.

- **`recycled_buffer_carries_no_stale_tail`** — recycle-buffer reuse
  must NOT leak stale bytes between chunks of different lengths. After
  a full chunk, a short read reuses the same recycled buffer; the
  regrow-then-truncate sequence must yield only fresh bytes. Verified
  by reassembling the full stream. Source: 8 bytes of 0xAA + 3 bytes
  of 0xBB, with chunk_bytes=8 → chunk0 = 8×0xAA, chunk1 = 3×0xBB.

- **`exact_multiple_length_no_trailing_empty_batch`** — exact-multiple
  boundary: when the source length is an exact multiple of
  chunk_bytes, the final non-empty chunk is followed by an `Ok(0)` EOF
  read, NOT a spurious empty Ok batch. 12 bytes with chunk_bytes=4 →
  three 4-byte chunks then clean EOF. Total bytes must equal 12 and no
  zero-length batch may appear.

- **`drop_finite_prefetcher_joins_cleanly`** — dropping the
  `BytePrefetcher` directly (without `into_channels`) must join the
  producer cleanly when the source is finite. The producer reaches
  EOF, drops tx, and exits; Drop's join returns. Grounds the
  `BytePrefetcher` `Drop` impl. Mutation: removing the `Ok(0) =>
  return` EOF exit would hang this join.

- **`drop_endless_prefetcher_joins_cleanly`** — regression: dropping a
  `BytePrefetcher` directly (without `into_channels`) with an ENDLESS
  source must not deadlock. Before the fix, `Drop` joined the producer
  while `rx`/`recycle_tx` were still alive (sibling field drop order),
  so the producer filled the depth-2 forward channel and then spun in
  `send_timeout` forever (rx never drained, halt=None). The fix drops
  `rx`+`recycle_tx` BEFORE the join so the producer sees
  `SendTimeoutError::Disconnected` and exits.