libfreemkv/docs/prefetched.md

# `sector::prefetched` — design notes

## Why a producer thread

The mux consumer (demux + codec parsing + frame output) is single-threaded
by nature (streams are sequential). The mux producer (read sectors + AACS
decrypt) is also single-threaded per-call but does CPU-heavy work (AES per
6144-byte unit). Running both on the same thread means the disk and decrypt
cores sit idle while the demux runs, and vice versa.

Splitting them across two threads with a bounded channel between lets both
run in parallel — peak throughput becomes `min(producer_rate, consumer_rate)`
instead of `1 / (1/producer + 1/consumer)`.

## Lifecycle

The producer thread is spawned by `PrefetchedSectorSource::new` (which
returns `Err` if the OS refuses the thread spawn). It walks the supplied
extent list in order, reads the configured batch size at each LBA, and
sends the resulting plaintext buffer into a `crossbeam_channel::bounded`
channel of small depth (so the producer stays a couple of batches ahead
without unbounded memory growth).

When the channel sender drops (either because all extents were served or
because the `Halt` token cancelled), the consumer observes `RecvError` on
the next `read_sectors` and treats it as end-of-stream. Errors from the
underlying reader are forwarded verbatim through the channel.

## Read API

`read_sectors` ignores its `lba`/`count` arguments — the producer has
already chosen what to read, in the order the extents dictate. This is
sound for the mux read path, which always walks extents sequentially and
never seeks. For random-access callers (sweep patch retries) this wrapper
is the wrong tool — they should keep reading the underlying source
directly.

## `new` — unit-alignment precondition

Each extent's `sector_count` should be a multiple of `SECTOR_ALIGNMENT`
(3 sectors / one 6144-byte AACS aligned unit). Blu-ray m2ts extents satisfy
this by spec. If an extent has a trailing 1-2 sectors that cannot fill a
complete unit, the producer surfaces `Error::ExtentNotUnitAligned` through
the channel rather than handing the decrypt step a sub-unit chunk it would
silently leave encrypted.

## `into_channels` — zero-copy pipeline mode

The caller (typically `super::super::mux::demux_thread::DemuxThread`) pulls
buffers from `rx`, consumes them, and pushes the empty `Vec<u8>` back
through `recycle_tx` so the producer can re-fill it. The producer-thread
`JoinHandle` stays with the returned `PrefetchedSectorSource` shell; drop
that to join. The shell only holds the join handle and total_sectors for
`capacity_sectors` queries; its `SectorSource` impl becomes invalid after
this call (data has been moved out).

## Test notes

- `drop_undrained_source_joins_cleanly`: regression for dropping a
  `PrefetchedSectorSource` DIRECTLY — the public `new` + documented
  direct-read path, and any error/halt exit before the extents are
  drained — must join the producer cleanly. `Drop::drop` used to `join()`
  while the struct still held `rx` and `recycle_tx` (sibling fields drop
  only AFTER `Drop::drop` returns), so a producer parked in the plain
  blocking `tx.send(Ok(buf))` never saw a disconnect and the dropping
  thread blocked in `join()` forever — a permanent two-thread deadlock
  that cancelling the `Halt` could not escape, because that `send` has no
  timeout and never re-polls the token. 300 sectors at batch=3 is 100
  batches against a forward channel of depth `PREFETCH_CHANNEL_DEPTH` (2),
  so the producer is guaranteed to be blocked in `send` by the time the
  drop runs. Mirrors `byte_prefetcher::drop_endless_prefetcher_joins_cleanly`,
  whose `Drop` already had the correct shape.

- `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.

- `halt_releases_producer`: same property via the halt path — cancel the
  token, then the producer must exit and the shell join must complete. The
  producer parks in a BLOCKING `tx.send` on the forward channel and only
  checks `halt` at the loop top, so `halt.cancel()` cannot interrupt a send
  that is already blocked on a full channel. To keep the test deterministic
  under load, we drain the forward receiver on a background thread: every
  send then makes progress, the producer reaches the loop top, observes
  the cancelled halt, and exits — so the shell join completes promptly
  regardless of scheduling. (Channel-disconnection shutdown is covered
  separately by `into_channels_drop_releases_producer`.)

- `zero_unit_align_rejected`: `unit_align == 0` must be rejected by the
  constructor, not turned into a divide-by-zero panic on the producer
  thread. Before the guard, `new_with_events` returned `Ok` and the
  producer evaluated `remaining % 0`, panicking ("attempt to calculate the
  remainder with a divisor of zero"); `catch_unwind` then reported the
  read as `DemuxThreadPanicked` instead of the `InvalidInput` its sibling
  parameter gets — a panic printed out of a public constructor's own
  thread.

- `direct_reads_past_pool_depth_do_not_deadlock`: more than 3 sequential
  direct `read_sectors` calls must succeed. The recycle pool seeds
  PREFETCH_CHANNEL_DEPTH+1 (3) buffers; before the fix the direct path
  dropped each drained buffer, so the 4th call deadlocked.

- `event_fn_fires_bytes_read_per_batch`: the producer-thread `event_fn`
  must fire a `BytesRead` event for every batch it reads, with a
  monotonically increasing cumulative byte count that reaches the full
  extent size at EOF. This is the contract autorip's mux progress bar +
  soft-stall watchdog depend on: the resume/multipass paths pass an
  `event_fn` so `latest_bytes_read` tracks read-ahead progress and
  `wd_last_frame` is refreshed on each sector read (not only on the slower
  write cadence). Before this guard nothing asserted the callback fired at
  all, so a path that passed `None` (the `resume_remux` regression)
  compiled and ran silently with the bar stuck at write-lagged progress.

- `non_multiple_of_three_extent_errors_on_tail`: an extent whose
  sector_count is not a multiple of 3 must not emit a still-encrypted
  sub-unit tail. The producer delivers the readable full units, then
  surfaces a typed error on the tail instead of a short batch.

- `short_read_does_not_desync_stream`: a short read (inner source returns
  fewer sectors than requested) must advance the extent cursor by the
  sectors actually read, not the requested count — otherwise the bytes
  between the short read and the request size are silently skipped.

- `capacity_sectors_sums_all_extents`: `capacity_sectors` returns the sum
  of all extents' sector_counts, computed once at construction. Grounding:
  doc comment on `total_sectors` — "the sum of each extent's sector_count".

- `capacity_sectors_clamps_on_overflow`: total-sector accumulation must
  clamp at u32::MAX rather than panic (debug overflow) or wrap (release)
  on a hostile extent set whose summed sector_count exceeds u32.
  Grounding: the `new` comment — "Accumulate in u64 then clamp ... a naive
  u32 sum() could panic in debug / wrap in release".

- `producer_walks_extents_in_order_at_correct_lbas`: the producer must
  walk extents in list order and start each extent at its `start_lba`
  (plus running offset within the extent), never reorder or merge them.
  Grounding: lifecycle doc — "walks the supplied extent list in order" and
  `lba = extent.start_lba.saturating_add(offset)`.

- `batch_trimmed_to_whole_units`: a batch larger than one unit must be
  trimmed DOWN to a whole number of 3-sector units before issuing the
  read — never a sub-unit count that decrypt would leave partially
  encrypted. batch=5 → trimmed to 3 (5 - 5%3). Grounding: the unit-trim
  block `sectors -= sectors % SECTOR_ALIGNMENT`.

- `unit_aligned_extent_delivers_all_and_eofs`: an extent whose
  sector_count IS a multiple of 3 must deliver exactly that many sectors
  and then cleanly EOF (no error on the final aligned batch). Grounding:
  the trailing-tail guard only fires for sub-unit leftovers; a unit-aligned
  extent forms full units on its own.

- `reader_error_propagates_with_kind`: the underlying reader's error must
  propagate to the consumer as an error (not Ok(0)/EOF), and its
  ErrorKind must survive the round-trip through the channel. Grounding:
  the producer's `Err(e) => tx.send(Err(e.into()))` arm, and
  `read_sectors`' `Ok(Err(e)) => { self.producer_failed = true;
  Err(Error::from(e)) }`. That arm recovers the producer's TYPED error by
  downcast rather than blanket-wrapping it as `Error::IoError`, so the
  kind survives; the `producer_failed` latch it also sets is what turns
  the channel close that follows into `SourceTerminated` instead of a
  clean EOF.

- `inner_source_quitting_early_is_not_reported_as_end_of_stream`: an inner
  source that answers a mid-extent read with `Ok(0)` has quit early: the
  extent list still has sectors to serve. The producer must say so, not
  simply drop `tx` — a closed channel reads as clean end-of-stream, and
  `DiscStream::fill_extents` then fabricates zeros for every remaining
  sector of the title and reports the pass complete. Same rule as the
  panic sentinel: a truncated title must never be finalized as success.

- `non_sector_multiple_read_rejected`: a read returning a byte count that
  is not a whole number of sectors (n % 2048 != 0) must be rejected —
  never truncated and advanced, which would split a sector and hand
  decrypt a partial unit. Grounding: the `if n % 2048 != 0 { send Err }`
  guard.

- `direct_read_too_small_buffer_errors`: a too-small consumer buffer in
  the direct `read_sectors` path must error (InvalidInput), never
  silently drop the bytes past `buf.len()`. Grounding: the
  `if filled.len() > buf.len()` guard in `read_sectors` ("would silently
  drop filled[buf.len()..], desyncing the stream").

- `too_small_buffer_repeated_does_not_deadlock_pool`: regression for the
  fix-1 deadlock — calling read_sectors with a too-small buffer more times
  than the pool depth (PREFETCH_CHANNEL_DEPTH+1 = 3) must NOT deadlock and
  the pool must remain usable afterwards. Before the fix, each
  too-small-buffer error path returned without recycling the received
  buffer, draining the fixed pool. On the 4th call the producer blocked on
  recycle_rx.recv() while the consumer blocked on rx.recv() — permanent
  deadlock.

- `delivered_bytes_match_source_exactly`: the producer delivers exactly
  the bytes the inner source produced, in order, byte-for-byte.
  PatternSource tags each sector with `(lba & 0xff)`, so the assembled
  stream must match a reconstruction from the extent's LBA range. Guards
  against off-by-one/duplicate/reorder in the offset bookkeeping.

- `empty_extents_eof_immediately`: an empty extent list must EOF
  immediately (capacity 0, first direct read returns Ok(0)) and must not
  deadlock. Grounding: the producer's `while ext_idx < extents.len()` loop
  body never runs, so `tx` drops and the consumer sees RecvError → Ok(0).

- `zero_length_extent_is_skipped`: a zero-length extent in the middle of
  the list must be skipped (remaining == 0 → advance to next extent)
  without emitting a batch and without stalling. Grounding: the
  `if remaining == 0 { ext_idx += 1; continue }` branch.

- `four_sector_extent_errors_on_one_sector_tail`: a 4-sector extent (one
  full unit + a 1-sector tail) must deliver the 3-sector unit and then
  error on the 1-sector remainder — exercising the trim-within-batch path
  (`sectors -= sectors % 3` lands on 3, leaving remaining=1) that then
  hits the sub-unit guard on the next iteration. Distinct control flow
  from the 8-sector case. Grounding: trailing-tail guard plus the
  unit-trim block.

- `many_extents_drain_without_deadlock`: many sequential direct reads
  across MANY extents must all flow through the fixed recycle pool
  without deadlock — a stronger version of the pool-depth regression that
  also crosses extent boundaries (offset reset to 0, ext_idx advance).

- `bad_sector_across_channel_is_not_a_transport_failure`: REGRESSION — an
  ordinary MEDIUM ERROR bad sector that crosses the prefetch channel must
  NOT be classified as a SCSI transport failure. `read_sectors` used to
  re-wrap EVERY channel error as `Error::IoError { source }`, and
  `is_scsi_transport_failure` matches `IoError` (the wedged-USB-bridge
  arm). So a skippable bad sector arrived at `DiscStream::fill_extents`
  looking like a dead bus and aborted the whole pass instead of honouring
  `skip_errors`.

- `transport_failure_across_channel_still_classifies`: OPPOSITE-DIRECTION
  CONTROL — a genuine transport failure (status 0xFF, wedged USB bridge)
  crossing the same channel MUST still classify as a transport failure, so
  `fill_extents` / sweep keep aborting the pass instead of zero-filling
  every read against a dead bus.