Skip to content
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,6 @@ removed).
- [Bindings name every session code](/quest/m1/ffi-malformed-auth-kind.md) - MALFORMED_AUTH_TOKEN and its siblings reach moq-ffi, moq-c, and the wrappers
- [Unbounded groups](/quest/m1/unbounded-groups/README.md) - groups and frames lose their size caps; the cache sheds parts of a group under pressure and refills the holes in place
- [Next Object on a cold Rust copy](/quest/m1/next-object-cold-copy.md) - a join after an upstream group report starts at the first frame received, never skipping
- [An HLS viewer starts capture](/quest/m1/hls-record-demand.md) - a record-track subscriber counts as demand for its rendition's media
- [gofmt-clean Go wrapper](/quest/m1/go-gofmt.md) - `just go check` fails on unformatted Go
- [moqsrc max-delay](/quest/m1/gst-max-delay.md) - GStreamer's `moqsrc` takes a `max-delay` property instead of a hard-coded 1 s budget
- [JS SETUP rejection ownership](/quest/m1/js-setup-rejection.md) - reproduce an unhandled version-refusal rejection without weakening the refusal
Expand Down
3 changes: 1 addition & 2 deletions quest/m1/eager-encode/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,7 @@ The epic's own work, once the children land:
replay = local subscriber"), [iOS capture](/quest/m2/mobile-capture-ios.md),
[video hardware](/quest/m3/video-hardware.md), and
[time-addressed consumers](/quest/m1/time-addressing/consumers.md)'s
HLS-only-viewer clause. [An HLS viewer starts capture](/quest/m1/hls-record-demand.md)
narrows to the opt-in mode.
HLS-only-viewer clause.

## Required

Expand Down
26 changes: 0 additions & 26 deletions quest/m1/hls-record-demand.md

This file was deleted.

25 changes: 13 additions & 12 deletions rs/moq-audio/src/encode/capture.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2501,33 +2501,34 @@ mod tests {
[Open::Stream(input), Open::Stream(resumed)],
);
let mut live = Vec::new();
let mut records = None;
let mut hls = None;

