From 3afea3d1b88d2c29dc71a290c1322181856942e2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 29 Aug 2026 10:03:31 -0700 Subject: [PATCH 1/9] feat(net): move wall-clock LRU expiry to the cache pool Track max_age used to drive two different clocks: the media-timestamp staleness budget and the wall-clock idle scan in evict_expired. The wall-clock half now lives on cache::Pool as an expiry window (default 30s, None to disable), so a track can promise a 5s media window while the pool reclaims anything unaccessed for 30s of real time. Media timestamps stand still during a congestion stall, so a short max_age can no longer age content out of the cache mid-stall; the LRU window is purely about not pinning RAM on content nobody reads. The origin's cache_duration keeps only its media-time role: clamping each track's advertised max_age. The relay's cache-duration knob now also sets the pool expiry, which is what its docs already promised (retained since last written or served from cache). Frame-write settlement now runs the expiry scan too, so a track appending frames to open groups without inserting new ones still ages idle siblings out. Progress on #3161 (the Rust reclamation half). Still open there: idle reclamation with zero writes needs a wakeup the model layer deliberately does not own, and the JS retention prune still keys off maxAge and retains open groups. Co-Authored-By: Claude Fable 5 --- doc/bin/relay/config.md | 40 ++++----- doc/concept/layer/moq-lite.md | 6 +- rs/moq-net/src/model/cache.rs | 95 ++++++++++++++++++--- rs/moq-net/src/model/group.rs | 15 ++-- rs/moq-net/src/model/origin.rs | 13 +-- rs/moq-net/src/model/track.rs | 152 ++++++++++++++++++++++----------- rs/moq-relay/src/cache.rs | 57 +++++++------ 7 files changed, 256 insertions(+), 122 deletions(-) diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 0ccaf767a43..78a548538f4 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -599,15 +599,18 @@ environment variable (`MOQ_STATS_ENABLED`, `MOQ_STATS_PREFIX`, ### \[cache] -Memory budget for cached groups. Old (non-latest) groups stay cached until their -track's retention window expires, the `duration` ceiling is reached, or the pool -runs out of room, whichever comes first. Under memory pressure each track evicts -its own stalest groups as it writes, ordered by when each was last written or -served from cache, and proportional to how much it writes, so usage converges on -the budget without any global scan; groups that FETCH requests keep hitting are -retained over ones nobody reads. The latest group of every track is -always retained. With none of the knobs set the cache is unbounded and only each -track's own window limits memory. +Memory budget for cached groups. Old (non-latest) groups stay cached until they +sit unaccessed past the wall-clock LRU window (`duration`, 30 seconds by +default) or the pool runs out of room, whichever comes first. Under memory +pressure each track evicts its own stalest groups as it writes, ordered by when +each was last written or served from cache, and proportional to how much it +writes, so usage converges on the budget without any global scan; groups that +FETCH requests keep hitting are retained over ones nobody reads. The latest +group of every track is always retained. With none of the knobs set the cache +is unbounded in bytes and only the default LRU window limits memory. Each +track's own retention window (its publisher's max age) is separate: that is +measured in media timestamps and bounds what subscribers may wait for, not +when idle memory is reclaimed. ```toml [cache] @@ -625,20 +628,19 @@ capacity = "8GiB" headroom = "2GiB" # Maximum time a non-latest cached group is retained since it was last written -# or served from cache by a FETCH ("30s", "500ms"). Caps each track's own -# retention window: a publisher advertising a longer window is clamped down to -# this, bounding how much history a track accumulates no matter what upstream -# asks for. A FETCH cache hit restarts the clock, so actively-read history -# stays cached. The latest group of every track is always retained, as it is -# the live edge. Unbounded (each track keeps its own window) when unset. -duration = "30s" +# or served from cache by a FETCH ("30s", "500ms"). Sets the pool's wall-clock +# LRU window (30s when unset), and also clamps each track's media-timestamp +# retention window, so a publisher advertising a longer window can't promise +# more history than the relay keeps. A FETCH cache hit restarts the clock, so +# actively-read history stays cached. The latest group of every track is +# always retained, as it is the live edge. +duration = "60s" ``` The `capacity` budget counts group payload bytes, not process RSS, so leave slack below physical memory (or just use `headroom`, which measures actual -available memory). `duration` is the age counterpart: it stops a long-running -relay from accumulating hours of history per track when the byte budget alone -leaves room for it. +available memory). `duration` is the age counterpart: it stops idle history +from pinning memory when the byte budget alone leaves room for it. All eviction happens as tracks write (there is no background reaper), so both `duration` and the byte budget cap how much history *active* publishers build diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 9812000b92c..0fbca72e536 100644 --- a/doc/concept/layer/moq-lite.md +++ b/doc/concept/layer/moq-lite.md @@ -124,8 +124,9 @@ Each Subscription consists of a few properties: - **Group Order**: The order in which groups are delivered. Defaults to descending; higher IDs are delivered first. - **Subscriber Max Age**: How old a non-latest group may get before it is skipped. Defaults to zero, so stale groups are skipped immediately. -That age is measured both on the media timeline (a group's first timestamp against the newest stamped one) and by wall-clock arrival time, and either limit can expire the group. -The media timeline keeps a backlog delivered as a burst old, while wall-clock time backstops stalled or empty groups that have no timestamp. +That age is measured on the media timeline: a group is stale once everything it could still hold falls a full budget behind the newest frame, bounded by where its successor begins. +Timestamps rather than the wall clock, so a backlog delivered as a burst is still old, while a congestion stall (nothing arrives, timestamps stand still) never expires content on its own. +Reclaiming idle cached content by wall clock is a separate cache policy, not part of this budget. Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads. The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too. Asking for old groups with `Group Start` does not exempt them: a floor only bounds what you are sent, and a subscriber that wants history has to raise its budget to match. @@ -133,6 +134,7 @@ That is also why the budget is what decides where delivery starts: the groups wo The publisher also keeps old groups around for a best-effort **Publisher Max Age** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds. The subscriber's max age is bounded by this window: a group can't be waited for longer than it's actually kept around. +Best-effort cuts the other way too: a cache reclaims groups nobody has read or written for a while (30 seconds by default) regardless of the advertised window, so idle history doesn't pin memory. It is declared per track, so a publisher raises it on the tracks that are read as history rather than followed at the live edge. hang media tracks ask for 30 seconds on that basis: a segmented egress (HLS/DASH) may only advertise segments a fetch can still reach, and a standard player starts several segments behind the live edge. diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index b9f28a40d4f..948767132de 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -18,10 +18,17 @@ //! old entries and inserting new ones both advance the mean, so the eviction //! frontier moves with cache turnover on its own. //! -//! A pool is inert by default ([`Pool::unbounded`]): publishers and subscribers that -//! never set a capacity pay only a couple of atomic counters. A relay creates one -//! bounded pool and shares it across every origin so the whole process caches into a -//! single budget. +//! The pool also owns the wall-clock LRU window ([`Pool::expiry`]): a non-latest +//! group that nobody has read or written for that long is reclaimed by its track's +//! next write, no matter what retention its track advertises. Track retention +//! ([`max_age`](crate::track::Info::max_age)) is measured in media timestamps, so a +//! congestion stall can't age content out; the pool's expiry is the orthogonal +//! wall-clock bound that keeps unwatched content from pinning RAM. +//! +//! A pool is mostly inert by default ([`Pool::unbounded`]): publishers and +//! subscribers that never set a capacity pay only a couple of atomic counters plus +//! the default expiry window. A relay creates one bounded pool and shares it across +//! every origin so the whole process caches into a single budget. use std::sync::Arc; use std::sync::atomic::{AtomicU64, Ordering}; @@ -53,6 +60,10 @@ const READ_BOOST: u64 = 2; /// the mean is count-weighted. const TICK_MS: u64 = 100; +/// Default [`Pool::expiry`]: how long an unread, unwritten non-latest group stays +/// cached before its track's next write reclaims it. +pub const DEFAULT_EXPIRY: Duration = Duration::from_secs(30); + /// A shared byte budget that caches charge into; cloning shares the same budget. /// /// The pool tracks how many payload bytes are cached across every registered group, @@ -71,6 +82,8 @@ struct Inner { used: AtomicU64, // u64::MAX means unbounded. capacity: AtomicU64, + // Wall-clock LRU window in milliseconds; u64::MAX means never expire by idleness. + expiry: AtomicU64, // Reference point for the coarse tick clock. epoch: crate::runtime::Instant, // Sum and count of last-access ticks across the evictable population, giving a @@ -85,6 +98,7 @@ impl Default for Inner { Self { used: AtomicU64::new(0), capacity: AtomicU64::new(u64::MAX), + expiry: AtomicU64::new(DEFAULT_EXPIRY.as_millis() as u64), epoch: crate::model::clock::now(), access_sum: AtomicU64::new(0), access_count: AtomicU64::new(0), @@ -131,6 +145,47 @@ impl Pool { self.inner.capacity.store(capacity, Ordering::Relaxed); } + /// Set the wall-clock LRU window, returning `self` for chaining. + /// + /// A non-latest cached group that nobody reads or writes for this long is + /// reclaimed by its track's next write, surfacing to any remaining reader as + /// [`Error::Old`](crate::Error::Old). This is deliberately independent of track + /// retention: [`max_age`](crate::track::Info::max_age) is measured in media + /// timestamps (so a congestion stall can't age content out), while this window + /// keeps content nobody is accessing from pinning RAM. `None` disables idle + /// reclamation, leaving only the byte budget. Defaults to [`DEFAULT_EXPIRY`]. + pub fn with_expiry(self, expiry: impl Into>) -> Self { + let ms = expiry + .into() + .map_or(u64::MAX, |expiry| u64::try_from(expiry.as_millis()).unwrap_or(u64::MAX)); + self.inner.expiry.store(ms, Ordering::Relaxed); + self + } + + /// The wall-clock LRU window, or `None` when idle content is never reclaimed. + pub fn expiry(&self) -> Option { + match self.inner.expiry.load(Ordering::Relaxed) { + u64::MAX => None, + ms => Some(Duration::from_millis(ms)), + } + } + + /// The LRU window in coarse ticks; effectively infinite when disabled. + pub(crate) fn expiry_ticks(&self) -> u64 { + match self.inner.expiry.load(Ordering::Relaxed) { + u64::MAX => u64::MAX, + ms => ms / TICK_MS, + } + } + + /// How often a reader on a lock-free path should re-stamp its group's access + /// time: half the LRU window keeps the stamp comfortably inside it while staying + /// rare on the hot path. Bounded even when expiry is disabled, since the stamp + /// also protects the group from byte-budget eviction. + pub(crate) fn refresh_interval(&self) -> Duration { + self.expiry().unwrap_or(DEFAULT_EXPIRY) / 2 + } + /// Returns true if both handles share the same underlying pool. pub fn same_pool(&self, other: &Self) -> bool { Arc::ptr_eq(&self.inner, &other.inner) @@ -152,11 +207,6 @@ impl Pool { elapsed.as_millis() as u64 / TICK_MS } - /// Convert a duration into coarse ticks, saturating. - pub(crate) fn ticks(duration: Duration) -> u64 { - u64::try_from(duration.as_millis() / TICK_MS as u128).unwrap_or(u64::MAX) - } - /// Mean last-access tick across the evictable population, or `None` when it is /// empty. The sum and count are read separately, so the mean is approximate /// under concurrent updates; eviction only needs a rough frontier. @@ -211,6 +261,7 @@ impl std::fmt::Debug for Pool { f.debug_struct("Pool") .field("used", &self.used()) .field("capacity", &self.capacity()) + .field("expiry", &self.expiry()) .finish() } } @@ -275,12 +326,13 @@ impl Track { self.written.swap(0, Ordering::Relaxed) } - /// Settle eviction debt from a frame write, once enough bytes accumulate. + /// Settle eviction debt and expire idle groups from a frame write, once enough + /// bytes accumulate. /// /// Called with no group lock held (locks are ordered track then group). Cheap /// until the threshold crosses: one relaxed load. This is what makes a track /// that only appends frames to open groups, never inserting another group, - /// still pay its debt (and age its content out). + /// still pay its debt and age its idle content out. pub(crate) fn settle(&self) { if self.written.load(Ordering::Relaxed) < WRITE_CHARGE_THRESHOLD { return; @@ -290,6 +342,7 @@ impl Track { let Some(state) = self.state.upgrade() else { return }; if let Ok(mut state) = state.write() { state.charge_debt(); + state.evict_expired(); } } } @@ -572,6 +625,26 @@ mod test { assert_eq!(c.accessed(), stamped); } + #[test] + fn expiry_config() { + // The LRU window is on by default, even for an unbounded pool. + let pool = Pool::unbounded(); + assert_eq!(pool.expiry(), Some(DEFAULT_EXPIRY)); + assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); + + let pool = pool.with_expiry(Duration::from_secs(1)); + assert_eq!(pool.expiry(), Some(Duration::from_secs(1))); + assert_eq!(pool.expiry_ticks(), 10); + assert_eq!(pool.refresh_interval(), Duration::from_millis(500)); + + // Disabled: never reclaimed by idleness, but readers still re-stamp on a + // bounded cadence for byte-eviction protection. + let pool = pool.with_expiry(None); + assert_eq!(pool.expiry(), None); + assert_eq!(pool.expiry_ticks(), u64::MAX); + assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); + } + #[test] fn resize() { let pool = Pool::unbounded(); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 0df6d2f8171..aebf0457942 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -814,7 +814,7 @@ impl Producer { end: None, prefetch: Prefetch::default(), last_refresh: crate::model::clock::now(), - max_age: self.track.max_age, + refresh_interval: self.cache.pool().refresh_interval(), }), // Untagged: a tagged track attaches the egress meter via `with_meter` // when it hands the consumer to a subscriber/fetch. @@ -1014,12 +1014,13 @@ struct Plain { // When this consumer last stamped the group's access time. The prefetch bounds // a batch by frame count, not elapsed time, so pops re-stamp on a time bound - // (see [`Self::refresh_if_stale`]) or a slow reader could go a full retention + // (see [`Self::refresh_if_stale`]) or a slow reader could go a full LRU // window without an access and be expired mid-read. last_refresh: crate::runtime::Instant, - // The publisher's retention window, used to bound refreshes on the prefetch path. - max_age: std::time::Duration, + // How long a prefetching reader may go without re-stamping the group's access + // time: half the pool's LRU window, captured when the cursor was created. + refresh_interval: std::time::Duration, } impl Clone for Plain { @@ -1032,7 +1033,7 @@ impl Clone for Plain { end: self.end, prefetch: Prefetch::default(), last_refresh: self.last_refresh, - max_age: self.max_age, + refresh_interval: self.refresh_interval, } } } @@ -1465,12 +1466,12 @@ impl Plain { } /// Re-stamp the group's access time from the lock-free prefetch path once half - /// the retention window has passed since this consumer last stamped it. The + /// the pool's LRU window has passed since this consumer last stamped it. The /// batch bounds frames, not elapsed time, so without this a reader pacing /// through a batch could be expired while demonstrably active. Half the window /// keeps the stamp comfortably inside it while staying rare on the hot path. fn refresh_if_stale(&mut self) { - if crate::model::clock::now().duration_since(self.last_refresh) * 2 < self.max_age { + if crate::model::clock::now().duration_since(self.last_refresh) < self.refresh_interval { return; } self.state.read().charge.refresh(); diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 3b8b12b6f5b..120a2769c56 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -106,12 +106,13 @@ pub struct Info { /// across the whole process share one memory budget. pub pool: cache::Pool, - /// Ceiling on how long any non-latest group under this origin is retained. Each - /// track's own [`max_age`](track::Info::max_age) window is clamped down to - /// this when the track binds, so a group is never held longer than this regardless - /// of what a publisher advertises. The age budget alongside [`Self::pool`]'s byte - /// budget: a relay bounds memory by both. [`Duration::MAX`] (the default) imposes no - /// ceiling, leaving each track's own window in force. + /// Ceiling on each track's media-timestamp retention window under this origin. + /// Each track's own [`max_age`](track::Info::max_age) is clamped down to this + /// when the track binds, so a subscriber is never promised more history than the + /// origin allows, regardless of what a publisher advertises. Wall-clock + /// reclamation of idle content is separate: [`Self::pool`]'s + /// [`expiry`](cache::Pool::expiry) window. [`Duration::MAX`] (the default) + /// imposes no ceiling, leaving each track's own window in force. pub cache_duration: Duration, /// The retention window given to a track whose publisher advertises none. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 3e3dfaf1e52..d50a1b86c73 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -68,14 +68,19 @@ pub struct Info { /// timestamps at this scale on the wire. Protocols whose wire can't carry it /// (pre-Lite05 moq-lite, IETF moq-transport) fall back to local monotonic milliseconds. pub timescale: Timescale, - /// How old a non-latest group may get before the publisher evicts it. The newest - /// group is always retained. + /// How far behind the live edge a group may fall, in media timestamps, before it + /// is stale. The newest group is always retained. /// /// A retention bound rather than a delivery one, the inverse of an HTTP /// `Cache-Control: max-age`. [`Subscription::max_age`] is clamped to this, since a /// group can't be waited for longer than it's kept around. Reported in TRACK_INFO so /// relays re-serve with the same window. Defaults to [`DEFAULT_MAX_AGE`]. /// + /// Measured against timestamps rather than the wall clock, so a congestion stall + /// (timestamps stop advancing) can't age content out. Wall-clock reclamation of + /// content nobody is accessing belongs to the cache pool's own + /// [`expiry`](crate::cache::Pool::expiry) window, not to this budget. + /// /// This is the `Publisher Max Age` on the wire, the publisher-side half of the /// budget [`Subscription::max_age`] sets for a subscriber. pub max_age: Duration, @@ -558,7 +563,12 @@ impl TrackState { Poll::Pending } - /// Expire groups whose last access is older than `max_age`, never the latest. + /// Expire groups idle past the pool's wall-clock LRU window, never the latest. + /// + /// The window is the pool's [`expiry`](cache::Pool::expiry), not the track's + /// [`max_age`](Info::max_age): retention is a media-timestamp promise, while this + /// is the cache's own guard against unread content pinning RAM, shared by every + /// track in the pool. /// /// One bounded, rotating scan over the eviction order, which holds every cached /// group except the protected latest. The cursor persists across calls, so @@ -566,9 +576,9 @@ impl TrackState { /// fetched, or written) entries in front of them: every position is revisited /// within a few writes. Expiry throughput is therefore EVICT_SCAN groups per write; the /// byte budget reclaims the remainder under memory pressure. - fn evict_expired(&mut self, max_age: Duration) { + pub(super) fn evict_expired(&mut self) { let now = self.cache.pool().now(); - let max_ticks = cache::Pool::ticks(max_age); + let max_ticks = self.cache.pool().expiry_ticks(); let len = self.evict.len(); if len > 0 { @@ -727,11 +737,11 @@ impl TrackState { /// Admit a freshly-created group: settle eviction debt first (so the newcomer /// can never be a victim of the very write that created it), insert it, then - /// expire by age. - fn commit_group(&mut self, group: &group::Producer, visible: bool, max_age: Duration) { + /// expire idle groups. + fn commit_group(&mut self, group: &group::Producer, visible: bool) { self.charge_debt(); self.insert_group(group, visible); - self.evict_expired(max_age); + self.evict_expired(); } /// Accrue and pay eviction debt for everything written since the last charge: @@ -956,14 +966,13 @@ impl TrackState { // An evicted sequence can be re-fetched; a live one is a duplicate. self.claim_sequence(sequence, frame_start)?; - let max_age = info.max_age; let group = group::Producer::new(group::Info { sequence }, info, self.cache.clone()); // A backfill exists because someone is fetching it right now: stamp that // access so the eviction walk can't kill it before the fetch resolves. // It is also invisible to arrival-order subscribers: fetched on demand, // not produced live by the publisher. group.cache_refresh(); - self.commit_group(&group, false, max_age); + self.commit_group(&group, false); Ok(group) } } @@ -1045,13 +1054,12 @@ impl Producer { return Err(Error::Closed); } let track = state.info.clone().unwrap(); - let max_age = track.max_age; // An evicted sequence can be re-created; a live one is a duplicate. state.claim_sequence(group.sequence, 0)?; let group = group::Producer::new(group, track, state.cache.clone()).with_meter(self.stats.meter()); - state.commit_group(&group, true, max_age); + state.commit_group(&group, true); Ok(group) } @@ -1070,11 +1078,10 @@ impl Producer { } let track = state.info.clone().unwrap(); - let max_age = track.max_age; let group = group::Producer::new(group::Info { sequence }, track, state.cache.clone()).with_meter(self.stats.meter()); - state.commit_group(&group, true, max_age); + state.commit_group(&group, true); Ok(group) } @@ -3981,8 +3988,8 @@ mod test { assert_eq!(state.offset, 0); } - // Advance time past the eviction threshold. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + // Advance time past the pool's LRU window. + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Append a new group to trigger eviction. producer.append_group().unwrap(); // seq 3 @@ -4016,8 +4023,8 @@ mod test { .unwrap(); assert_eq!(consumer.next_frame().await.unwrap().unwrap().size, 5); - // The group stays open well past the max age, then the next period starts. - crate::model::clock::advance(DEFAULT_MAX_AGE * 12); + // The group stays open well past the LRU window, then the next period starts. + crate::model::clock::advance(cache::DEFAULT_EXPIRY * 2); group.finish().unwrap(); let _next = producer.create_group(group::Info { sequence: 1 }).unwrap(); @@ -4046,7 +4053,7 @@ mod test { // Each step stays well inside the retention window, but the whole read // spans several windows. New groups keep the expiry scan running. for seq in 2..12u64 { - crate::model::clock::advance(DEFAULT_MAX_AGE / 2); + crate::model::clock::advance(cache::DEFAULT_EXPIRY / 2); let frame = reading.next_frame().await; assert!( matches!(frame, Ok(Some(_))), @@ -4079,7 +4086,7 @@ mod test { // One whole-frame read per half-window: most are served straight from the // prefetch without locking. New groups keep the expiry scan running. for seq in 1..20u64 { - crate::model::clock::advance(DEFAULT_MAX_AGE / 2); + crate::model::clock::advance(cache::DEFAULT_EXPIRY / 2); let frame = reading.read_frame().await; assert!( matches!(frame, Ok(Some(_))), @@ -4104,12 +4111,12 @@ mod test { producer.create_group(1u64.into()).unwrap().finish().unwrap(); // Deliver just inside the window: the delivery stamps the group. - crate::model::clock::advance(DEFAULT_MAX_AGE - Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY - Duration::from_secs(1)); let mut reading = subscriber.assert_group(); // Almost another full window passes: far beyond the write, inside the // delivery stamp. The new group runs the expiry scan. - crate::model::clock::advance(DEFAULT_MAX_AGE - Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY - Duration::from_secs(1)); producer.create_group(2u64.into()).unwrap().finish().unwrap(); let frame = reading.read_frame().await.unwrap(); @@ -4135,7 +4142,7 @@ mod test { // One chunk per half-window; the whole frame spans several windows. New // groups keep the expiry scan running. for seq in 2..12u64 { - crate::model::clock::advance(DEFAULT_MAX_AGE / 2); + crate::model::clock::advance(cache::DEFAULT_EXPIRY / 2); frame.write(bytes::Bytes::from_static(b"x")).unwrap(); producer.create_group(seq.into()).unwrap().finish().unwrap(); } @@ -4168,14 +4175,14 @@ mod test { subscriber.assert_no_group(); // Just inside the window, the cap rises and the re-offer stamps group 1. - crate::model::clock::advance(DEFAULT_MAX_AGE - Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY - Duration::from_secs(1)); subscriber.end_at(1); let mut reading = subscriber.assert_group(); assert_eq!(reading.sequence, 1); // Almost another full window passes: far beyond the write, inside the // re-offer stamp. The new group runs the expiry scan. - crate::model::clock::advance(DEFAULT_MAX_AGE - Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY - Duration::from_secs(1)); producer.create_group(2u64.into()).unwrap().finish().unwrap(); let frame = reading.read_frame().await.unwrap(); @@ -4187,8 +4194,8 @@ mod test { let mut producer = track_producer("test", None); producer.append_group().unwrap(); // seq 0 - // Advance time past threshold. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + // Advance time past the LRU window. + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Append another group; seq 0 is expired and evicted. producer.append_group().unwrap(); // seq 1 @@ -4222,7 +4229,7 @@ mod test { let mut consumer = producer.subscribe(None); - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); producer.append_group().unwrap(); // seq 1 // Group 0 was evicted. Consumer should get group 1. @@ -4230,22 +4237,64 @@ mod test { assert_eq!(group.sequence, 1); } + /// Mint a track under an origin whose pool has the given wall-clock LRU window. + fn track_producer_expiring(name: impl Into>, expiry: impl Into>) -> Producer { + let origin = crate::origin::Info::default().with_pool(cache::Pool::unbounded().with_expiry(expiry)); + Producer::new( + Arc::new(broadcast::Info { + origin, + ..Default::default() + }), + name, + None, + ) + } + #[tokio::test] - async fn cache_age_controls_eviction() { - // A shorter cache evicts sooner than the default. - let mut producer = track_producer("test", Info::default().with_max_age(Duration::from_secs(1))); + async fn pool_expiry_controls_eviction() { + // A shorter LRU window on the pool evicts sooner than the default. + let mut producer = track_producer_expiring("test", Duration::from_secs(1)); producer.append_group().unwrap(); // seq 0 - // Past the custom budget but well within DEFAULT_MAX_AGE. + // Past the pool's window but well within cache::DEFAULT_EXPIRY. crate::model::clock::advance(Duration::from_secs(2)); producer.append_group().unwrap(); // seq 1 - // Seq 0 is gone because the publisher only keeps groups for 1s. + // Seq 0 is gone because the pool only keeps idle groups for 1s. let state = producer.state.read(); assert_eq!(live_groups(&state), 1); assert_eq!(first_live_sequence(&state), 1); } + /// A track's `max_age` is a media-timestamp budget: it does not drive wall-clock + /// eviction, so a stall (no accesses, no timestamp progress) shorter than the + /// pool's LRU window can't age content out no matter how small the window is. + #[tokio::test] + async fn max_age_does_not_drive_wall_eviction() { + let mut producer = track_producer("test", Info::default().with_max_age(Duration::from_secs(1))); + producer.append_group().unwrap(); // seq 0 + + // Far past max_age in wall time, but inside the pool's LRU window. + crate::model::clock::advance(Duration::from_secs(10)); + producer.append_group().unwrap(); // seq 1 + + let state = producer.state.read(); + assert_eq!(live_groups(&state), 2, "max_age is media time, not a wall clock"); + } + + /// Disabling the pool's expiry keeps idle groups until byte pressure reclaims them. + #[tokio::test] + async fn disabled_pool_expiry_never_reclaims() { + let mut producer = track_producer_expiring("test", None); + producer.append_group().unwrap(); // seq 0 + + crate::model::clock::advance(Duration::from_secs(3600)); + producer.append_group().unwrap(); // seq 1 + + let state = producer.state.read(); + assert_eq!(live_groups(&state), 2); + } + #[test] fn max_age_clamped_to_cache() { let producer = track_producer("test", Info::default().with_max_age(Duration::from_secs(2))); @@ -4302,9 +4351,10 @@ mod test { assert_eq!(under.state.read().max_age_bound(), Some(Duration::from_millis(500))); } + /// The origin ceiling clamps the media-timestamp budget only; wall-clock + /// reclamation belongs to the pool's LRU window, not the ceiling. #[tokio::test] - async fn origin_cache_duration_caps_eviction() { - // The publisher wants a 60s window, but the origin caps retention at 1s. + async fn origin_cache_duration_does_not_wall_evict() { let mut producer = track_producer_capped( "test", Info::default().with_max_age(Duration::from_secs(60)), @@ -4312,14 +4362,12 @@ mod test { ); producer.append_group().unwrap(); // seq 0 - // Past the origin ceiling but far within the publisher's own 60s window. + // Far past the ceiling in wall time, but inside the pool's LRU window. crate::model::clock::advance(Duration::from_secs(2)); producer.append_group().unwrap(); // seq 1 - // Seq 0 is evicted anyway: the origin ceiling wins over the larger publisher window. let state = producer.state.read(); - assert_eq!(live_groups(&state), 1); - assert_eq!(first_live_sequence(&state), 1); + assert_eq!(live_groups(&state), 2); } #[test] @@ -5228,7 +5276,7 @@ mod test { } // Expire all three groups. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Append seq 6 (becomes new max_sequence). producer.append_group().unwrap(); // seq 6 @@ -5253,7 +5301,7 @@ mod test { // Arrive: seq 5, then seq 3. producer.create_group(group::Info { sequence: 5 }).unwrap(); - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Seq 3 arrives late; max_sequence is still 5 (at front). producer.create_group(group::Info { sequence: 3 }).unwrap(); @@ -5267,7 +5315,7 @@ mod test { } // Expire seq 3 as well. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Seq 2 arrives late, triggering eviction. producer.create_group(group::Info { sequence: 2 }).unwrap(); @@ -6654,9 +6702,9 @@ mod test { ); } - /// A late frame write restarts the retention clock (retention is documented as - /// time since last written or fetched), so an actively-growing group is not - /// expired as old mid-write. + /// A late frame write restarts the LRU clock (the window measures time since + /// last written or fetched), so an actively-growing group is not expired as + /// idle mid-write. #[tokio::test] async fn write_restarts_retention_clock() { let (mut producer, _pool) = pooled_producer(1 << 40); @@ -6664,7 +6712,7 @@ mod test { producer.append_group().unwrap().finish().unwrap(); // seq 1 demotes seq 0 // Idle past the window, then the straggler receives a late frame. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); straggler .write_frame(Timestamp::ZERO, bytes::Bytes::from(vec![0u8; 100])) .unwrap(); @@ -6674,7 +6722,7 @@ mod test { assert!(consumer.peek_group(0).is_some(), "the write restarted the clock"); // Once the writes stop, the group ages out normally. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); producer.append_group().unwrap().finish().unwrap(); // seq 3 runs expiry assert!(consumer.peek_group(0).is_none(), "idle content still expires"); } @@ -6705,7 +6753,7 @@ mod test { // Age everything out, then refresh the first four backfills so they sit // fresh at the front of the eviction order, hiding the expired fifth. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); for sequence in 1..=4u64 { consumer.fetch_group(sequence, None).await.unwrap(); } @@ -6874,9 +6922,9 @@ mod test { } // Keep seq 2 fresh while seq 3 (behind it in eviction order) expires. - crate::model::clock::advance(Duration::from_secs(4)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY / 2 + Duration::from_secs(1)); consumer.fetch_group(2, None).await.unwrap(); - crate::model::clock::advance(DEFAULT_MAX_AGE - Duration::from_secs(2)); + crate::model::clock::advance(cache::DEFAULT_EXPIRY / 2 + Duration::from_secs(1)); producer.create_group(6u64.into()).unwrap().finish().unwrap(); let consumer = producer.consume(); @@ -7039,8 +7087,8 @@ mod test { pending.await.unwrap(); let used = pool.used(); - // Age past the track window; the next write reclaims the backfill. - crate::model::clock::advance(DEFAULT_MAX_AGE + Duration::from_secs(1)); + // Age past the pool's LRU window; the next write reclaims the backfill. + crate::model::clock::advance(cache::DEFAULT_EXPIRY + Duration::from_secs(1)); producer.create_group(6u64.into()).unwrap().finish().unwrap(); assert!(consumer.peek_group(2).is_none(), "expired backfill is reclaimed"); diff --git a/rs/moq-relay/src/cache.rs b/rs/moq-relay/src/cache.rs index c78b9d270dc..cb0ec5ab299 100644 --- a/rs/moq-relay/src/cache.rs +++ b/rs/moq-relay/src/cache.rs @@ -14,11 +14,11 @@ const GOVERNOR_INTERVAL: Duration = Duration::from_secs(5); /// Configuration for the relay's group cache. /// -/// Non-latest groups stay cached until their track's retention window expires, -/// the `duration` ceiling is reached, or the pool runs out of room, whichever -/// comes first (the latest group of every track is always retained). With none -/// of the knobs set the pool is unbounded and only each track's own window -/// bounds memory. +/// Non-latest groups stay cached until they sit unaccessed past the wall-clock +/// LRU window (`duration`, 30s by default) or the pool runs out of room, +/// whichever comes first (the latest group of every track is always retained). +/// With none of the knobs set the pool is unbounded in bytes and only the +/// default LRU window bounds memory. #[derive(usage::Args, Clone, Debug, Default, Deserialize, Serialize)] #[usage(unknown_flags = "error", args_override_self = false)] #[serde(default, deny_unknown_fields)] @@ -43,36 +43,38 @@ pub struct CacheConfig { #[usage(long = "cache-headroom", env = "MOQ_CACHE_HEADROOM")] pub headroom: Option, - /// Maximum time a non-latest cached group is retained since it was last - /// written or served from cache by a FETCH, e.g. "30s" or "500ms". + /// Maximum time a non-latest cached group is retained, e.g. "30s" or "500ms". /// - /// Caps each track's own retention window: a publisher advertising a longer - /// window is clamped down to this, bounding how much history a track can - /// accumulate no matter what upstream asks for. A FETCH cache hit restarts - /// the clock, so actively-read history stays cached. This bounds memory by - /// age where `capacity` bounds it by bytes. Unbounded (each track keeps its - /// own window) when unset. + /// Sets both halves of the retention bound. The pool's wall-clock LRU window + /// becomes this: a group nobody has written or served from cache for this + /// long is reclaimed, and a FETCH cache hit restarts that clock, so + /// actively-read history stays cached. Each track's own media-timestamp + /// retention window is also clamped down to this, so a publisher advertising + /// a longer window can't promise more history than the relay keeps. This + /// bounds memory by age where `capacity` bounds it by bytes. When unset, the + /// LRU window keeps its 30 second default and each track keeps its own + /// retention window. /// - /// Two caveats on the ceiling. The latest group of every track is always - /// retained, since it is the live edge. And expiry is evaluated when a track - /// writes its next group, so a publisher that stops writing without - /// disconnecting keeps whatever it had cached until it resumes or the - /// broadcast closes; under memory pressure the `capacity` budget is repaid by - /// the tracks that are still writing. + /// Two caveats. The latest group of every track is always retained, since it + /// is the live edge. And expiry is evaluated when a track writes, so a + /// publisher that stops writing without disconnecting keeps whatever it had + /// cached until it resumes or the broadcast closes; under memory pressure the + /// `capacity` budget is repaid by the tracks that are still writing. #[usage(long = "cache-duration", env = "MOQ_CACHE_DURATION")] pub duration: Option, } /// The relay's resolved cache settings: the shared byte-budget pool plus the -/// age ceiling applied to every track. +/// retention ceiling applied to every track. #[non_exhaustive] pub struct Cache { - /// The shared byte-budget pool every session's groups register with. + /// The shared pool every session's groups register with: the byte budget plus + /// the wall-clock LRU window that reclaims idle groups. pub pool: cache::Pool, - /// Ceiling on how long a non-latest group is retained (the latest group of every - /// track is always kept). [`Duration::MAX`] imposes no ceiling, leaving each - /// track's own window in force. + /// Ceiling on each track's media-timestamp retention window (the latest group of + /// every track is always kept). [`Duration::MAX`] imposes no ceiling, leaving + /// each track's own window in force. pub duration: Duration, } @@ -81,10 +83,15 @@ impl CacheConfig { /// spawning the headroom governor when configured. Requires a tokio runtime. pub fn init(&self) -> anyhow::Result { let capacity = self.capacity.as_deref().map(parse_limit).transpose()?; - let pool = match capacity { + let mut pool = match capacity { Some(bytes) => cache::Pool::new(bytes), None => cache::Pool::unbounded(), }; + // The same window also clamps each track's media-timestamp retention below, + // via `Cache::duration`; unset leaves the pool's default LRU window in force. + if let Some(duration) = self.duration.map(moq_tokio::Duration::into_std) { + pool = pool.with_expiry(duration); + } if let Some(headroom) = self.headroom.as_deref() { let headroom = parse_limit(headroom)?; From f219573736fab29921a7ee0216085d8b378add1e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 29 Aug 2026 19:21:27 -0700 Subject: [PATCH 2/9] fix(net): run cache expiry independently of byte debt Preserve the no-eviction contract for bare unbounded pools while explicitly enabling the default idle window for bounded pools, standalone origins, and relays. Run time-based scans for small whole-frame and streamed writes, with regression coverage for both paths. Co-Authored-By: GPT-5 --- doc/bin/relay/config.md | 6 +-- rs/moq-net/src/model/cache.rs | 93 +++++++++++++++++++++++++++------- rs/moq-net/src/model/group.rs | 3 ++ rs/moq-net/src/model/origin.rs | 21 ++++---- rs/moq-net/src/model/track.rs | 32 ++++++++++++ rs/moq-relay/src/cache.rs | 24 +++++---- 6 files changed, 138 insertions(+), 41 deletions(-) diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 78a548538f4..46d12cf155c 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -603,7 +603,7 @@ Memory budget for cached groups. Old (non-latest) groups stay cached until they sit unaccessed past the wall-clock LRU window (`duration`, 30 seconds by default) or the pool runs out of room, whichever comes first. Under memory pressure each track evicts its own stalest groups as it writes, ordered by when -each was last written or served from cache, and proportional to how much it +each was last read or written, and proportional to how much it writes, so usage converges on the budget without any global scan; groups that FETCH requests keep hitting are retained over ones nobody reads. The latest group of every track is always retained. With none of the knobs set the cache @@ -627,8 +627,8 @@ capacity = "8GiB" # with `capacity` to also bound the target from above. headroom = "2GiB" -# Maximum time a non-latest cached group is retained since it was last written -# or served from cache by a FETCH ("30s", "500ms"). Sets the pool's wall-clock +# Maximum time a non-latest cached group is retained since it was last read or +# written ("30s", "500ms"). Sets the pool's wall-clock # LRU window (30s when unset), and also clamps each track's media-timestamp # retention window, so a publisher advertising a longer window can't promise # more history than the relay keeps. A FETCH cache hit restarts the clock, so diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 948767132de..ae903b7c415 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -25,10 +25,11 @@ //! congestion stall can't age content out; the pool's expiry is the orthogonal //! wall-clock bound that keeps unwatched content from pinning RAM. //! -//! A pool is mostly inert by default ([`Pool::unbounded`]): publishers and -//! subscribers that never set a capacity pay only a couple of atomic counters plus -//! the default expiry window. A relay creates one bounded pool and shares it across -//! every origin so the whole process caches into a single budget. +//! A bare pool is inert by default ([`Pool::unbounded`]): publishers and subscribers +//! that never set a capacity or expiry pay only a couple of atomic counters. A +//! standalone [`origin`](crate::origin::Info) enables [`DEFAULT_EXPIRY`], while a +//! relay creates one configured pool and shares it across every origin so the whole +//! process caches into a single policy. use std::sync::Arc; use std::sync::atomic::{AtomicU64, Ordering}; @@ -60,8 +61,10 @@ const READ_BOOST: u64 = 2; /// the mean is count-weighted. const TICK_MS: u64 = 100; -/// Default [`Pool::expiry`]: how long an unread, unwritten non-latest group stays -/// cached before its track's next write reclaims it. +/// Default idle window for standalone origins and relays. +/// +/// A bare [`Pool`] has no idle expiry until one is configured with +/// [`Pool::with_expiry`]. pub const DEFAULT_EXPIRY: Duration = Duration::from_secs(30); /// A shared byte budget that caches charge into; cloning shares the same budget. @@ -98,7 +101,7 @@ impl Default for Inner { Self { used: AtomicU64::new(0), capacity: AtomicU64::new(u64::MAX), - expiry: AtomicU64::new(DEFAULT_EXPIRY.as_millis() as u64), + expiry: AtomicU64::new(u64::MAX), epoch: crate::model::clock::now(), access_sum: AtomicU64::new(0), access_count: AtomicU64::new(0), @@ -107,7 +110,7 @@ impl Default for Inner { } impl Pool { - /// Create a pool with a byte target that tracks evict toward as they write. + /// Create a pool with a byte target and the default idle expiry. /// /// The budget counts frame payload bytes (plus a small fixed overhead per /// group), not process RSS, and is a convergence target rather than a hard @@ -115,6 +118,10 @@ impl Pool { pub fn new(capacity: u64) -> Self { let pool = Self::default(); pool.inner.capacity.store(capacity, Ordering::Relaxed); + pool.inner.expiry.store( + u64::try_from(DEFAULT_EXPIRY.as_millis()).unwrap_or(u64::MAX), + Ordering::Relaxed, + ); pool } @@ -153,7 +160,8 @@ impl Pool { /// retention: [`max_age`](crate::track::Info::max_age) is measured in media /// timestamps (so a congestion stall can't age content out), while this window /// keeps content nobody is accessing from pinning RAM. `None` disables idle - /// reclamation, leaving only the byte budget. Defaults to [`DEFAULT_EXPIRY`]. + /// reclamation, leaving only the byte budget. A bare pool has no idle expiry; + /// standalone origins and relays configure [`DEFAULT_EXPIRY`]. pub fn with_expiry(self, expiry: impl Into>) -> Self { let ms = expiry .into() @@ -271,6 +279,14 @@ impl std::fmt::Debug for Pool { /// pays. Coarse: the cost is one track-state lock per threshold crossing. const WRITE_CHARGE_THRESHOLD: u64 = 256 * 1024; +/// Maximum cadence for write-driven expiry scans, in the pool's coarse ticks. +/// +/// Byte debt settles only after enough data accumulates, but expiry is a time +/// policy and must also run for low-bitrate tracks. Limiting that extra track lock +/// to once per second keeps the write hot path cheap while a bounded scan drains +/// stale backlogs steadily. +const EXPIRY_SCAN_TICKS: u64 = 1000 / TICK_MS; + /// One track's account against the [`Pool`], shared with every group it creates. /// /// Groups charge their bytes here (through a [`Charge`]) rather than straight into the @@ -289,6 +305,9 @@ pub(crate) struct Track { // decremented here: the track swaps it out as it accrues debt. written: AtomicU64, + // Earliest coarse tick when a frame write may run another expiry scan. + next_expiry: AtomicU64, + // The track that pays this account off, holding the groups being charged. state: kio::Weak, } @@ -299,6 +318,7 @@ impl Track { Arc::new(Self { pool, written: AtomicU64::new(0), + next_expiry: AtomicU64::new(0), state, }) } @@ -326,24 +346,48 @@ impl Track { self.written.swap(0, Ordering::Relaxed) } - /// Settle eviction debt and expire idle groups from a frame write, once enough - /// bytes accumulate. + /// Settle eviction debt and expire idle groups from a frame write. /// /// Called with no group lock held (locks are ordered track then group). Cheap - /// until the threshold crosses: one relaxed load. This is what makes a track - /// that only appends frames to open groups, never inserting another group, - /// still pay its debt and age its idle content out. + /// until the byte or time gate crosses: relaxed atomics only. This is what makes + /// a track that only appends frames to open groups, never inserting another + /// group, still pay its debt and age its idle content out. pub(crate) fn settle(&self) { - if self.written.load(Ordering::Relaxed) < WRITE_CHARGE_THRESHOLD { + let settle_debt = self.written.load(Ordering::Relaxed) >= WRITE_CHARGE_THRESHOLD; + let expire = self.expiry_due(); + if !settle_debt && !expire { return; } // Counts as a producer while it lives, which is why `track::Producer` gates // its teardown on its own clone count rather than the state's. let Some(state) = self.state.upgrade() else { return }; if let Ok(mut state) = state.write() { - state.charge_debt(); - state.evict_expired(); + if settle_debt { + state.charge_debt(); + } + if expire { + state.evict_expired(); + } + } + } + + /// Claim the next write-driven expiry scan when its time gate is due. + fn expiry_due(&self) -> bool { + let expiry = self.pool.expiry_ticks(); + if expiry == u64::MAX { + return false; + } + + let now = self.pool.now(); + let next = self.next_expiry.load(Ordering::Relaxed); + if now < next { + return false; } + + let interval = expiry.clamp(1, EXPIRY_SCAN_TICKS); + self.next_expiry + .compare_exchange(next, now.saturating_add(interval), Ordering::Relaxed, Ordering::Relaxed) + .is_ok() } } @@ -495,6 +539,12 @@ mod test { assert_eq!(pool.used(), 0); } + #[test] + fn bounded_pool_enables_default_expiry() { + let pool = Pool::new(1000); + assert_eq!(pool.expiry(), Some(DEFAULT_EXPIRY)); + } + #[test] fn accrue_none_under_capacity() { let pool = Pool::new(1000); @@ -627,9 +677,9 @@ mod test { #[test] fn expiry_config() { - // The LRU window is on by default, even for an unbounded pool. + // A bare pool preserves the unbounded contract in both dimensions. let pool = Pool::unbounded(); - assert_eq!(pool.expiry(), Some(DEFAULT_EXPIRY)); + assert_eq!(pool.expiry(), None); assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); let pool = pool.with_expiry(Duration::from_secs(1)); @@ -645,6 +695,11 @@ mod test { assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); } + #[test] + fn standalone_origin_enables_default_expiry() { + assert_eq!(crate::origin::Info::default().pool.expiry(), Some(DEFAULT_EXPIRY)); + } + #[test] fn resize() { let pool = Pool::unbounded(); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index aebf0457942..4ac4622f18c 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -667,6 +667,9 @@ impl Producer { if let Ok(mut state) = self.state.write() { state.charge.record_write(); } + // The payload was charged when the frame opened, but a long streamed frame + // still counts as track activity for the independent expiry time gate. + self.cache.settle(); } /// Commit the in-flight frame as a completed frame (called by [`frame::Producer::finish`]). diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 120a2769c56..e134d8cb8c3 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -89,9 +89,9 @@ impl Origin { /// parent handle every broadcast carries ([`broadcast::Info::origin`]): the origin owns /// the [`cache::Pool`] every group in the tree charges into, so a relay configures one /// bounded pool here and every broadcast, track, and group beneath it reaches that single -/// budget by walking up the ownership chain. Defaults to an unbounded pool. Cheap to -/// clone (a `Copy` id plus an `Arc`-handle bump), so it's stored by value rather than -/// behind another `Arc`. +/// budget by walking up the ownership chain. Defaults to no byte target and the +/// cache's standard idle expiry. Cheap to clone (a `Copy` id plus an `Arc`-handle +/// bump), so it's stored by value rather than behind another `Arc`. #[derive(Clone, Debug)] #[non_exhaustive] pub struct Info { @@ -101,9 +101,10 @@ pub struct Info { /// The cache pool broadcasts under this origin charge their groups into. It flows /// down the ownership chain (origin -> broadcast -> track -> group): a track opens - /// an account against it, and its groups charge through that. Unbounded by - /// default; a relay sets a bounded one (via [`Self::with_pool`]) so cached groups - /// across the whole process share one memory budget. + /// an account against it, and its groups charge through that. It has no byte target + /// and uses [`cache::DEFAULT_EXPIRY`] by default; a relay sets a shared configured + /// pool (via [`Self::with_pool`]) so cached groups across the whole process share + /// one policy. pub pool: cache::Pool, /// Ceiling on each track's media-timestamp retention window under this origin. @@ -128,12 +129,12 @@ pub struct Info { } impl Default for Info { - /// An unknown origin (id `0`, no loop detection) with an unbounded pool. This is - /// what a standalone broadcast (no relay origin) inherits. + /// An unknown origin (id `0`, no loop detection) with no byte target and the + /// default idle expiry. This is what a standalone broadcast inherits. fn default() -> Self { Self { id: Origin::UNKNOWN, - pool: cache::Pool::default(), + pool: cache::Pool::unbounded().with_expiry(cache::DEFAULT_EXPIRY), cache_duration: Duration::MAX, default_max_age: track::DEFAULT_MAX_AGE, } @@ -141,7 +142,7 @@ impl Default for Info { } impl Info { - /// Config for the given origin id with an unbounded cache pool. + /// Config for the given origin id with no byte target and the default idle expiry. pub fn new(id: Origin) -> Self { Self { id, ..Self::default() } } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index d50a1b86c73..582241dcd82 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -4266,6 +4266,38 @@ mod test { assert_eq!(first_live_sequence(&state), 1); } + #[tokio::test] + async fn small_frame_write_expires_idle_siblings() { + let mut producer = track_producer_expiring("test", Duration::from_secs(1)); + producer.append_group().unwrap().finish().unwrap(); // seq 0 + let mut live = producer.append_group().unwrap(); // seq 1 + + crate::model::clock::advance(Duration::from_secs(2)); + live.write_frame(Timestamp::ZERO, b"x".as_slice()).unwrap(); + + let expired = !producer.state.read().lookup.contains_key(&0); + assert!(expired, "a small frame write runs expiry"); + } + + #[tokio::test] + async fn streaming_frame_write_expires_idle_siblings() { + let mut producer = track_producer_expiring("test", Duration::from_secs(1)); + producer.append_group().unwrap().finish().unwrap(); // seq 0 + let mut live = producer.append_group().unwrap(); // seq 1 + let mut frame = live + .create_frame(frame::Info { + size: 1, + timestamp: Timestamp::ZERO, + }) + .unwrap(); + + crate::model::clock::advance(Duration::from_secs(2)); + frame.write(b"x".as_slice()).unwrap(); + + let expired = !producer.state.read().lookup.contains_key(&0); + assert!(expired, "a streamed chunk runs expiry"); + } + /// A track's `max_age` is a media-timestamp budget: it does not drive wall-clock /// eviction, so a stall (no accesses, no timestamp progress) shorter than the /// pool's LRU window can't age content out no matter how small the window is. diff --git a/rs/moq-relay/src/cache.rs b/rs/moq-relay/src/cache.rs index cb0ec5ab299..14a933c2dec 100644 --- a/rs/moq-relay/src/cache.rs +++ b/rs/moq-relay/src/cache.rs @@ -46,9 +46,8 @@ pub struct CacheConfig { /// Maximum time a non-latest cached group is retained, e.g. "30s" or "500ms". /// /// Sets both halves of the retention bound. The pool's wall-clock LRU window - /// becomes this: a group nobody has written or served from cache for this - /// long is reclaimed, and a FETCH cache hit restarts that clock, so - /// actively-read history stays cached. Each track's own media-timestamp + /// becomes this: a group nobody has read or written for this long is + /// reclaimed, so actively-read history stays cached. Each track's own media-timestamp /// retention window is also clamped down to this, so a publisher advertising /// a longer window can't promise more history than the relay keeps. This /// bounds memory by age where `capacity` bounds it by bytes. When unset, the @@ -83,15 +82,15 @@ impl CacheConfig { /// spawning the headroom governor when configured. Requires a tokio runtime. pub fn init(&self) -> anyhow::Result { let capacity = self.capacity.as_deref().map(parse_limit).transpose()?; - let mut pool = match capacity { + let pool = match capacity { Some(bytes) => cache::Pool::new(bytes), None => cache::Pool::unbounded(), - }; - // The same window also clamps each track's media-timestamp retention below, - // via `Cache::duration`; unset leaves the pool's default LRU window in force. - if let Some(duration) = self.duration.map(moq_tokio::Duration::into_std) { - pool = pool.with_expiry(duration); } + .with_expiry( + self.duration + .map(moq_tokio::Duration::into_std) + .unwrap_or(cache::DEFAULT_EXPIRY), + ); if let Some(headroom) = self.headroom.as_deref() { let headroom = parse_limit(headroom)?; @@ -179,6 +178,13 @@ async fn governor(pool: cache::Pool, capacity: Option, headroom: u64) { mod tests { use super::*; + #[test] + fn default_config_enables_expiry_without_clamping_media_time() { + let cache = CacheConfig::default().init().unwrap(); + assert_eq!(cache.pool.expiry(), Some(cache::DEFAULT_EXPIRY)); + assert_eq!(cache.duration, Duration::MAX); + } + #[test] fn parse_limit_bytes() { assert_eq!(parse_limit("8GiB").unwrap(), 8 * 1024 * 1024 * 1024); From deacd2f5b6f6c62b94bb7ae034295e45ea55b17f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 29 Aug 2026 19:41:58 -0700 Subject: [PATCH 3/9] fix(net): expire cached groups on datagram writes Route both origin and forwarded datagram writes through the cache's throttled settlement path after releasing the track lock. This keeps idle group expiry progressing for active datagram-only publishers. Co-Authored-By: GPT-5 --- rs/moq-net/src/model/track.rs | 38 +++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 582241dcd82..c686bba0bb3 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1124,6 +1124,9 @@ impl Producer { timestamp, payload, }); + let cache = state.cache.clone(); + drop(state); + cache.settle(); Ok(sequence) } @@ -1153,6 +1156,9 @@ impl Producer { state.max_sequence = Some(state.max_sequence.unwrap_or(0).max(datagram.sequence)); meter.datagram(datagram.payload.len() as u64); state.push_datagram(datagram); + let cache = state.cache.clone(); + drop(state); + cache.settle(); Ok(()) } @@ -4298,6 +4304,38 @@ mod test { assert!(expired, "a streamed chunk runs expiry"); } + #[tokio::test] + async fn appended_datagram_expires_idle_groups() { + let mut producer = track_producer_expiring("test", Duration::from_secs(1)); + producer.append_group().unwrap().finish().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 1 + + crate::model::clock::advance(Duration::from_secs(2)); + producer.append_datagram(Timestamp::ZERO, b"x".as_slice()).unwrap(); + + let expired = !producer.state.read().lookup.contains_key(&0); + assert!(expired, "an appended datagram runs expiry"); + } + + #[tokio::test] + async fn forwarded_datagram_expires_idle_groups() { + let mut producer = track_producer_expiring("test", Duration::from_secs(1)); + producer.append_group().unwrap().finish().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 1 + + crate::model::clock::advance(Duration::from_secs(2)); + producer + .write_datagram(Datagram { + sequence: 2, + timestamp: Timestamp::ZERO, + payload: bytes::Bytes::from_static(b"x"), + }) + .unwrap(); + + let expired = !producer.state.read().lookup.contains_key(&0); + assert!(expired, "a forwarded datagram runs expiry"); + } + /// A track's `max_age` is a media-timestamp budget: it does not drive wall-clock /// eviction, so a stall (no accesses, no timestamp progress) shorter than the /// pool's LRU window can't age content out no matter how small the window is. From c3c2135282201ffe52bd7115e493e2d9f184441c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 29 Aug 2026 19:59:03 -0700 Subject: [PATCH 4/9] fix(net): refresh consumers with the current expiry Keep the shared cache pool on prefetched consumers and query its current refresh cadence. Existing readers now follow expiry changes made after their cursor was created. Co-Authored-By: GPT-5 --- rs/moq-net/src/model/group.rs | 37 ++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 4ac4622f18c..68749d3a485 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -817,7 +817,7 @@ impl Producer { end: None, prefetch: Prefetch::default(), last_refresh: crate::model::clock::now(), - refresh_interval: self.cache.pool().refresh_interval(), + pool: self.cache.pool().clone(), }), // Untagged: a tagged track attaches the egress meter via `with_meter` // when it hands the consumer to a subscriber/fetch. @@ -1021,9 +1021,9 @@ struct Plain { // window without an access and be expired mid-read. last_refresh: crate::runtime::Instant, - // How long a prefetching reader may go without re-stamping the group's access - // time: half the pool's LRU window, captured when the cursor was created. - refresh_interval: std::time::Duration, + // The shared pool supplies the current refresh cadence. Its expiry can be + // reconfigured after this cursor is created. + pool: cache::Pool, } impl Clone for Plain { @@ -1036,7 +1036,7 @@ impl Clone for Plain { end: self.end, prefetch: Prefetch::default(), last_refresh: self.last_refresh, - refresh_interval: self.refresh_interval, + pool: self.pool.clone(), } } } @@ -1474,11 +1474,12 @@ impl Plain { /// through a batch could be expired while demonstrably active. Half the window /// keeps the stamp comfortably inside it while staying rare on the hot path. fn refresh_if_stale(&mut self) { - if crate::model::clock::now().duration_since(self.last_refresh) < self.refresh_interval { + let now = crate::model::clock::now(); + if now.duration_since(self.last_refresh) < self.pool.refresh_interval() { return; } self.state.read().charge.refresh(); - self.last_refresh = crate::model::clock::now(); + self.last_refresh = now; } // A helper to automatically apply Dropped if the state is closed without an error. fn poll(&self, waiter: &kio::Waiter, f: F) -> Poll> @@ -1943,6 +1944,28 @@ mod test { assert!(end.is_none()); } + #[test] + fn prefetch_refresh_uses_current_pool_expiry() { + let pool = cache::Pool::unbounded().with_expiry(std::time::Duration::from_secs(30)); + let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let mut producer = Producer::new(Info { sequence: 0 }, track::Info::default(), cache); + producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"a")).unwrap(); + producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"b")).unwrap(); + producer.finish().unwrap(); + + let mut consumer = producer.consume(); + consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); + let before = producer.cache_accessed(); + + // The first read prefetched the second frame with a 15-second refresh + // interval. Shortening the shared pool must affect this existing cursor. + let _ = pool.clone().with_expiry(std::time::Duration::from_secs(1)); + crate::model::clock::advance(std::time::Duration::from_millis(600)); + consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); + + assert!(producer.cache_accessed() > before, "the current pool cadence is used"); + } + /// Reading more than one prefetch batch drains every frame in order across the /// batch boundary (the refill starts exactly where the previous batch ended). #[test] From 5ebb30b6490fe238e1674921ed94584daa6b805b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 29 Aug 2026 20:17:05 -0700 Subject: [PATCH 5/9] fix(net): preserve the track refresh cadence Keep prefetched consumers on the stricter of the current pool expiry cadence and the track retention cadence. Add a regression test for a short track max_age with a longer pool expiry. Co-Authored-By: GPT-5 --- rs/moq-net/src/model/group.rs | 42 +++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 68749d3a485..5864bc61b7b 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -818,6 +818,7 @@ impl Producer { prefetch: Prefetch::default(), last_refresh: crate::model::clock::now(), pool: self.cache.pool().clone(), + max_age: self.track.max_age, }), // Untagged: a tagged track attaches the egress meter via `with_meter` // when it hands the consumer to a subscriber/fetch. @@ -1021,9 +1022,13 @@ struct Plain { // window without an access and be expired mid-read. last_refresh: crate::runtime::Instant, - // The shared pool supplies the current refresh cadence. Its expiry can be + // The shared pool supplies the current idle-expiry cadence. Its expiry can be // reconfigured after this cursor is created. pool: cache::Pool, + + // The publisher's media-retention window also bounds refreshes so moving idle + // expiry to the pool does not weaken protection from byte-budget eviction. + max_age: std::time::Duration, } impl Clone for Plain { @@ -1037,6 +1042,7 @@ impl Clone for Plain { prefetch: Prefetch::default(), last_refresh: self.last_refresh, pool: self.pool.clone(), + max_age: self.max_age, } } } @@ -1469,13 +1475,13 @@ impl Plain { } /// Re-stamp the group's access time from the lock-free prefetch path once half - /// the pool's LRU window has passed since this consumer last stamped it. The + /// the shorter of its track retention or the pool's idle window has passed. The /// batch bounds frames, not elapsed time, so without this a reader pacing - /// through a batch could be expired while demonstrably active. Half the window - /// keeps the stamp comfortably inside it while staying rare on the hot path. + /// through a batch could be expired or evicted while demonstrably active. fn refresh_if_stale(&mut self) { let now = crate::model::clock::now(); - if now.duration_since(self.last_refresh) < self.pool.refresh_interval() { + let interval = self.pool.refresh_interval().min(self.max_age / 2); + if now.duration_since(self.last_refresh) < interval { return; } self.state.read().charge.refresh(); @@ -1944,17 +1950,23 @@ mod test { assert!(end.is_none()); } - #[test] - fn prefetch_refresh_uses_current_pool_expiry() { - let pool = cache::Pool::unbounded().with_expiry(std::time::Duration::from_secs(30)); + fn prefetched_consumer(pool: &cache::Pool, max_age: std::time::Duration) -> (Producer, Consumer) { let cache = cache::Track::new(pool.clone(), kio::Weak::new()); - let mut producer = Producer::new(Info { sequence: 0 }, track::Info::default(), cache); + let track = track::Info::default().with_max_age(max_age); + let mut producer = Producer::new(Info { sequence: 0 }, track, cache); producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"a")).unwrap(); producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"b")).unwrap(); producer.finish().unwrap(); let mut consumer = producer.consume(); consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); + (producer, consumer) + } + + #[test] + fn prefetch_refresh_uses_current_pool_expiry() { + let pool = cache::Pool::unbounded().with_expiry(std::time::Duration::from_secs(30)); + let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::MAX); let before = producer.cache_accessed(); // The first read prefetched the second frame with a 15-second refresh @@ -1966,6 +1978,18 @@ mod test { assert!(producer.cache_accessed() > before, "the current pool cadence is used"); } + #[test] + fn prefetch_refresh_honors_track_max_age() { + let pool = cache::Pool::unbounded().with_expiry(std::time::Duration::from_secs(30)); + let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::from_secs(1)); + let before = producer.cache_accessed(); + + crate::model::clock::advance(std::time::Duration::from_millis(600)); + consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); + + assert!(producer.cache_accessed() > before, "the track cadence remains in force"); + } + /// Reading more than one prefetch batch drains every frame in order across the /// batch boundary (the refill starts exactly where the previous batch ended). #[test] From 56363347b19285aaeb314aa4a1b818436f481b3a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 29 Aug 2026 20:32:32 -0700 Subject: [PATCH 6/9] fix(net): honor shortened cache expiry Clamp pending write-driven scan deadlines against the pool current expiry cadence so existing tracks respond promptly when a shared pool is shortened. Add a regression for the default-to-subsecond transition. Co-Authored-By: GPT-5 --- rs/moq-net/src/model/cache.rs | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index ae903b7c415..0267870a093 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -379,14 +379,15 @@ impl Track { } let now = self.pool.now(); + let interval = expiry.clamp(1, EXPIRY_SCAN_TICKS); + let deadline = now.saturating_add(interval); let next = self.next_expiry.load(Ordering::Relaxed); - if now < next { + if now < next && next <= deadline { return false; } - let interval = expiry.clamp(1, EXPIRY_SCAN_TICKS); self.next_expiry - .compare_exchange(next, now.saturating_add(interval), Ordering::Relaxed, Ordering::Relaxed) + .compare_exchange(next, deadline, Ordering::Relaxed, Ordering::Relaxed) .is_ok() } } @@ -695,6 +696,19 @@ mod test { assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); } + #[test] + fn shortening_expiry_rechecks_existing_tracks() { + let pool = Pool::unbounded().with_expiry(DEFAULT_EXPIRY); + let track = Track::new(pool.clone(), kio::Weak::new()); + assert!(track.expiry_due()); + + crate::model::clock::advance(Duration::from_millis(100)); + assert!(!track.expiry_due(), "the original one-second deadline is pending"); + + let _ = pool.clone().with_expiry(Duration::from_millis(100)); + assert!(track.expiry_due(), "the shorter expiry advances the pending scan"); + } + #[test] fn standalone_origin_enables_default_expiry() { assert_eq!(crate::origin::Info::default().pool.expiry(), Some(DEFAULT_EXPIRY)); From 6e23943a5834f0bc52fb662e3ed2ffcb12445746 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 30 Aug 2026 14:18:10 -0700 Subject: [PATCH 7/9] fix(net): avoid no-op expiry wakeups Keep the rotating scan cursor outside observable track state and inspect each candidate window before taking a notifying write guard. Rename the new expiry configurator to a setter so its shared mutation is explicit. --- rs/moq-net/src/model/cache.rs | 57 +++++++++++++------ rs/moq-net/src/model/group.rs | 8 ++- rs/moq-net/src/model/origin.rs | 4 +- rs/moq-net/src/model/track.rs | 100 +++++++++++++++++++++++++++++---- rs/moq-relay/src/cache.rs | 4 +- 5 files changed, 138 insertions(+), 35 deletions(-) diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 0267870a093..86cda2a4164 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -32,7 +32,7 @@ //! process caches into a single policy. use std::sync::Arc; -use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering}; use std::time::Duration; use super::track::TrackState; @@ -64,10 +64,10 @@ const TICK_MS: u64 = 100; /// Default idle window for standalone origins and relays. /// /// A bare [`Pool`] has no idle expiry until one is configured with -/// [`Pool::with_expiry`]. +/// [`Pool::set_expiry`]. pub const DEFAULT_EXPIRY: Duration = Duration::from_secs(30); -/// A shared byte budget that caches charge into; cloning shares the same budget. +/// A shared cache policy and byte budget; cloning shares both. /// /// The pool tracks how many payload bytes are cached across every registered group, /// plus the mean last-access time of the evictable ones. It never evicts on its own: @@ -152,7 +152,7 @@ impl Pool { self.inner.capacity.store(capacity, Ordering::Relaxed); } - /// Set the wall-clock LRU window, returning `self` for chaining. + /// Set the wall-clock LRU window for this pool and all of its clones. /// /// A non-latest cached group that nobody reads or writes for this long is /// reclaimed by its track's next write, surfacing to any remaining reader as @@ -161,13 +161,13 @@ impl Pool { /// timestamps (so a congestion stall can't age content out), while this window /// keeps content nobody is accessing from pinning RAM. `None` disables idle /// reclamation, leaving only the byte budget. A bare pool has no idle expiry; - /// standalone origins and relays configure [`DEFAULT_EXPIRY`]. - pub fn with_expiry(self, expiry: impl Into>) -> Self { + /// standalone origins and relays configure [`DEFAULT_EXPIRY`]. Changes apply to + /// existing tracks because they read the shared policy while writing. + pub fn set_expiry(&self, expiry: impl Into>) { let ms = expiry .into() .map_or(u64::MAX, |expiry| u64::try_from(expiry.as_millis()).unwrap_or(u64::MAX)); self.inner.expiry.store(ms, Ordering::Relaxed); - self } /// The wall-clock LRU window, or `None` when idle content is never reclaimed. @@ -308,6 +308,9 @@ pub(crate) struct Track { // Earliest coarse tick when a frame write may run another expiry scan. next_expiry: AtomicU64, + // Rotating position of the expiry scan over the track's eviction order. + expiry_cursor: AtomicUsize, + // The track that pays this account off, holding the groups being charged. state: kio::Weak, } @@ -319,6 +322,7 @@ impl Track { pool, written: AtomicU64::new(0), next_expiry: AtomicU64::new(0), + expiry_cursor: AtomicUsize::new(0), state, }) } @@ -349,28 +353,44 @@ impl Track { /// Settle eviction debt and expire idle groups from a frame write. /// /// Called with no group lock held (locks are ordered track then group). Cheap - /// until the byte or time gate crosses: relaxed atomics only. This is what makes - /// a track that only appends frames to open groups, never inserting another - /// group, still pay its debt and age its idle content out. + /// until the byte or time gate crosses: relaxed atomics plus a coarse clock read + /// when expiry is enabled. This is what makes a track that only appends frames to + /// open groups, never inserting another group, still pay its debt and age its + /// idle content out. pub(crate) fn settle(&self) { let settle_debt = self.written.load(Ordering::Relaxed) >= WRITE_CHARGE_THRESHOLD; - let expire = self.expiry_due(); - if !settle_debt && !expire { + let scan_expiry = self.expiry_due(); + if !settle_debt && !scan_expiry { return; } // Counts as a producer while it lives, which is why `track::Producer` gates // its teardown on its own clone count rather than the state's. let Some(state) = self.state.upgrade() else { return }; + let expiry = if scan_expiry { + let state = state.read(); + let scan = state.expiry_scan(); + state.expiry_mutation_due(scan).then_some(scan) + } else { + None + }; + if !settle_debt && expiry.is_none() { + return; + } if let Ok(mut state) = state.write() { if settle_debt { state.charge_debt(); } - if expire { - state.evict_expired(); + if let Some(scan) = expiry { + state.evict_expired_scan(scan); } } } + /// Claim the next rotating window in the track's eviction order. + pub(crate) fn next_expiry_scan(&self, width: usize) -> usize { + self.expiry_cursor.fetch_add(width, Ordering::Relaxed) + } + /// Claim the next write-driven expiry scan when its time gate is due. fn expiry_due(&self) -> bool { let expiry = self.pool.expiry_ticks(); @@ -683,14 +703,14 @@ mod test { assert_eq!(pool.expiry(), None); assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); - let pool = pool.with_expiry(Duration::from_secs(1)); + pool.set_expiry(Duration::from_secs(1)); assert_eq!(pool.expiry(), Some(Duration::from_secs(1))); assert_eq!(pool.expiry_ticks(), 10); assert_eq!(pool.refresh_interval(), Duration::from_millis(500)); // Disabled: never reclaimed by idleness, but readers still re-stamp on a // bounded cadence for byte-eviction protection. - let pool = pool.with_expiry(None); + pool.set_expiry(None); assert_eq!(pool.expiry(), None); assert_eq!(pool.expiry_ticks(), u64::MAX); assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); @@ -698,14 +718,15 @@ mod test { #[test] fn shortening_expiry_rechecks_existing_tracks() { - let pool = Pool::unbounded().with_expiry(DEFAULT_EXPIRY); + let pool = Pool::unbounded(); + pool.set_expiry(DEFAULT_EXPIRY); let track = Track::new(pool.clone(), kio::Weak::new()); assert!(track.expiry_due()); crate::model::clock::advance(Duration::from_millis(100)); assert!(!track.expiry_due(), "the original one-second deadline is pending"); - let _ = pool.clone().with_expiry(Duration::from_millis(100)); + pool.set_expiry(Duration::from_millis(100)); assert!(track.expiry_due(), "the shorter expiry advances the pending scan"); } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 5864bc61b7b..d1877072a1d 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1965,13 +1965,14 @@ mod test { #[test] fn prefetch_refresh_uses_current_pool_expiry() { - let pool = cache::Pool::unbounded().with_expiry(std::time::Duration::from_secs(30)); + let pool = cache::Pool::unbounded(); + pool.set_expiry(std::time::Duration::from_secs(30)); let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::MAX); let before = producer.cache_accessed(); // The first read prefetched the second frame with a 15-second refresh // interval. Shortening the shared pool must affect this existing cursor. - let _ = pool.clone().with_expiry(std::time::Duration::from_secs(1)); + pool.set_expiry(std::time::Duration::from_secs(1)); crate::model::clock::advance(std::time::Duration::from_millis(600)); consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); @@ -1980,7 +1981,8 @@ mod test { #[test] fn prefetch_refresh_honors_track_max_age() { - let pool = cache::Pool::unbounded().with_expiry(std::time::Duration::from_secs(30)); + let pool = cache::Pool::unbounded(); + pool.set_expiry(std::time::Duration::from_secs(30)); let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::from_secs(1)); let before = producer.cache_accessed(); diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index e134d8cb8c3..fc62406d382 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -132,9 +132,11 @@ impl Default for Info { /// An unknown origin (id `0`, no loop detection) with no byte target and the /// default idle expiry. This is what a standalone broadcast inherits. fn default() -> Self { + let pool = cache::Pool::unbounded(); + pool.set_expiry(cache::DEFAULT_EXPIRY); Self { id: Origin::UNKNOWN, - pool: cache::Pool::unbounded().with_expiry(cache::DEFAULT_EXPIRY), + pool, cache_duration: Duration::MAX, default_max_age: track::DEFAULT_MAX_AGE, } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c686bba0bb3..66471ea1230 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -48,6 +48,14 @@ const EVICT_SLACK: usize = 64; /// groups, small enough that a write never scans a long queue. const EVICT_SCAN: usize = 4; +/// One bounded pass over the eviction order at a fixed cache time. +#[derive(Clone, Copy)] +pub(super) struct ExpiryScan { + start: usize, + now: u64, + max_ticks: u64, +} + /// Publisher-side properties of a track. /// /// These are fixed by the publisher when the track is created and don't change @@ -191,10 +199,6 @@ pub(crate) struct TrackState { // Incarnation counter for `Slot::stamp`. next_stamp: u32, - // Rotating position of the expiry scan over `evict`, so entries beyond one - // scan window can't be starved by fresh entries in front of them. - expire_cursor: usize, - // The sequence number at which the track was finalized. final_sequence: Option, @@ -571,18 +575,62 @@ impl TrackState { /// track in the pool. /// /// One bounded, rotating scan over the eviction order, which holds every cached - /// group except the protected latest. The cursor persists across calls, so + /// group except the protected latest. The cursor persists in the cache account, so /// entries beyond one scan window can't be starved by fresh (recently read, /// fetched, or written) entries in front of them: every position is revisited /// within a few writes. Expiry throughput is therefore EVICT_SCAN groups per write; the /// byte budget reclaims the remainder under memory pressure. pub(super) fn evict_expired(&mut self) { - let now = self.cache.pool().now(); - let max_ticks = self.cache.pool().expiry_ticks(); + let scan = self.expiry_scan(); + self.evict_expired_scan(scan); + } + /// Describe the next bounded expiry scan without mutating observable track state. + pub(super) fn expiry_scan(&self) -> ExpiryScan { + ExpiryScan { + start: self.cache.next_expiry_scan(EVICT_SCAN), + now: self.cache.pool().now(), + max_ticks: self.cache.pool().expiry_ticks(), + } + } + + /// Whether an expiry scan would change observable track state. + pub(super) fn expiry_mutation_due(&self, scan: ExpiryScan) -> bool { let len = self.evict.len(); if len > 0 { - let start = self.expire_cursor % len; + let start = scan.start % len; + for step in 0..len.min(EVICT_SCAN) { + let (sequence, stamp) = self.evict[(start + step) % len]; + let Some(slot) = self.lookup.get(&sequence) else { + continue; + }; + if slot.stamp != stamp { + continue; + } + if slot.group.is_aborted() + || (Some(sequence) != self.latest_group + && scan.now.saturating_sub(slot.group.cache_accessed()) > scan.max_ticks) + { + return true; + } + } + } + + self.arrival + .front() + .is_some_and(|(sequence, stamp)| !self.is_current(*sequence, *stamp)) + || self + .evict + .front() + .is_some_and(|(sequence, stamp)| !self.is_current(*sequence, *stamp)) + || self.evict.len() > 2 * self.lookup.len() + EVICT_SLACK + } + + /// Apply a scan previously selected by [`Self::expiry_scan`]. + pub(super) fn evict_expired_scan(&mut self, scan: ExpiryScan) { + let len = self.evict.len(); + if len > 0 { + let start = scan.start % len; for step in 0..len.min(EVICT_SCAN) { let (sequence, stamp) = self.evict[(start + step) % len]; let Some(slot) = self.lookup.get(&sequence) else { @@ -598,7 +646,9 @@ impl TrackState { self.lookup.remove(&sequence); continue; } - if Some(sequence) == self.latest_group || now.saturating_sub(slot.group.cache_accessed()) <= max_ticks { + if Some(sequence) == self.latest_group + || scan.now.saturating_sub(slot.group.cache_accessed()) <= scan.max_ticks + { continue; } // Take the group out of the cache and abort it, so any consumer @@ -607,7 +657,6 @@ impl TrackState { let slot = self.lookup.remove(&sequence).unwrap(); let _ = slot.group.abort(Error::Old); } - self.expire_cursor = (start + EVICT_SCAN) % len; } // Trim dead leading arrival entries to advance the subscriber offset. An @@ -637,6 +686,11 @@ impl TrackState { } } + /// Whether `(sequence, stamp)` names the currently cached incarnation. + fn is_current(&self, sequence: u64, stamp: u32) -> bool { + self.lookup.get(&sequence).is_some_and(|slot| slot.stamp == stamp) + } + /// Drop every cached group and reset the eviction bookkeeping. Each group's /// access sample lives in its own charge, released when the group itself dies. fn clear_cache(&mut self) { @@ -4245,7 +4299,9 @@ mod test { /// Mint a track under an origin whose pool has the given wall-clock LRU window. fn track_producer_expiring(name: impl Into>, expiry: impl Into>) -> Producer { - let origin = crate::origin::Info::default().with_pool(cache::Pool::unbounded().with_expiry(expiry)); + let pool = cache::Pool::unbounded(); + pool.set_expiry(expiry); + let origin = crate::origin::Info::default().with_pool(pool); Producer::new( Arc::new(broadcast::Info { origin, @@ -4285,6 +4341,28 @@ mod test { assert!(expired, "a small frame write runs expiry"); } + #[tokio::test] + async fn fresh_expiry_scan_does_not_wake_track_consumers() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let mut producer = track_producer_expiring("test", cache::DEFAULT_EXPIRY); + producer.append_group().unwrap().finish().unwrap(); + let mut live = producer.append_group().unwrap(); + let mut consumer = producer.subscribe(None); + assert_eq!(consumer.assert_group().sequence, 0); + assert_eq!(consumer.assert_group().sequence, 1); + + let woken = Arc::new(AtomicBool::new(false)); + let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); + assert!(consumer.poll_recv_group(&waiter).is_pending()); + + live.write_frame(Timestamp::ZERO, b"x".as_slice()).unwrap(); + assert!( + !woken.load(Ordering::SeqCst), + "a no-op expiry scan must not wake track consumers" + ); + } + #[tokio::test] async fn streaming_frame_write_expires_idle_siblings() { let mut producer = track_producer_expiring("test", Duration::from_secs(1)); diff --git a/rs/moq-relay/src/cache.rs b/rs/moq-relay/src/cache.rs index 14a933c2dec..02eaebb79ba 100644 --- a/rs/moq-relay/src/cache.rs +++ b/rs/moq-relay/src/cache.rs @@ -85,8 +85,8 @@ impl CacheConfig { let pool = match capacity { Some(bytes) => cache::Pool::new(bytes), None => cache::Pool::unbounded(), - } - .with_expiry( + }; + pool.set_expiry( self.duration .map(moq_tokio::Duration::into_std) .unwrap_or(cache::DEFAULT_EXPIRY), From 482d6fa83484c31e5aef2331018690be9175c547 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 30 Aug 2026 15:31:58 -0700 Subject: [PATCH 8/9] refactor(net): configure cache pools at construction Make idle expiry immutable pool configuration while preserving dynamic capacity resizing for the relay memory governor. --- rs/moq-ffi/src/origin.rs | 5 +- rs/moq-ffi/src/test.rs | 4 + rs/moq-net/benches/track.rs | 5 +- rs/moq-net/src/model/cache.rs | 156 +++++++++++++++++---------------- rs/moq-net/src/model/group.rs | 34 +++---- rs/moq-net/src/model/origin.rs | 3 +- rs/moq-net/src/model/track.rs | 18 ++-- rs/moq-net/tests/loom.rs | 12 +-- rs/moq-relay/src/cache.rs | 33 ++++--- 9 files changed, 143 insertions(+), 127 deletions(-) diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 707e180f6ca..83cf9d04d7d 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -172,7 +172,10 @@ impl MoqOriginProducer { fn from_options(options: MoqOriginOptions) -> Self { let mut info = moq_net::origin::Info::new(moq_net::Origin::random()); if let Some(capacity) = options.cache_capacity_bytes { - info = info.with_pool(moq_net::cache::Pool::new(capacity)); + let config = moq_net::cache::Config::default() + .with_capacity(capacity) + .with_expiry(info.pool.expiry()); + info = info.with_pool(moq_net::cache::Pool::new(config)); } Self { inner: spawn(info) } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 0e64b83e99b..d9159825d70 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -144,6 +144,10 @@ fn origin_options_set_cache_capacity() { cache_capacity_bytes: Some(4096), }); assert_eq!(origin.inner().info().pool.capacity(), Some(4096)); + assert_eq!( + origin.inner().info().pool.expiry(), + Some(moq_net::cache::DEFAULT_EXPIRY) + ); } #[test] diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 440e386c207..4d5ff5cbb9a 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -34,7 +34,10 @@ struct Fanout { impl Fanout { fn new(subscribers: usize) -> Self { let mut info = broadcast::Info::default(); - info.origin.pool = cache::Pool::new(CACHE_CAPACITY); + let config = cache::Config::default() + .with_capacity(CACHE_CAPACITY) + .with_expiry(cache::DEFAULT_EXPIRY); + info.origin.pool = cache::Pool::new(config); let mut broadcast = broadcast::Producer::new(info); let track = broadcast.create_track("bench", None).unwrap(); let mut subscribers: Vec<_> = (0..subscribers).map(|_| track.subscribe(None)).collect(); diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 86cda2a4164..3e34f4fc575 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -62,11 +62,39 @@ const READ_BOOST: u64 = 2; const TICK_MS: u64 = 100; /// Default idle window for standalone origins and relays. -/// -/// A bare [`Pool`] has no idle expiry until one is configured with -/// [`Pool::set_expiry`]. pub const DEFAULT_EXPIRY: Duration = Duration::from_secs(30); +/// The initial policy for a [`Pool`]. +/// +/// The default is inert: no byte target and no idle expiry. Use +/// [`Self::with_capacity`] and [`Self::with_expiry`] before creating the pool. +#[derive(Clone, Debug, Default)] +pub struct Config { + capacity: Option, + expiry: Option, +} + +impl Config { + /// Set the initial byte target. `None` leaves it unbounded. + pub fn with_capacity(mut self, capacity: impl Into>) -> Self { + self.capacity = capacity.into(); + self + } + + /// Set the wall-clock LRU window. `None` disables idle reclamation. + /// + /// A non-latest cached group that nobody reads or writes for this long is + /// reclaimed by its track's next write, surfacing to any remaining reader as + /// [`Error::Old`](crate::Error::Old). This is independent of track retention: + /// [`max_age`](crate::track::Info::max_age) uses media timestamps, while this + /// window keeps idle content from pinning memory. The value is fixed when the + /// pool is created. + pub fn with_expiry(mut self, expiry: impl Into>) -> Self { + self.expiry = expiry.into(); + self + } +} + /// A shared cache policy and byte budget; cloning shares both. /// /// The pool tracks how many payload bytes are cached across every registered group, @@ -75,18 +103,24 @@ pub const DEFAULT_EXPIRY: Duration = Duration::from_secs(30); /// pay it, so every operation here is a few atomics with no lock. The capacity is /// therefore a target usage converges toward, not a hard limit: carried debt, capped /// payments, and the always-protected live edge all let usage transiently exceed it. -#[derive(Clone, Default)] +#[derive(Clone)] pub struct Pool { inner: Arc, } +impl Default for Pool { + fn default() -> Self { + Self::unbounded() + } +} + struct Inner { // Total bytes currently charged, including per-entry overhead. used: AtomicU64, // u64::MAX means unbounded. capacity: AtomicU64, // Wall-clock LRU window in milliseconds; u64::MAX means never expire by idleness. - expiry: AtomicU64, + expiry: u64, // Reference point for the coarse tick clock. epoch: crate::runtime::Instant, // Sum and count of last-access ticks across the evictable population, giving a @@ -96,38 +130,32 @@ struct Inner { access_count: AtomicU64, } -impl Default for Inner { - fn default() -> Self { - Self { - used: AtomicU64::new(0), - capacity: AtomicU64::new(u64::MAX), - expiry: AtomicU64::new(u64::MAX), - epoch: crate::model::clock::now(), - access_sum: AtomicU64::new(0), - access_count: AtomicU64::new(0), - } - } -} - impl Pool { - /// Create a pool with a byte target and the default idle expiry. + /// Create a pool from an initial policy. /// /// The budget counts frame payload bytes (plus a small fixed overhead per /// group), not process RSS, and is a convergence target rather than a hard - /// limit; leave headroom when sizing it from real memory. - pub fn new(capacity: u64) -> Self { - let pool = Self::default(); - pool.inner.capacity.store(capacity, Ordering::Relaxed); - pool.inner.expiry.store( - u64::try_from(DEFAULT_EXPIRY.as_millis()).unwrap_or(u64::MAX), - Ordering::Relaxed, - ); - pool + /// limit; leave headroom when sizing it from real memory. The expiry is fixed, + /// while the capacity can later be changed with [`Self::resize`]. + pub fn new(config: Config) -> Self { + let expiry = config + .expiry + .map_or(u64::MAX, |expiry| u64::try_from(expiry.as_millis()).unwrap_or(u64::MAX)); + Self { + inner: Arc::new(Inner { + used: AtomicU64::new(0), + capacity: AtomicU64::new(config.capacity.unwrap_or(u64::MAX)), + expiry, + epoch: crate::model::clock::now(), + access_sum: AtomicU64::new(0), + access_count: AtomicU64::new(0), + }), + } } /// Create a pool that never evicts. This is the [`Default`]. pub fn unbounded() -> Self { - Self::default() + Self::new(Config::default()) } /// The configured byte target, or `None` when unbounded. @@ -152,27 +180,9 @@ impl Pool { self.inner.capacity.store(capacity, Ordering::Relaxed); } - /// Set the wall-clock LRU window for this pool and all of its clones. - /// - /// A non-latest cached group that nobody reads or writes for this long is - /// reclaimed by its track's next write, surfacing to any remaining reader as - /// [`Error::Old`](crate::Error::Old). This is deliberately independent of track - /// retention: [`max_age`](crate::track::Info::max_age) is measured in media - /// timestamps (so a congestion stall can't age content out), while this window - /// keeps content nobody is accessing from pinning RAM. `None` disables idle - /// reclamation, leaving only the byte budget. A bare pool has no idle expiry; - /// standalone origins and relays configure [`DEFAULT_EXPIRY`]. Changes apply to - /// existing tracks because they read the shared policy while writing. - pub fn set_expiry(&self, expiry: impl Into>) { - let ms = expiry - .into() - .map_or(u64::MAX, |expiry| u64::try_from(expiry.as_millis()).unwrap_or(u64::MAX)); - self.inner.expiry.store(ms, Ordering::Relaxed); - } - /// The wall-clock LRU window, or `None` when idle content is never reclaimed. pub fn expiry(&self) -> Option { - match self.inner.expiry.load(Ordering::Relaxed) { + match self.inner.expiry { u64::MAX => None, ms => Some(Duration::from_millis(ms)), } @@ -180,7 +190,7 @@ impl Pool { /// The LRU window in coarse ticks; effectively infinite when disabled. pub(crate) fn expiry_ticks(&self) -> u64 { - match self.inner.expiry.load(Ordering::Relaxed) { + match self.inner.expiry { u64::MAX => u64::MAX, ms => ms / TICK_MS, } @@ -402,7 +412,7 @@ impl Track { let interval = expiry.clamp(1, EXPIRY_SCAN_TICKS); let deadline = now.saturating_add(interval); let next = self.next_expiry.load(Ordering::Relaxed); - if now < next && next <= deadline { + if now < next { return false; } @@ -549,6 +559,11 @@ mod test { Track::new(pool.clone(), kio::Weak::new()).charge() } + fn bounded(capacity: u64) -> Pool { + let config = Config::default().with_capacity(capacity).with_expiry(DEFAULT_EXPIRY); + Pool::new(config) + } + #[test] fn unbounded_never_accrues() { let pool = Pool::unbounded(); @@ -561,14 +576,15 @@ mod test { } #[test] - fn bounded_pool_enables_default_expiry() { - let pool = Pool::new(1000); + fn config_applies_capacity_and_expiry() { + let pool = bounded(1000); + assert_eq!(pool.capacity(), Some(1000)); assert_eq!(pool.expiry(), Some(DEFAULT_EXPIRY)); } #[test] fn accrue_none_under_capacity() { - let pool = Pool::new(1000); + let pool = bounded(1000); let mut charge = charge(&pool); charge.add(500); assert_eq!(pool.accrue(100), None); @@ -576,7 +592,7 @@ mod test { #[test] fn accrue_proportional_over_capacity() { - let pool = Pool::new(1000); + let pool = bounded(1000); let mut charge = charge(&pool); charge.add(2000 - ENTRY_OVERHEAD); // used = 2000, twice the capacity @@ -588,7 +604,7 @@ mod test { #[test] fn average_tracks_evictable_population() { - let pool = Pool::new(1000); + let pool = bounded(1000); assert_eq!(pool.average(), None); pool.access_insert(10); @@ -607,7 +623,7 @@ mod test { #[test] fn charge_raii() { - let pool = Pool::new(1000); + let pool = bounded(1000); let mut charge = charge(&pool); assert_eq!(pool.used(), ENTRY_OVERHEAD); @@ -635,7 +651,7 @@ mod test { #[test] fn accrue_saturates() { // A huge overshoot against a tiny capacity must saturate, not wrap. - let pool = Pool::new(1); + let pool = bounded(1); let mut c = charge(&pool); c.add(1 << 40); assert_eq!(pool.accrue(1 << 40), Some(u64::MAX)); @@ -643,7 +659,7 @@ mod test { #[test] fn charge_counts_gross_writes() { - let track = Track::new(Pool::new(1000), kio::Weak::new()); + let track = Track::new(bounded(1000), kio::Weak::new()); let mut c = track.charge(); c.add(100); c.sub(40); // releases don't refund the gross counter @@ -653,7 +669,7 @@ mod test { #[test] fn charge_owns_access_sample() { - let pool = Pool::new(1000); + let pool = bounded(1000); let mut c = charge(&pool); assert_eq!(pool.average(), None, "not evictable until demoted"); @@ -670,7 +686,7 @@ mod test { #[test] fn refresh_updates_a_counted_sample() { - let pool = Pool::new(1000); + let pool = bounded(1000); let mut c = charge(&pool); c.demote(); c.refresh(); @@ -683,7 +699,7 @@ mod test { #[test] fn refresh_protects_within_a_tick() { - let pool = Pool::new(1000); + let pool = bounded(1000); let mut c = charge(&pool); c.demote(); let average = pool.average().unwrap(); @@ -703,33 +719,19 @@ mod test { assert_eq!(pool.expiry(), None); assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); - pool.set_expiry(Duration::from_secs(1)); + let pool = Pool::new(Config::default().with_expiry(Duration::from_secs(1))); assert_eq!(pool.expiry(), Some(Duration::from_secs(1))); assert_eq!(pool.expiry_ticks(), 10); assert_eq!(pool.refresh_interval(), Duration::from_millis(500)); // Disabled: never reclaimed by idleness, but readers still re-stamp on a // bounded cadence for byte-eviction protection. - pool.set_expiry(None); + let pool = Pool::new(Config::default()); assert_eq!(pool.expiry(), None); assert_eq!(pool.expiry_ticks(), u64::MAX); assert_eq!(pool.refresh_interval(), DEFAULT_EXPIRY / 2); } - #[test] - fn shortening_expiry_rechecks_existing_tracks() { - let pool = Pool::unbounded(); - pool.set_expiry(DEFAULT_EXPIRY); - let track = Track::new(pool.clone(), kio::Weak::new()); - assert!(track.expiry_due()); - - crate::model::clock::advance(Duration::from_millis(100)); - assert!(!track.expiry_due(), "the original one-second deadline is pending"); - - pool.set_expiry(Duration::from_millis(100)); - assert!(track.expiry_due(), "the shorter expiry advances the pending scan"); - } - #[test] fn standalone_origin_enables_default_expiry() { assert_eq!(crate::origin::Info::default().pool.expiry(), Some(DEFAULT_EXPIRY)); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index d1877072a1d..8bc7b900a88 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -817,8 +817,7 @@ impl Producer { end: None, prefetch: Prefetch::default(), last_refresh: crate::model::clock::now(), - pool: self.cache.pool().clone(), - max_age: self.track.max_age, + refresh_interval: self.cache.pool().refresh_interval().min(self.track.max_age / 2), }), // Untagged: a tagged track attaches the egress meter via `with_meter` // when it hands the consumer to a subscriber/fetch. @@ -1022,13 +1021,9 @@ struct Plain { // window without an access and be expired mid-read. last_refresh: crate::runtime::Instant, - // The shared pool supplies the current idle-expiry cadence. Its expiry can be - // reconfigured after this cursor is created. - pool: cache::Pool, - - // The publisher's media-retention window also bounds refreshes so moving idle - // expiry to the pool does not weaken protection from byte-budget eviction. - max_age: std::time::Duration, + // The shorter of half the immutable pool expiry and half the publisher's + // media-retention window. + refresh_interval: std::time::Duration, } impl Clone for Plain { @@ -1041,8 +1036,7 @@ impl Clone for Plain { end: self.end, prefetch: Prefetch::default(), last_refresh: self.last_refresh, - pool: self.pool.clone(), - max_age: self.max_age, + refresh_interval: self.refresh_interval, } } } @@ -1480,8 +1474,7 @@ impl Plain { /// through a batch could be expired or evicted while demonstrably active. fn refresh_if_stale(&mut self) { let now = crate::model::clock::now(); - let interval = self.pool.refresh_interval().min(self.max_age / 2); - if now.duration_since(self.last_refresh) < interval { + if now.duration_since(self.last_refresh) < self.refresh_interval { return; } self.state.read().charge.refresh(); @@ -1964,25 +1957,22 @@ mod test { } #[test] - fn prefetch_refresh_uses_current_pool_expiry() { - let pool = cache::Pool::unbounded(); - pool.set_expiry(std::time::Duration::from_secs(30)); + fn prefetch_refresh_honors_pool_expiry() { + let config = cache::Config::default().with_expiry(std::time::Duration::from_secs(1)); + let pool = cache::Pool::new(config); let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::MAX); let before = producer.cache_accessed(); - // The first read prefetched the second frame with a 15-second refresh - // interval. Shortening the shared pool must affect this existing cursor. - pool.set_expiry(std::time::Duration::from_secs(1)); crate::model::clock::advance(std::time::Duration::from_millis(600)); consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); - assert!(producer.cache_accessed() > before, "the current pool cadence is used"); + assert!(producer.cache_accessed() > before, "the pool cadence is used"); } #[test] fn prefetch_refresh_honors_track_max_age() { - let pool = cache::Pool::unbounded(); - pool.set_expiry(std::time::Duration::from_secs(30)); + let config = cache::Config::default().with_expiry(std::time::Duration::from_secs(30)); + let pool = cache::Pool::new(config); let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::from_secs(1)); let before = producer.cache_accessed(); diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index fc62406d382..e58a563e4b1 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -132,8 +132,7 @@ impl Default for Info { /// An unknown origin (id `0`, no loop detection) with no byte target and the /// default idle expiry. This is what a standalone broadcast inherits. fn default() -> Self { - let pool = cache::Pool::unbounded(); - pool.set_expiry(cache::DEFAULT_EXPIRY); + let pool = cache::Pool::new(cache::Config::default().with_expiry(cache::DEFAULT_EXPIRY)); Self { id: Origin::UNKNOWN, pool, diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 66471ea1230..174fc60cd45 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -4299,8 +4299,7 @@ mod test { /// Mint a track under an origin whose pool has the given wall-clock LRU window. fn track_producer_expiring(name: impl Into>, expiry: impl Into>) -> Producer { - let pool = cache::Pool::unbounded(); - pool.set_expiry(expiry); + let pool = cache::Pool::new(cache::Config::default().with_expiry(expiry)); let origin = crate::origin::Info::default().with_pool(pool); Producer::new( Arc::new(broadcast::Info { @@ -6467,7 +6466,10 @@ mod test { /// Mint a track whose groups charge into a bounded [`cache::Pool`]. fn pooled_producer(capacity: u64) -> (Producer, cache::Pool) { - let pool = cache::Pool::new(capacity); + let config = cache::Config::default() + .with_capacity(capacity) + .with_expiry(cache::DEFAULT_EXPIRY); + let pool = cache::Pool::new(config); let broadcast = broadcast::Info { origin: crate::origin::Info::default().with_pool(pool.clone()), ..Default::default() @@ -6632,7 +6634,10 @@ mod test { /// can't strand the bytes already-created groups keep charging. #[tokio::test] async fn accept_preserves_write_accounting() { - let pool = cache::Pool::new(12_000); + let config = cache::Config::default() + .with_capacity(12_000) + .with_expiry(cache::DEFAULT_EXPIRY); + let pool = cache::Pool::new(config); let broadcast = broadcast::Info { origin: crate::origin::Info::default().with_pool(pool.clone()), ..Default::default() @@ -6814,7 +6819,10 @@ mod test { /// `Info` can't leave already-created groups writing for free. #[tokio::test] async fn pre_accept_backfill_settles_late_writes() { - let pool = cache::Pool::new(2_000); + let config = cache::Config::default() + .with_capacity(2_000) + .with_expiry(cache::DEFAULT_EXPIRY); + let pool = cache::Pool::new(config); let broadcast = broadcast::Info { origin: crate::origin::Info::default().with_pool(pool.clone()), ..Default::default() diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index 22977468136..1bf7a93033a 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -110,14 +110,16 @@ fn subscriber_wakes_parked_demand() { /// a cache leaks, and loom's Arc-leak check catches the reference-cycle flavor of the /// same bug. /// -/// This does not model the charge accounting itself. `cache::Pool` counts with bare -/// `AtomicU64`s and guards its LRU with a `web_async::Lock`, so loom permutes the two -/// tracks only where they meet in kio. Reordering the pool's own counters would need -/// those swapped for loom's too. +/// This does not model the charge accounting itself. `cache::Pool` uses standard +/// atomics, so loom permutes the two tracks only where they meet in kio. Reordering +/// the pool's own counters would need those swapped for loom's atomics too. #[test] fn concurrent_tracks_drain_a_shared_pool() { loom::model(|| { - let pool = cache::Pool::new(512); + let config = cache::Config::default() + .with_capacity(512) + .with_expiry(cache::DEFAULT_EXPIRY); + let pool = cache::Pool::new(config); let mut info = broadcast::Info::new(); info.origin = origin::Info::default().with_pool(pool.clone()); let mut broadcast = info.produce(); diff --git a/rs/moq-relay/src/cache.rs b/rs/moq-relay/src/cache.rs index 02eaebb79ba..ef16c8fc129 100644 --- a/rs/moq-relay/src/cache.rs +++ b/rs/moq-relay/src/cache.rs @@ -82,15 +82,11 @@ impl CacheConfig { /// spawning the headroom governor when configured. Requires a tokio runtime. pub fn init(&self) -> anyhow::Result { let capacity = self.capacity.as_deref().map(parse_limit).transpose()?; - let pool = match capacity { - Some(bytes) => cache::Pool::new(bytes), - None => cache::Pool::unbounded(), - }; - pool.set_expiry( - self.duration - .map(moq_tokio::Duration::into_std) - .unwrap_or(cache::DEFAULT_EXPIRY), - ); + let duration = self.duration.map(moq_tokio::Duration::into_std); + let config = cache::Config::default() + .with_capacity(capacity) + .with_expiry(duration.unwrap_or(cache::DEFAULT_EXPIRY)); + let pool = cache::Pool::new(config); if let Some(headroom) = self.headroom.as_deref() { let headroom = parse_limit(headroom)?; @@ -101,16 +97,13 @@ impl CacheConfig { tracing::info!(capacity, "cache capacity set"); } - if let Some(duration) = self.duration.map(moq_tokio::Duration::into_std) { + if let Some(duration) = duration { tracing::info!(?duration, "cache duration ceiling set"); } Ok(Cache { pool, - duration: self - .duration - .map(moq_tokio::Duration::into_std) - .unwrap_or(Duration::MAX), + duration: duration.unwrap_or(Duration::MAX), }) } } @@ -185,6 +178,18 @@ mod tests { assert_eq!(cache.duration, Duration::MAX); } + #[test] + fn explicit_duration_configures_both_bounds() { + let duration = Duration::from_secs(5); + let config = CacheConfig { + duration: Some(duration.into()), + ..Default::default() + }; + let cache = config.init().unwrap(); + assert_eq!(cache.pool.expiry(), Some(duration)); + assert_eq!(cache.duration, duration); + } + #[test] fn parse_limit_bytes() { assert_eq!(parse_limit("8GiB").unwrap(), 8 * 1024 * 1024 * 1024); From 3a5796cddcbf213bebc53ec925725a7c5d8f6a56 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 30 Aug 2026 16:17:18 -0700 Subject: [PATCH 9/9] fix(net): clamp cache expiry to clock tick --- rs/moq-net/src/model/cache.rs | 48 +++++++++++++++++++++++++---------- rs/moq-net/src/model/group.rs | 5 ++++ rs/moq-net/src/model/track.rs | 4 +-- 3 files changed, 42 insertions(+), 15 deletions(-) diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 3e34f4fc575..1b028b3d62c 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -50,15 +50,17 @@ const ENTRY_OVERHEAD: u64 = 256; /// delivered or fetched group, a frame read, a backfill's birth) outranks both. const WRITE_BOOST: u64 = 1; const READ_BOOST: u64 = 2; +const ACCESS_SHIFT: u32 = 2; /// Milliseconds per tick of the coarse clock behind access timestamps. /// /// Coarse ticks keep the count-weighted timestamp sum far from u64 overflow: the -/// sum is bounded by `elapsed_ticks * live_groups`, live groups are bounded by -/// `used / ENTRY_OVERHEAD`, and twenty years of ticks (6.3e9) times a 64 GiB -/// target's worst-case ~270M groups is ~1.7e18, a tenth of `u64::MAX`. A -/// byte-weighted mean would overflow u64 even at whole-second ticks, which is why -/// the mean is count-weighted. +/// sum is bounded by `elapsed_ticks * live_groups`, plus two low tie-breaking +/// bits. Live groups are bounded by `used / ENTRY_OVERHEAD`, and twenty years of +/// ticks (6.3e9) times a 64 GiB target's worst-case ~270M groups is ~6.8e18 after +/// that encoding, still below half of `u64::MAX`. A byte-weighted mean would +/// overflow u64 even at whole-second ticks, which is why the mean is +/// count-weighted. const TICK_MS: u64 = 100; /// Default idle window for standalone origins and relays. @@ -88,7 +90,8 @@ impl Config { /// [`Error::Old`](crate::Error::Old). This is independent of track retention: /// [`max_age`](crate::track::Info::max_age) uses media timestamps, while this /// window keeps idle content from pinning memory. The value is fixed when the - /// pool is created. + /// pool is created. Values are rounded up to the pool's 100 ms clock tick, with + /// 100 ms as the minimum effective window. pub fn with_expiry(mut self, expiry: impl Into>) -> Self { self.expiry = expiry.into(); self @@ -138,9 +141,13 @@ impl Pool { /// limit; leave headroom when sizing it from real memory. The expiry is fixed, /// while the capacity can later be changed with [`Self::resize`]. pub fn new(config: Config) -> Self { - let expiry = config - .expiry - .map_or(u64::MAX, |expiry| u64::try_from(expiry.as_millis()).unwrap_or(u64::MAX)); + let expiry = config.expiry.map_or(u64::MAX, |expiry| { + let ms = u64::try_from(expiry.as_millis()).unwrap_or(u64::MAX); + if ms == u64::MAX { + return u64::MAX; + } + ms.max(1).div_ceil(TICK_MS).saturating_mul(TICK_MS) + }); Self { inner: Arc::new(Inner { used: AtomicU64::new(0), @@ -225,6 +232,11 @@ impl Pool { elapsed.as_millis() as u64 / TICK_MS } + /// Encode the current clock tick and an access-priority tie breaker. + fn stamp(&self, boost: u64) -> u64 { + self.now().saturating_mul(1 << ACCESS_SHIFT).saturating_add(boost) + } + /// Mean last-access tick across the evictable population, or `None` when it is /// empty. The sum and count are read separately, so the mean is approximate /// under concurrent updates; eviction only needs a rough frontier. @@ -346,7 +358,7 @@ impl Track { pub(crate) fn charge(self: &Arc) -> Charge { self.pool.add(ENTRY_OVERHEAD); self.written.fetch_add(ENTRY_OVERHEAD, Ordering::Relaxed); - let last = self.pool.now(); + let last = self.pool.stamp(0); Charge { track: Some(self.clone()), bytes: ENTRY_OVERHEAD, @@ -482,6 +494,11 @@ impl Charge { self.last.load(Ordering::Relaxed) } + /// Coarse clock tick of the group's last cache access, without its priority bits. + pub(crate) fn accessed_tick(&self) -> u64 { + self.accessed() >> ACCESS_SHIFT + } + /// Enter the group into the evictable population (demoted from the live edge, /// or inserted behind it), sampling its access time into the pool's mean. /// Idempotent. @@ -509,16 +526,16 @@ impl Charge { self.touch(WRITE_BOOST); } - /// Advance the last-access tick to `boost` ticks past the coarse clock. + /// Advance the last-access stamp to the current clock tick with `boost` priority. /// /// The boost breaks ties within one coarse tick: written content outranks /// merely-inserted content, and explicitly read content outranks both, so a /// same-tick access still reads as strictly newer than the population mean of /// weaker accesses. Idempotent within a tick (monotone, never regressing), so - /// repeated accesses can't run ahead of the clock by more than the boost. + /// repeated accesses remain idempotent without advancing the expiry clock. fn touch(&self, boost: u64) { let Some(track) = &self.track else { return }; - let target = track.pool.now().saturating_add(boost); + let target = track.pool.stamp(boost); // `fetch_max` keeps the stamp monotone, and its prior value makes the // paired mean update exact even for back-to-back accesses. let prev = self.last.fetch_max(target, Ordering::Relaxed); @@ -706,6 +723,7 @@ mod test { // A refresh in the same coarse tick still lifts the group above the mean. c.refresh(); assert!(c.accessed() > average); + assert_eq!(c.accessed_tick(), pool.now(), "priority does not advance expiry time"); // Repeated same-tick refreshes are idempotent, not runaway. let stamped = c.accessed(); c.refresh(); @@ -724,6 +742,10 @@ mod test { assert_eq!(pool.expiry_ticks(), 10); assert_eq!(pool.refresh_interval(), Duration::from_millis(500)); + let pool = Pool::new(Config::default().with_expiry(Duration::from_millis(1))); + assert_eq!(pool.expiry(), Some(Duration::from_millis(TICK_MS))); + assert_eq!(pool.expiry_ticks(), 1); + // Disabled: never reclaimed by idleness, but readers still re-stamp on a // bounded cadence for byte-eviction protection. let pool = Pool::new(Config::default()); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 8bc7b900a88..cbbaa52da8c 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -789,6 +789,11 @@ impl Producer { self.state.read().charge.accessed() } + /// Coarse clock tick of the group's last cache access, used by age expiry. + pub(crate) fn cache_accessed_tick(&self) -> u64 { + self.state.read().charge.accessed_tick() + } + /// Enter the group into the evictable population: demoted from the live edge, /// or inserted behind it. Idempotent; a no-op once the group is closed. pub(crate) fn cache_demote(&self) { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 174fc60cd45..7404db12a3c 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -609,7 +609,7 @@ impl TrackState { } if slot.group.is_aborted() || (Some(sequence) != self.latest_group - && scan.now.saturating_sub(slot.group.cache_accessed()) > scan.max_ticks) + && scan.now.saturating_sub(slot.group.cache_accessed_tick()) > scan.max_ticks) { return true; } @@ -647,7 +647,7 @@ impl TrackState { continue; } if Some(sequence) == self.latest_group - || scan.now.saturating_sub(slot.group.cache_accessed()) <= scan.max_ticks + || scan.now.saturating_sub(slot.group.cache_accessed_tick()) <= scan.max_ticks { continue; }