Forward-buffer window: 150-segment ceiling silently caps an "unbounded pre-buffer" host option (#102 follow-up)

[fxndxs]

What should the engine do?

Summary

LoadOptions.forwardBufferSegments (#102) made the loopback session's forward window configurable, but HLSVideoEngine.clampedForwardWindow caps it at 150 segments (~10 min at 4 s). A host that offers an explicit "buffer without limit" setting cannot honor it: any request above 150 clamps down, so a user who deliberately opted into pre-buffering the whole source for a flaky network (WAN/VPN streaming, commuting, trains/tunnels) still stalls once the connection drops for longer than ~10 minutes of content.

Proposal

Raise the ceiling from 150 to 2700 segments (~3 h at 4 s) — a pure sanity bound against accidental values that still covers a whole feature film. Hosts can then pass Int.max to mean "buffer the entire source". Floor (4) and nil default (10) stay unchanged, and 150 still passes through unchanged, so sessions that don't opt in are unaffected.

The cost profile stays the host's informed choice, as designed in #102: segments are disk-backed (mmap served, ~10 MB per 4K-HEVC segment — a fully cached 2 h film can occupy ~18 GB), and the producer front-loads the demux work. SegmentCache and HLSSegmentProducer take the window as plain arithmetic bounds (no fixed-size structures), so no other code change is needed; the backpressure/wedge machinery is untouched because the producer still paces against AVPlayer's fetch target plus the window.

If you'd rather keep 150 as the default ceiling, an alternative shape would be an explicit opt-in (e.g. forwardBufferSegments: .unbounded) — happy to rework the patch.

Patch

forward-window-ceiling.patch

Attached: git am-able patch against 5.20.4 (1abe7fa):

• HLSVideoEngine.clampedForwardWindow: ceiling 150 → 2700, doc comment explains the whole-film rationale and disk math.
• LoadOptions.forwardBufferSegments doc comment updated to match.
• ForwardBufferWindowTests: ceiling tests updated (900/2700 pass through, 2701/Int.max clamp to 2700); floor and nil-default tests unchanged.

Motivating media or use case

Raise the clampedForwardWindow ceiling (currently 150 segments ≈ 10 min at 4 s) so a host's explicit "buffer without limit" option can actually pre-buffer a whole film — e.g. to 2700 segments (~3 h), with Int.max meaning "buffer the entire source". Floor (4) and the nil default (10) stay unchanged, and 150 still passes through, so sessions that don't opt in are unaffected.

Area

Performance

Host app / integration context

No response

Would you be willing to open a PR?

Maybe, with guidance

[superuser404notfound]

Thanks for the analysis and the ready patch. The ceiling raise is the right direction, but the patch's premise that no other change is needed does not hold, so the merged version bounds the prefetch in bytes rather than segments. PR: #212.

Why the constant alone is unsafe. SegmentCache.pruneOutsideWindow never evicts the hard window (see its doc comment: "the window itself is never evicted even when it alone exceeds the budget"). The retention budget, min(2 GiB, a quarter of the tmp volume's free space) from HLSVideoEngine.vodRetentionBudgetBytes, therefore bounds only the entries outside the window. That is correct while the window fits under the budget by construction, which is exactly why 150 was the ceiling: 150 x ~10 MB ~ 1.5 GB sits below the 2 GiB cap. With a whole-film window the window becomes the footprint and the budget is unreachable, so your own ~18 GB estimate lands on the volume with nothing left to clamp it. SegmentCache.store logs a failed write and moves on, which surfaces as a missing segment, an AVPlayer miss and a stall. That is the failure the option exists to prevent, with disk instead of the network as the cause.

Simply making the window evictable does not work either: the producer would write segment N + window and the cache would immediately drop it, which is why the producer's race-ahead and the cache's forward window are coupled and the window is exempt in the first place.

What #212 does instead.

1. Ceiling 150 -> 2700 as you proposed, as a sanity bound only, with Int.max meaning the whole source. Floor 4 and the nil default 10 are unchanged, 150 still passes through.
2. Windows past the historical 150 count as an explicit opt-in, so the retention budget drops its 2 GiB default cap for them and keeps the quarter-of-free-space clamp, which is the part that actually protects a nearly full device.
3. The producer parks once its race-ahead (bytes at or above the consumer's fetch target) has filled that budget, and the eviction that follows the advancing playhead releases it. So an opt-in prefetch buffers as much of the source as safely fits and then tracks playback, instead of buffering a fixed segment count and hoping the volume has room.

The park cannot starve playback: it only holds while at least 10 produced segments sit ahead of the consumer, and a shorter lead keeps producing regardless of the budget. Counting only the bytes ahead of the consumer, rather than the whole window, also keeps retained backward history from throttling a producer whose real race-ahead is a handful of segments, so nothing changes for sessions that do not opt in.

Your ceiling change and its test deltas are in the branch and you are credited as co-author. 999 tests green, strict-concurrency clean, tvOS Simulator build green. A device retest of an actual opt-in prefetch session (host passing Int.max, watching for the disk park in the log and for the cache footprint plateauing at a quarter of free space) once this ships would be welcome.

[fxndxs]

Confirmed on device with 5.20.7: with the host passing Int.max the prefetch now grows well past the old ~10 min boundary — the buffered band keeps advancing instead of pinning at the former ceiling. Thanks for catching that the constant alone would have put the window's bytes on the volume unchecked; the byte-bounded version is clearly the right shape.

I haven't yet verified the two tail behaviors on a long enough session: the disk park appearing in the log and the cache footprint plateauing at a quarter of free space.

[superuser404notfound]

Thanks for the device confirmation, that is the part I most wanted to see.

On the two tail behaviors: both are expected to stay invisible on a machine with plenty of free space, so before hunting for the park in the log, check the budget line the engine emits once per session at load:

[HLSVideoEngine] segment retention budget: <N> MiB (volumeAvailable=<M> MiB, forwardWindow=<W> seg, opt-in prefetch: default cap relaxed)

The opt-in prefetch: default cap relaxed suffix confirms the relaxed path is active (window past 150), and N is the budget the prefetch plateaus at: a quarter of what the tmp volume had free at load time, computed once per session. The producer only parks once the bytes it has produced at or above the consumer's fetch target reach N, so if N comfortably exceeds the remaining source, the whole film lands on disk and it never parks. That is the bound working rather than missing, there was simply nothing left to hold back. Forcing the park needs a session where the remaining source exceeds a quarter of the free space, i.e. free space below roughly 4x the remaining film bytes, which for an ~18 GB 4K HEVC film means below ~72 GB free.

Worth knowing when reading logs either way: the park is silent for its first 10 s and only logs after that, then repeats every 30 s.

[HLSSegmentProducer] #207 prefetch disk PARK (<context>) head=... cacheTarget=... forward=... MiB budget=... MiB parked=...s
[HLSSegmentProducer] #207 prefetch disk park released (<context>) head=... after=...s ...

Short parks around an eviction therefore never surface at all. Both lines are in the .session log category.

One correction to my own wording above about the plateau: what plateaus at the budget is the forward band, the bytes at or above the fetch target. The total on-disk footprint sits a little above it, because the cache also keeps up to 20 segments of backward history exempt from eviction (~200 MB for 4K HEVC). Everything older than that band is dropped once the kept bytes reach the budget.

Leaving this open as a residual watch until a session that actually reaches the budget has been observed. If your storage situation does not lend itself to that, the outcome that matters is a full film played through with the buffer growing the whole way and no stall, and you already have that.

[fxndxs]

Both tail behaviors now confirmed on device (tvOS 27, AetherEngine 5.20.7, ~3h42m UHD DV P7 remux, ~130 GB source, host passing Int.max).

Budget line at load

segment retention budget: 7268 MiB (volumeAvailable=29072 MiB, forwardWindow=2700 seg, opt-in prefetch: default cap relaxed)

Relaxed path active, and 29072/4 = 7268 exactly.

The park fires and releases exactly as designed

#207 prefetch disk PARK (advance) head=322 cacheTarget=98 forward=7271 MiB budget=7268 MiB parked=10s (opt-in prefetch full; resumes as playback advances)
#207 prefetch disk park released (advance) head=322 after=12s cacheTarget=99 forward=7262 MiB
#207 prefetch disk PARK (advance) head=323 cacheTarget=101 forward=7279 MiB budget=7268 MiB parked=10s (opt-in prefetch full; resumes as playback advances)
#207 prefetch disk park released (advance) head=323 after=18s cacheTarget=103 forward=7228 MiB

The producer parks within ~11 MiB of the budget (7271/7279 vs 7268) and the extras eviction that follows the advancing playhead releases it (7262/7228). Parks ran 12–18 s, i.e. only just past the 10 s log threshold; everything before t≈270 s stayed under it and never surfaced, matching your note. Measured source throughput drops to 0.0 during a park and recovers on release.

Footprint plateaus at budget + backward history

Cache size from the 30 s memprobes (MB): 2287 → 4352 → 6546 → 7326 → 7923 → 7925 → 7933 → 7898 → 7899 → 7804 → 7809 → 7931 → 7967 → 7894 → 7900 → 7864.

Growth breaks at t≈120 s and is dead flat from t≈150 s onward, oscillating in a ~160 MB band around 7.9 GB for the rest of the session. That sits ~630 MB above the 7268 MiB budget, which is ~20 segments at ~32 MB — your correction about the exempt backward history, confirmed to the segment.

Eviction is clearly doing the work: at t=481 s the muxer had cut 371 segments (11980 MB written) with 241 resident (7864 MB), so 130 segments had already been dropped. Producer lead at the park was 224 segments over the consumer's fetch target, ~15 min of content.

No cost to playback

stall=0 restarts=0 keepUp=y drop=0+0 for the whole 8+ minute session, parks included. Two source-side stalls landed mid-session (slow read: 2414ms, 2354ms) and were absorbed without a visible hiccup — which is the whole point of the option.

That closes the residual watch from my side. Thanks for reworking this into a byte bound rather than taking the ceiling patch as-is; the segment-count version would have put the footprint on the volume unchecked exactly as you described.

[fxndxs]

One regression turned up while running the confirmation session, on 5.20.7 and still present on 5.23.3 (the functions below are unchanged): with the opt-in prefetch active, clock.bufferedPosition collapses to exactly the playhead a few minutes in and stays there for the rest of the session, even though ~15 min of content is resident. A host drawing a buffer bar from it watches the bar shrink to zero and vanish.

It's an anchor mismatch between the frontier walk and the eviction window, not a byte-accounting problem:

• SegmentCache.contiguousForwardFrontier(from:) starts the walk at the playhead's segment and returns targetIdx - 1 when that entry is absent. contiguousForwardReadAheadSeconds then fails its frontier >= targetIdx guard and returns 0, so bufferedPosition = renderedDisplay + 0.
• pruneOutsideWindow anchors on the consumer's fetch target: lo = currentTargetIndex - backwardWindow. AVPlayer's fetch target runs ~120 s (~30 segments) ahead of the playhead, so the retained low end sits around playhead + 10 segments — the playhead's own segment is evictable, and once the budget is reached it really is evicted.

This is why it surfaces now rather than being an old bug: with the historical 10-segment window the whole footprint (~30 segments) stayed under the 2 GiB budget, so the extras below lo always survived and the walk found its starting entry. With a whole-source window the budget is reached, extras eviction runs, and the walk starts on a hole every tick.

From the same session I posted above:

segment retention budget: 7268 MiB (volumeAvailable=29072 MiB, forwardWindow=2700 seg, opt-in prefetch: default cap relaxed)
memprobe t=481s ... cacheCount=241 ... muxCuts=371 ... avBufAhead=123.6s

Resident span ≈ [131, 371]; the playhead at 481 s sits at segment ≈ 120, below the resident range. So contiguousForwardFrontier(120) returns 119, the guard fails, and the reported read-ahead is 0 while 241 segments are cached ahead of it.

Playback is unaffected and nothing is actually missing — AVPlayer holds the gap in its own buffer and the cache covers everything from ~40 s ahead onwards, so the union stays contiguous. Only the reported frontier is wrong.

One trap worth flagging for the fix: simply skipping the leading hole is unsafe. Playing at 10 min with 10–25 min resident, seek back to 2 min — the producer restarts at 2 min while the old band survives (nothing forces its eviction while the budget has room). A walk that skips the hole lands on the stale band and reports ~25 min buffered when almost nothing is available at 2 min, i.e. it fails in the dangerous direction.

What separates a harmless hole from a real one is whether the consumer has already fetched across it: segments below currentTargetIndex are by definition in AVPlayer's own buffer, anything above it has to be genuinely resident. That discriminator is already tracked by the cache (eviction and the park both use it), so the fix can be the anchor itself:

let anchor = max(segmentIndexForPlaylistTime(playlistSeconds), cache.currentTargetIndex)
let frontier = cache.contiguousForwardFrontier(from: anchor)

• opt-in prefetch: anchor = fetch target, cache resident from target - 20 upward, full frontier reported;
• backward seek: anchor = the new target, the walk stops at the hole above the freshly produced band, stale band never reached;
• startup / default window: anchor ≈ playhead, behaviour unchanged;
• software path: no cache, already 0.

Might be worth settling the published contract while you're in there, since it affects every host: the doc comment currently says "playhead plus the seconds of contiguously cached-ahead content", i.e. disk only, which also under-reports during the first seconds before the cache has built, independently of this bug. What a buffer bar wants to express is the end of the contiguous safe range from the playhead — what the consumer already holds, plus what sits contiguously above it on disk. The anchor change happens to produce exactly that.

Happy to send a patch if the shape looks right, though after the ceiling patch I'd rather have your read first. My client meanwhile draws max(engine bufferedPosition, AVPlayer loadedTimeRanges end), so the bar shows AVPlayer's ~2 min instead of vanishing — no urgency from my side.

[superuser404notfound]

Thanks for both of these. The tail confirmation is exactly the run this needed: budget line, park firing and releasing within ~11 MiB of the budget, footprint flat at budget plus the exempt backward history to the segment, and stall=0 restarts=0 through two multi-second source stalls. That closes the residual watch on the prefetch itself.

The frontier report is correct in every detail, and it reproduces from the code without needing the session logs: the walk in contiguousForwardFrontier(from:) starts at the playhead's segment, pruneOutsideWindow retains from currentTargetIndex - backwardWindow upward, and with the fetch target ~30 segments ahead the playhead's own segment is an evictable extra. The reason it only surfaces under the opt-in prefetch is the one given: the historical window kept the whole footprint under the budget, so the extras below the low end always survived and the walk found its starting entry.

The anchor is the right fix and it is merged as proposed in shape, PR #223. Two deltas worth naming.

The anchor moved into the cache rather than the caller. max(playheadSegment, cache.currentTargetIndex) at the call site takes two separate lock holds, so a target change can land between reading the target and walking the entries, and the walk then proceeds from an anchor that does not match what it observes. contiguousForwardFrontier(fromPlayhead:) resolves the anchor and walks under one hold.

The caller's guard stays measured against the playhead, not the anchor. When the walk fails immediately above the fetch target the frontier is target - 1, which is still ahead of the playhead, and that is the correct answer rather than a reason to fall back to 0: the consumer holds everything below its target. Keeping the guard at frontier >= playheadIdx also preserves the #54 clamp.

One residual your analysis does not cover, and it is worth knowing about since it is in the direction you were guarding against. Between a backward seek and the consumer's first fetch at the new position, the declared target is still the old one, so max picks the stale target and a tick or two can report the old band. It is transient by construction and self-corrects on the first fetch, unlike the permanent mis-report an unbounded hole-skip would give, so it is documented at the call site rather than bounded with separate seek state. Worth revisiting if a bar visibly jumps on backward seeks in practice.

The contract is settled in the same change, since you are right that it affects every host. PlaybackClock.bufferedPosition still documented the native path as the loadedTimeRanges span, which #105 had already replaced with the disk frontier, while the engine-side comment described disk only. Both now say what a bar wants: the end of the contiguous safe range ahead of the playhead, the consumer's own buffer plus the contiguous disk band above it. That also removes the under-report during the first seconds before the cache has built, so max(engine bufferedPosition, AVPlayer loadedTimeRanges end) should stop being necessary on the client side once this ships.

No patch needed, and the analysis is credited as co-author. 7 new tests cover the eviction precondition, the collapse, the target-anchored band, the backward-seek trap, the backward refetch, and the unchanged default window. Full suite 1081 tests green, strict-concurrency clean, CI green on macOS, tvOS Simulator and iOS Simulator.

Keeping this open until the bar has been seen behaving on a device under an opt-in session.

[superuser404notfound]

Shipped in 5.23.4.

[fxndxs]

Confirmed on device: 5.23.4, tvOS 27, opt-in prefetch (Int.max). The bar grows past the old ceiling and then holds steady instead of vanishing.

The forward session hit the precondition that used to break it, so this isn't a lucky miss:

segment retention budget: 7253 MiB (volumeAvailable=29013 MiB, forwardWindow=2700 seg, opt-in prefetch: default cap relaxed)
memprobe t=210s ... cacheCount=295 cacheMB=7815 ... muxCuts=357 ... avBufAhead=122.1s

Footprint flat from t≈120 s at budget plus ~560 MB of exempt backward history, 62 segments already evicted. Resident span ≈ [63, 357] while the playhead at 210 s sits at segment ≈ 52 — evicted, so the old walk would have started on a hole and reported 0. The fetch target at ≈ segment 83 is inside the span, the anchored walk runs to 357, and the bar shows ~20 min ahead. stall=0 restarts=0 keepUp=y throughout.

I've removed the max(engine bufferedPosition, AVPlayer loadedTimeRanges end) stopgap; the bar now reads bufferedPosition directly and the first-seconds under-report is gone too.

Seeks inside the resident band

Rewinds of 40–80 s were served entirely from disk:

declareTarget backward jump 390 -> 352: resident in cache, no restart
declareTarget backward jump 426 -> 383: resident in cache, no restart
declareTarget backward jump 414 -> 364: resident in cache, no restart

srvSfMB=3265 for the session, AVPlayer's forward buffer refilled 0 → 120 s in about three ticks, stall=0 throughout. Two seeks landed just below the band and took the restart path (producer restarted at idx=347 / at idx=344, 17 ms and 62 ms); the bar dropped briefly there and grew back, which is correct rather than stale since little was genuinely resident ahead until the fresh band closed the gap to the old one.

The residual, reproduced

A deliberate far seek does show it. Jumping out of the band (declareTarget backward jump 439 → 210, proactively restarting producer) and then forward to segment 729, the tick taken while the clock was still frozen at the old position reads:

LagDiag clk=838.80 ... wait=AVPlayerWaitingToMinimizeStallsReason fwd=2089.6 keepUp=n
LagDiag clk=2929.22 dclk=2090.42 tcs=playing fwd=3.3

So ~35 min of claimed lead over a playhead with nothing resident ahead of it — magnitude equal to the seek distance rather than a small overshoot. It lasted exactly one tick and corrected as soon as the clock landed.