for samples in [&first, &second] {
let mut track = fixture.subscribe().await;
live.push(fixture.deliver(samples, &mut track, &live).await);
drop(track);
// The break is marked when the second run resumes, and its stop declares the unhinted
// duration.
if records.is_none() && live.len() > 1 {
let hls = fixture.catalog.snapshot().audio.renditions["audio"]
.hls
.clone()
.expect("the audio track declares its HLS records once the first run stops");
records = Some(
moq_mux::hls::Consumer::subscribe(&fixture.consumer, &hls)
.await
.unwrap(),
if hls.is_none() && live.len() > 1 {
hls = Some(
fixture.catalog.snapshot().audio.renditions["audio"]
.hls
.clone()
.expect("the audio track declares its HLS records once the first run stops"),
);
}
wait_for(&mut fixture.publication, Status::Waiting).await;
// Idle past the minimum segment, so each run is listed as its own segment.
tokio::time::sleep(moq_mux::hls::DEFAULT_DURATION + Duration::from_millis(100)).await;
}

let (mut catalog, _consumer) = fixture.finish().await;
let (mut catalog, consumer) = fixture.finish().await;
catalog.finish().unwrap();
let mut records = records.unwrap();
// Read only now: a record reader is demand too, and would have kept the capture from
// idling between the runs.
let mut records = moq_mux::hls::Consumer::subscribe(&consumer, &hls.unwrap())
.await
.unwrap();
let mut listed = Vec::new();
while let Some(event) = records.next().await.unwrap() {
match event {
Expand Down
5 changes: 4 additions & 1 deletion rs/moq-mux/src/container/fmp4/import.rs
Original file line number Diff line number Diff line change
Expand Up @@ -489,7 +489,10 @@ impl<E: crate::catalog::hang::CatalogExt> Import<E> {

// Enroll every track for HLS records: passthrough writes groups by hand (no
// `container::Producer`), so the recorder is fed directly at each fragment.
let recorder = self.catalog.enroll(track.name(), None)?;
let mut recorder = self.catalog.enroll(track.name(), None)?;
if let Some(recorder) = recorder.as_mut() {
recorder.lend(&track);
}

// Whatever the descriptor declared (a bitrate) is authoritative; the rest is filled by
// `estimate` as fragments arrive.
Expand Down
8 changes: 6 additions & 2 deletions rs/moq-mux/src/container/producer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -425,8 +425,12 @@ where
self
}

/// Report each written group through `recorder` into the track's HLS records.
pub(crate) fn with_recorder(mut self, recorder: Option<crate::hls::Recorder>) -> Self {
/// Report each written group through `recorder` into the track's HLS records, whose readers
/// count as demand for this track.
pub(crate) fn with_recorder(mut self, mut recorder: Option<crate::hls::Recorder>) -> Self {
if let Some(recorder) = recorder.as_mut() {
recorder.lend(&self.inner);
}
self.recorder = recorder;
self
}
Expand Down
147 changes: 146 additions & 1 deletion rs/moq-mux/src/hls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@
//! rendition's records and yields decoded [`Event`]s. On the wire each record track is a
//! [`compress`](moq_net::track::Info::compress)ed [`moq_json::window`] whose groups restate the
//! recent records.
//!
//! An edge reads only the records and fetches media per segment request, so it never subscribes to
//! the media. A record track's subscribers therefore count as demand for its media track: while
//! any remain, a local subscription keeps the media wanted, so an on-demand publisher produces it.

use std::collections::{BTreeMap, VecDeque};
use std::sync::{Arc, Mutex};
Expand Down Expand Up @@ -589,7 +593,7 @@ impl Tracks {
live
}
};
Ok(Recorder { live })
Ok(Recorder { live, lend: None })
}

/// The record track and nominal duration advertised for `name`, once its duration is known.
Expand Down Expand Up @@ -671,16 +675,99 @@ fn round(duration: Duration) -> Duration {
Duration::from_millis(units(duration))
}

/// Lends a record track's demand to its media track: while anyone subscribes to the records, a
/// local subscription keeps the media wanted, so an on-demand publisher produces the media that an
/// HLS export, which reads only the records, describes and fetches.
///
/// Driven by the record track's wakeups rather than a task, since nothing here owns a runtime. A
/// wake polls inline on the waking thread, reading the record track, so it relies on kio and
/// moq-net waking a track's waiters only once its lock is released. The waker holds this weakly, so
/// dropping the [`Recorder`] ends the subscription and the registration together. Both track
/// handles are weak, so neither keeps its track open.
struct Lend {
records: moq_net::track::Demand,
media: moq_net::track::Consumer,
/// The subscription held while the records are wanted. Never polled: holding it is the demand.
held: Option<moq_net::track::Subscribing>,
waiter: kio::Waiter,
}

impl Lend {
fn new(records: moq_net::track::Demand, media: moq_net::track::Consumer) -> Arc<Mutex<Self>> {
let lend = Arc::new_cyclic(|weak| {
let waker = std::task::Waker::from(Arc::new(LendWaker(weak.clone())));
Mutex::new(Self {
records,
media,
held: None,
waiter: kio::Waiter::new(waker),
})
});
Self::poll(&lend);
lend
}

/// Follow the record track's demand until it next changes.
fn poll(lend: &Mutex<Self>) {
let mut lend = lend.lock().unwrap();
let lend = &mut *lend;
loop {
match lend.records.poll_wanted_changed(&lend.waiter) {
Poll::Pending => return,
Poll::Ready(Ok(Some(_))) => {
if lend.held.is_none() {
lend.held = Some(lend.media.subscribe(None).into_inner());
}
}
Poll::Ready(Ok(None)) => lend.held = None,
Poll::Ready(Err(_)) => {
lend.held = None;
return;
}
}
}
}
}

/// Re-polls a [`Lend`] when its record track's demand changes.
struct LendWaker(std::sync::Weak<Mutex<Lend>>);

impl std::task::Wake for LendWaker {
fn wake(self: Arc<Self>) {
self.wake_by_ref();
}

fn wake_by_ref(self: &Arc<Self>) {
if let Some(lend) = self.0.upgrade() {
Lend::poll(&lend);
Comment thread
kixelated marked this conversation as resolved.
Resolved
}
}
}

/// Reports one track's frames into its live record track.
///
/// Move-only: it is the track's reporting handle, minted by [`Tracks::track`] and held by a
/// rendition's [`container::Producer`](crate::container::Producer). Dropping it stops the open
/// segment; the record track stays open until [`Tracks::finish`].
pub(crate) struct Recorder {
live: Arc<Mutex<Live>>,
/// Lends the record track's demand to the media track, once [`Self::lend`] names it.
lend: Option<Arc<Mutex<Lend>>>,
}

impl Recorder {
/// Keep `media`, the track this recorder reports, wanted while anyone subscribes to its
/// records, so an HLS export that reads only the records still starts an on-demand publisher.
/// The demand ends when the record track's last subscriber leaves, or this recorder drops.
pub fn lend(&mut self, media: &moq_net::track::Producer) {
let records = {
let live = self.live.lock().unwrap();
live.output.as_ref().map(|output| output.track.demand())
};
// A record track that already failed has no readers to lend for.
self.lend = records.map(|records| Lend::new(records, media.consume()));
}

/// The track's fixed nominal segment duration, once known.
pub fn declared(&self) -> Option<Duration> {
self.live.lock().unwrap().segmenter.declared()
Expand Down Expand Up @@ -1181,6 +1268,64 @@ mod test {
assert_eq!(records, [(0, 0, false), (1, 1, true), (2, 0, false), (3, 1, true)]);
}

/// A record track's readers are demand for its media, so an HLS export, which subscribes only to
/// the records, starts an on-demand publisher, and its leaving stops it.
#[tokio::test]
async fn record_readers_want_the_media() {
let broadcast = moq_net::broadcast::Info::new().produce();
let media = broadcast.create_track("video", None).unwrap();
let demand = media.demand();
let tracks = Tracks::new(&broadcast);
let mut recorder = tracks.track("video", hinted()).unwrap();
recorder.lend(&media);
assert_eq!(demand.wanted(), None, "nobody reads the records yet");

let hls = tracks.hls("video").unwrap();
let records = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap();
assert!(demand.wanted().is_some(), "a record reader wants the media");
let again = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap();
drop(records);
assert!(demand.wanted().is_some(), "another reader remains");
drop(again);
assert_eq!(demand.wanted(), None, "the last reader left");

// Dropping the recorder ends the lend, even with a reader still on the records.
let _records = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap();
assert!(demand.wanted().is_some());
drop(recorder);
assert_eq!(demand.wanted(), None, "the recorder is gone");
}

/// A join over the record track's refresh ratio is answered by the next record's fresh group,
/// whose demand wake reaches the lend only once the track's lock is released, not under it.
#[tokio::test]
async fn a_refreshing_join_keeps_lending() {
let broadcast = moq_net::broadcast::Info::new().produce();
let media = broadcast.create_track("video", None).unwrap();
let demand = media.demand();
let tracks = Tracks::new(&broadcast);
let mut recorder = tracks.track("video", hinted()).unwrap();
recorder.lend(&media);

let hls = tracks.hls("video").unwrap();
let _first = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap();
// Enough records that a join outweighs the refresh ratio and asks for a fresh group.
for group in 0..64 {
recorder.frame(group, ms(group * 4_000));
}
let records = broadcast.consume().track("video.hls").unwrap();
let before = records.subscribe(None).await.unwrap().largest().await;
let _late = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap();
recorder.frame(64, ms(64 * 4_000));

let after = records.subscribe(None).await.unwrap().largest().await;
assert!(
after.map(|at| at.group) > before.map(|at| at.group),
"the join was answered with a fresh group"
);
assert!(demand.wanted().is_some(), "the readers still want the media");
}

#[test]
fn a_taken_record_track_name_fails_enrollment() {
let broadcast = moq_net::broadcast::Info::new().produce();
Expand Down
40 changes: 38 additions & 2 deletions rs/moq-net/src/model/track.rs
Original file line number Diff line number Diff line change
Expand Up @@ -489,6 +489,10 @@ pub(crate) struct TrackState {
// Kept here (rather than threaded through every handle) so any holder reaches it.
subscriptions: kio::Lock<Subscriptions>,

// Demand wakes a write owes, fired once the state guard is released (see
// [`Self::deferred`]). A woken waker may read this track, so none fires under its lock.
deferred: Vec<kio::WaiterList>,

// The fills readers queued for groups they miss (see [`Fill`]), same reasoning: a miss
// queues here and a `Requests` drains.
fills: kio::Shared<FillState>,
Expand Down Expand Up @@ -1902,11 +1906,21 @@ impl TrackState {
/// changes it, even one below a reached end.
///
/// `answers` when it is a group subscribers receive, which answers a pending refresh.
///
/// The demand wakes it owes wait in [`Self::deferred`] for the caller to fire once its guard
/// is released.
fn advance(&mut self, sequence: u64, answers: bool) {
self.max_sequence = Some(self.max_sequence.map_or(sequence, |max| max.max(sequence)));
self.cache.advance_largest(Position::group(sequence));
let mut wakes = self.subscriptions.lock().wrote(sequence, answers);
wakes.wake();
let wakes = self.subscriptions.lock().wrote(sequence, answers);
if !wakes.is_empty() {
self.deferred.push(wakes);
}
}

/// Take the wakes [`Self::advance`] deferred, to fire once the state guard is released.
pub(super) fn deferred(&mut self) -> Deferred {
Deferred(std::mem::take(&mut self.deferred))
}

/// The sequence the next append takes: one past this track's own writes.
Expand Down Expand Up @@ -2749,6 +2763,18 @@ impl TrackState {
}
}

/// Demand wakes taken out of the track state, fired once its guard is gone.
#[must_use = "fire the wakes once the guard is released"]
pub(super) struct Deferred(Vec<kio::WaiterList>);

impl Deferred {
pub(super) fn wake(self) {
for mut wakes in self.0 {
wakes.wake();
}
}
}

/// Record `err` and close the track, the shared tail of every abort, returning the open
/// groups to abort once the guard is gone.
fn commit_abort(mut state: kio::Mut<'_, TrackState>, err: Error) -> OpenGroups {
Expand Down Expand Up @@ -2970,6 +2996,9 @@ impl Producer {
}
state.cap(&group.handle())?;
state.commit_group(&group.handle());
let deferred = state.deferred();
drop(state);
deferred.wake();
Ok(group)
}

Expand All @@ -2993,6 +3022,9 @@ impl Producer {
group::Producer::new(group::Info { sequence }, track, state.cache.clone()).with_meter(self.stats.meter());
state.cap(&group.handle())?;
state.commit_group(&group.handle());
let deferred = state.deferred();
drop(state);
deferred.wake();

Ok(group)
}
Expand Down Expand Up @@ -3053,7 +3085,9 @@ impl Producer {
meter.datagram(datagram.stored_len());
state.push_datagram(datagram);
let cache = state.cache.clone();
let deferred = state.deferred();
drop(state);
deferred.wake();
cache.settle(None);
Ok(sequence)
}
Expand Down Expand Up @@ -3103,7 +3137,9 @@ impl Producer {
meter.datagram(datagram.stored_len());
state.push_datagram(datagram);
let cache = state.cache.clone();
let deferred = state.deferred();
drop(state);
deferred.wake();
cache.settle(None);
Ok(())
}
Expand Down
Loading
Loading