Skip to content

fix(protocols): keep recent blocks cached in PrefetchReader - #282

Merged
BGLuis merged 1 commit into
developfrom
fix/prefetch-multi-block-cache
Nov 21, 2026
Merged

BGLuis merged 1 commit into
developfrom
fix/prefetch-multi-block-cache

Conversation

@BGLuis

@BGLuis BGLuis commented Nov 21, 2026

Copy link
Copy Markdown
Owner

Description

An 8K60 HEVC MP4 streamed over SFTP never played: the first frame took ~6 s and playback stalled right after (sem frame novo ha 500ms, repeated Video catch-up), even though the link sustained ~30 MiB/s.

Root cause. The file is not interleaved: all audio samples sit together near the start (~520 KB) and the video ~178 MB further in, so the demuxer alternates between two distant regions packet by packet. PrefetchReader cached a single block, so every audio↔video hop was:

  • a cache miss for a block read moments before → synchronous 1 MB refetch (~25–30 ms);
  • a drain-and-discard of the video read-ahead in flight (blocksDiscarded climbing).

On the headset this fetched 1194 MiB in 859 fetches to advance ~57 MB of the file (~11 Mbit/s of useful data for a ~96 Mbit/s stream).

Fix (rust/protocols/src/prefetch.rs):

  • Besides the current block, the last MAX_CACHED_BLOCKS - 1 blocks stay in an LRU (MAX_CACHED_BLOCKS = 4). Returning to a cached region neither refetches it nor cancels the read-ahead pending for the region it left.
  • A prefetch drained by a non-sequential miss is kept in the LRU instead of thrown away; if it already covers the requested offset it is used directly.
  • Memory: with the 12 MB playback block size, at most 48 MB resident (was 12 MB) plus the block in flight.
  • blocks_discarded now counts in-flight prefetches a miss had to wait out without them covering the offset; the block itself stays cached. Its doc comment and the module header were updated.

Type of change

  • 🐛 Bug fix (non-breaking change which fixes an issue)
  • ✨ New feature (non-breaking change which adds functionality)
  • 🛠️ Technical refactor / Code improvement
  • 📝 Documentation update
  • 🚀 Performance optimization
  • 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)

Affected layers

  • 🟣 Kotlin (app/) — app shell, UI panels, credentials, history, i18n
  • 🔵 C++ (native/) — OpenXR session, Vulkan/GLES render loop, controller input
  • 🦀 Rust (rust/) — demux, decode, audio, network protocols
  • 🔧 Build / CI / scripts
  • 📚 Docs only

How has this been tested?

  • Unit tests (JVM / cargo test)
  • Native/Vulkan build compiled without errors
  • Physically tested on a device (Quest 3 / Quest 3s)

Host:

  • Two new regression tests in prefetch::tests:
    • alternating_between_two_regions_does_not_refetch_on_every_hop — 300 audio/video hops between two distant regions. Fails on the previous code with 601 fetches for 600 hops, the same pattern seen on the headset.
    • prefetch_drained_by_a_seek_is_reused_when_reading_comes_back — returning to a drained read-ahead block must not refetch it (fails on the previous code: 4 fetches instead of 3).
  • cargo fmt --check, cargo clippy -p protocols -p media-logic --all-targets --all-features -- -D warnings, cargo test -p protocols -p media-logic (148 + 302 tests) all pass.

Quest 3, same file over SFTP (from the session telemetry CSVs):

Before After
Decoded / output fps ~0 (2 frames in 30 s) ~60 steady
Useful network rate ~30 MiB/s fetched, mostly wasted ~12 MiB/s, the stream bitrate
Block fetches 859 in ~30 s 76 in 71 s
Video queue 0 300 (full, ~5 s buffered)

A second, interleaved file (fisheye 190, also SFTP) was played afterwards to check for regressions: ~60 fps, 59 fetches in 55 s, several seeks each recovering in 0.2–1 s.

Not covered: the integration tests against real servers (./scripts/test-network-protocols.sh) were not run.

Checklist:

  • My code follows the project's style guidelines (ktlint, rustfmt, clippy -D warnings).
  • I have performed a self-review of my own code.
  • I have commented my code, particularly in hard-to-understand areas.
  • I have added new tests that prove my fix is effective or that my feature works.
  • The CI checks (Security & Workflows, Rust, C++, Android and Markdown Lint, gated by CI Gate) are passing for this PR.

Follow-up (not in this PR)

After a seek, the decoder's catch-up drops feed state.droppedFps (native/src/vr_player_app_vulkan.cpp), and QualityController (rust/media-logic/src/quality.rs) degrades the render scale (HIGH → MEDIUM, DROPPED_FRAMES) even though rendering is fine. It recovers after 30 healthy samples, but ignoring drops for a short window after a seek would avoid the false degrade.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DKhrqRn7bTFHuxW5XFTqvh

A non-interleaved MP4 stores all audio samples together and the video far
from them, so the demuxer alternates between two distant regions packet by
packet. With a single cached block each hop was a synchronous 1MB refetch of
a block read moments before, and it also threw away the video read-ahead in
flight. On an 8K60 SFTP file this fetched ~1.2GB to advance ~57MB (601
fetches per 600 hops in the new test) and playback never got past the first
frames.

PrefetchReader now keeps the last MAX_CACHED_BLOCKS (4) blocks in an LRU:
returning to a cached region neither refetches nor cancels the pending
read-ahead, and a prefetch drained by a seek is kept instead of discarded.
With 12MB playback blocks this costs at most 48MB resident.

Verified on Quest 3: the same file now plays at ~60 fps (76 block fetches
in 71 s, previously 859 in ~30 s); a second, interleaved file is unaffected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DKhrqRn7bTFHuxW5XFTqvh
@BGLuis
BGLuis merged commit 4e6a857 into develop Nov 21, 2026
6 of 7 checks passed
@BGLuis
BGLuis deleted the fix/prefetch-multi-block-cache branch November 21, 2026 02:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant