diff --git a/js/hang/src/container/consumer.nonsequential.test.ts b/js/hang/src/container/consumer.nonsequential.test.ts index ac379567042..c0240f07f64 100644 --- a/js/hang/src/container/consumer.nonsequential.test.ts +++ b/js/hang/src/container/consumer.nonsequential.test.ts @@ -1,6 +1,6 @@ import { afterEach, beforeEach, expect, test } from "bun:test"; import { type Installed, Manual, type Micro, Milli, Nano } from "@moq/clock"; -import { Time, Track, Varint } from "@moq/net"; +import { type Group, Time, Track, Varint } from "@moq/net"; import { Consumer } from "./consumer.ts"; import { Format as LegacyFormat } from "./legacy.ts"; @@ -92,3 +92,44 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame consumer.close(); }); + +// A skip past a group already begun records where it ended, as Rust's `skip_to` does, so a later group +// continuing its timeline reads on without a gap. Sparse sequence numbers leave only the timeline to +// prove nothing is missing, and the empty group in between says nothing of it. +test("Consumer reads on without a gap past a group it skipped", async () => { + const track = new Track.Producer("test"); + const consumer = new Consumer(track.subscribe(), { + format: new LegacyFormat("audio"), + delay: { max: 500 as Milli }, + }); + const write = (group: Group.Producer, timestamps: number[]) => { + for (const timestamp of timestamps) { + group.writeFrame({ + payload: encodeLegacyFrame(timestamp as Micro, new Uint8Array([0x01])), + timestamp: Time.Timestamp.now(), + }); + } + }; + + const first = track.createGroup(0n); + write(first, [0, 100_000, 200_000, 300_000, 400_000]); + for (let i = 0; i < 5; i++) expect((await nextFrame(consumer))?.group).toBe(0n); + // The first group finishes, read to its end but not yet passed, followed by an adjacent empty group + // and a group continuing its timeline. That group's start falls past the age bound behind the newest + // frame, so the age skip passes the first group cleanly, then the empty one, which ends without a + // frame and leaves only the skipped group's end to show the timeline goes on. + first.finish(); + const empty = track.createGroup(1n); + await clock.advance(Nano.zero); + const last = track.createGroup(20n); + write(last, [400_000, 1_000_000]); + last.finish(); + empty.finish(); + await clock.advance(Nano.zero); + const next = await poll(consumer.next()); + expect(next).toMatchObject({ kind: "frame", group: 20n }); + + consumer.close(); + track.finish(); + track.close(); +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 32648589f9e..dcb4913d254 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -196,7 +196,7 @@ export class Consumer { #hole?: Instant; // Presentation end (max PTS + duration) of the group we most recently advanced past, so next()'s // promotion guard can tell a timeline-continuous next group from one sitting after a gap. - // Maintained only via #recordPresented; see its comment for the invariant. + // Written only by #pass, which every move past a group goes through. #presentedEnd?: Micro; // Group of the last media frame next() returned, so an endpoint after it reads as that frame's // duration rather than a declared stop. @@ -518,14 +518,13 @@ export class Consumer { return group.consumer.closed.peek() ?? null; } - // Record where a group's content ends as the cursor advances past it. next()'s promotion guard - // compares the following group's first PTS against this to tell an unbroken timeline from a real - // gap, so EVERY site that moves #active past a group must call this; a site that forgets leaves a - // stale end behind and silently blocks the next contiguous group forever. A group with no frames - // (empty, or errored before the first one) says nothing about the timeline, so it leaves the last - // known end in place rather than wiping it. - #recordPresented(group: Group): void { + // Move the cursor past `group` to `next`, recording where the group's content ends. next()'s + // promotion guard compares the following group's first PTS against that to tell an unbroken + // timeline from a real gap. A group with no frames (empty, or errored before the first one) says + // nothing about the timeline, so it leaves the last known end in place rather than wiping it. + #pass(group: Group, next: bigint | undefined): void { if (group.end !== undefined) this.#presentedEnd = group.end; + this.#active = next; } // Skip the oldest groups while the buffered span exceeds the max delay. Returns true if any was skipped. @@ -597,7 +596,7 @@ export class Consumer { this.#groups.shift(); stamped--; - this.#active = this.#groups[0]?.consumer.sequence; + this.#pass(first, this.#groups[0]?.consumer.sequence); const next = this.#groups[0]; const nextStart = next?.frames.at(0)?.timestamp ?? next?.end; @@ -668,8 +667,7 @@ export class Consumer { this.#groups.shift(); console.warn(`skipping covered group: ${active.consumer.sequence} -> ${next.consumer.sequence}`); - this.#recordPresented(active); - this.#active = next.consumer.sequence; + this.#pass(active, next.consumer.sequence); this.#discard(active); this.#updateBuffered(); @@ -701,8 +699,7 @@ export class Consumer { const nextStart = next.frames.at(0)?.timestamp; const marker = !head.empty && !head.media; if (marker || !ptsContiguous(head.end ?? this.#presentedEnd, nextStart)) this.#lost = true; - this.#recordPresented(head); - this.#active = next.consumer.sequence; + this.#pass(head, next.consumer.sequence); this.#discard(head); this.#updateBuffered(); @@ -939,9 +936,8 @@ export class Consumer { // the hole expired -- every group through the skip path, i.e. constant stutter. A real // PTS gap is different: an intermediate group may still be in transit, so fall back to // +1 there (the promotion guard above fixes it up once a continuous group arrives). - this.#recordPresented(head); const next = this.#groups.at(0); - this.#active = continues(head, next) ? next.consumer.sequence : seq + 1n; + this.#pass(head, continues(head, next) ? next.consumer.sequence : seq + 1n); } head.consumer.close(); this.#release(head); diff --git a/quest/m1/explicit-state/README.md b/quest/m1/explicit-state/README.md index 6039e2bbfc7..f672dab642d 100644 --- a/quest/m1/explicit-state/README.md +++ b/quest/m1/explicit-state/README.md @@ -73,7 +73,7 @@ which collapses that state and waits on [Drop set](/quest/m1/drop-set.md). - [js/qmux close](/quest/m1/explicit-state/qmux-close.md) - a graceful remote close ends qmux streams cleanly - [FFI handle state](/quest/m1/explicit-state/ffi-state.md) - FFI handles hold one state each: video follow under one lock, requests answered once, drivers Cancelled after shutdown - [moq-net phase data](/quest/m1/explicit-state/net-phases.md) - moq-net's session and subscription state machines keep each phase's data in its variant -- [moq-mux and moq-gst lifecycles](/quest/m1/explicit-state/mux-gst.md) - export sources, TS and fMP4 export tracks, and gst pads are explicit state +- [TS and fMP4 export lifecycles](/quest/m1/explicit-state/mux-gst.md) - the TS export program and tracks and the fMP4 export track are explicit state ## Related diff --git a/quest/m1/explicit-state/mux-gst.md b/quest/m1/explicit-state/mux-gst.md index f4f0b63c0de..ead70fb397a 100644 --- a/quest/m1/explicit-state/mux-gst.md +++ b/quest/m1/explicit-state/mux-gst.md @@ -1,57 +1,38 @@ -# [M] moq-mux and moq-gst lifecycles +# [M] TS and fMP4 export lifecycles ## Goal -The lifecycles of moq-mux and moq-gst export and ingest are explicit state: -export sources, TS and fMP4 export tracks and programs, the HLS segment -window, the container consumer's startup, and the GStreamer sink and source -pads. Each phase's data lives in its variant, and no `.expect()` or flag -ordering stands in for a phase. +The TS and fMP4 export lifecycles in moq-mux are explicit state: the TS +export program and its tracks, the TS follower, passthrough, and group +buffer, and the fMP4 export track. Each phase's data lives in its variant, +and no `.expect()` or flag ordering stands in for a phase. ## Plan The shared decisions are in the [epic](/quest/m1/explicit-state/README.md). -No confirmed bug is folded into this child. Reproduce these two first: +No confirmed bug is folded into this child. Two suspected ones were checked +and are not defects: -- **fMP4 export** (`rs/moq-mux/src/container/fmp4/export.rs`): a track that - ends before it is ever described, while the catalog stays live, may keep - `init_ready()` false forever. -- **TS export track** (`rs/moq-mux/src/container/ts/export.rs`): - - Withdrawing a track keeps its parked frames, so it can become both - `withdrawn` and `listed`. - - `finished` carries five meanings, and the "gone" predicate ANDs eight - conditions. +- An fMP4 export track that ends before it is described, while the catalog + stays live, keeps `init_ready()` false. That wait is bounded: once other + tracks have media it fails at the init queue limit, naming the track. + Otherwise the live catalog can still move the rendition. +- A withdrawn TS track whose parked frames already went out stays listed. + This is intended, and `revision_test.rs` covers it. Instances to redesign: -- **TS export `Program`**: `catalog`, `catalog_ended`, `cataloged`, - `retired`, `left`, `psi`, and others. `resume` hand-resets six fields. -- **`ExportSource`** (`container/source.rs`): `media`, `priority_control`, - `instance`, `live`, and `after` belong inside the `SourceState` variants. -- **Container `Consumer`** (`container/consumer.rs`): the startup phase and - the `track`/`track_error` reader state. The JS twin is - `js/hang/src/container/consumer.ts`, whose `#checkMaxDelay` moves `#active` - without `#recordPresented`. Change both together. -- **HLS** (`rs/moq-hls`): - - The segment window keeps `ended`, `cut`, and `failed`, and `push` after - `end()` isn't refused. - - Retiring a `Claim` takes two locks. - - The importer's `TrackState` generation fields. -- **Catalog publish gate** (`catalog/producer.rs`): `Reservations` writes its - predicate twice, in two shapes. -- **TS `Follower.refused`** belongs inside `Serving`. The TS `Passthrough` - start and clock, and the `GroupBuffer` content kind, also become explicit. -- **moq-gst sink pads** (`rs/moq-gst/src/sink/request_pad.rs`, `pad.rs`, - `imp.rs`): - - The `ended` bool means something different from `Status::Ended`. - - `releasing` is cleared after removal. - - The element's `drained`/`lingering`/`eos_delivered` and the pad's - `reserved`/`track`/`catalog`/`caps`/`failed` encode phases. -- **moq-gst source** `Entry`'s `reader`/`draining`. -- **Others**: - - The RTMP `ServerSession`: the connected app name belongs inside - `SessionState::Connected`. - - The moq-webrtc ICE `Agent`: its failure isn't sticky. - - The p2p channel handout. - - The jitter `Track`. +- **TS export `Program`** (`rs/moq-mux/src/container/ts/export.rs`): + `catalog`, `catalog_ended`, `cataloged`, `retired`, `left`, `psi`, and + others. `resume` hand-resets six fields. +- **TS export track**: `finished` carries five meanings, and the "gone" + predicate ANDs eight conditions. +- **TS `Follower.refused`** (`ts/follower.rs`) belongs inside `Serving`. The + TS `Passthrough` start and clock, and the `GroupBuffer` content kind, also + become explicit. +- **fMP4 export track** (`rs/moq-mux/src/container/fmp4/export.rs`): + `source`, `described`, `finished`, `resume`, and `group_finished` encode + its phases. Land after + [moq-dev/moq#7916](https://github.com/moq-dev/moq/pull/7916), which + rewrites this file. diff --git a/rs/moq-gst/src/sink/imp.rs b/rs/moq-gst/src/sink/imp.rs index 5b405e54259..f27e66b3a58 100644 --- a/rs/moq-gst/src/sink/imp.rs +++ b/rs/moq-gst/src/sink/imp.rs @@ -22,7 +22,7 @@ use hang::moq_net; use super::listed::{Listed, Watch}; use super::pad::{CapsOutcome, Names, ProducerOptions, PushOutcome, caps_supported}; -use super::request_pad::{MoqSinkPad, Notifications, PadLifecycle}; +use super::request_pad::{MoqSinkPad, Notifications, PadLifecycle, Phase}; use super::session::{ CAT, Completion, CompletionHandle, ConnectionStatus, RUNTIME, ResolvedSettings, Session, SessionRegistration, notify, sessions_structure, @@ -77,13 +77,21 @@ struct State { names: Names, /// How long a clean end keeps the finished broadcast up before its EOS. linger: Duration, - /// Whether the finished broadcast closed, so the EOS it owes may go out. - drained: bool, - /// The task serving the finished broadcast for its linger, aborted on stop. - lingering: Option, - /// Whether this publication's single EOS message already went out. One per publication, not per - /// entry to PLAYING: a finished publication is terminal here, so there is nothing to announce twice. - eos_delivered: bool, + /// How far a clean finish has wound the publication down. + drain: Drain, +} + +/// How far a cleanly finished publication has wound down, ending in its one EOS. +enum Drain { + /// The publication has not finished cleanly. + Open, + /// Serving the finished broadcast for its linger, until the task ends or a stop aborts it. + Lingering(tokio::task::AbortHandle), + /// The finished broadcast closed, so the EOS it owes may go out. + Closed, + /// The EOS went out. One per publication, not per entry to PLAYING: a finished publication is + /// terminal here, so there is nothing to announce twice. + Posted, } impl State { @@ -117,10 +125,10 @@ fn claim_eos(control: &mut Control) -> Posted { return Posted::Nothing; }; // Only a clean finish drains, so a drained publication ended with EOS. - if state.eos_delivered || !state.drained { + if !matches!(state.drain, Drain::Closed) { return Posted::Nothing; } - state.eos_delivered = true; + state.drain = Drain::Posted; Posted::Message { session: state.session.completion(), kind: MessageKind::Eos, @@ -484,10 +492,10 @@ impl ElementImpl for MoqSink { let mut control = self.control.lock().unwrap(); control.admissions.remove(sink_pad); let mut lifecycle = sink_pad.lifecycle(); - if lifecycle.releasing { + if lifecycle.is_released() { return; } - lifecycle.releasing = true; + lifecycle.phase = Phase::Released; if let Err(err) = lifecycle.media.finalize() { gst::warning!(CAT, "finalize on release {}: {err:?}", pad.name()); } @@ -496,7 +504,6 @@ impl ElementImpl for MoqSink { if self.obj().remove_pad(pad).is_ok() { self.obj().child_removed(pad, pad.name().as_str()); } - sink_pad.lifecycle().releasing = false; sink_pad.notify_changes(changes); let finished = { let mut control = self.control.lock().unwrap(); @@ -600,9 +607,7 @@ impl MoqSink { watch, names: Names::default(), linger, - drained: false, - lingering: None, - eos_delivered: false, + drain: Drain::Open, }); let pads = self.pads_locked(&control); let state = control.live.as_ref().unwrap(); @@ -614,7 +619,7 @@ impl MoqSink { let mut lifecycle = pad.lifecycle(); let changes = lifecycle.reset(); lifecycle.completion = Some(completion.clone()); - if !lifecycle.releasing { + if !lifecycle.is_released() { lifecycle.media.reserve(catalog, wall.clone(), &state.names); } changes @@ -683,7 +688,7 @@ impl MoqSink { gst::warning!(CAT, "finalize on stop: {err:?}"); } // Close the broadcast before reaping the session task. This also ends a linger early. - if let Some(lingering) = state.lingering.take() { + if let Drain::Lingering(lingering) = &state.drain { lingering.abort(); } state.route.broadcast().close(); @@ -725,7 +730,7 @@ impl MoqSink { let _rt = RUNTIME.enter(); let (outcome, changes) = { let mut lifecycle = pad.lifecycle(); - let Some(completion) = lifecycle.completion.as_ref().filter(|_| !lifecycle.releasing) else { + let Some(completion) = lifecycle.completion.as_ref().filter(|_| !lifecycle.is_released()) else { return Err(gst::FlowError::Flushing); }; // The element's own end comes before the pad's: a broken rendition is isolated so the others @@ -802,7 +807,7 @@ impl MoqSink { true => None, false => { let mut lifecycle = sink_pad.lifecycle(); - match lifecycle.releasing { + match lifecycle.is_released() { true => None, false => { lifecycle.media.invalidate(); @@ -826,7 +831,7 @@ impl MoqSink { && let Some(catalog) = state.catalog.as_ref() { let mut lifecycle = sink_pad.lifecycle(); - if lifecycle.releasing { + if lifecycle.is_released() { return false; } Some(observe_caps(state, catalog, sink_pad, &mut lifecycle, &caps)) @@ -847,7 +852,7 @@ impl MoqSink { let control = self.control.lock().unwrap(); let completion = control.live.as_ref().map(|state| state.session.completion()); let mut lifecycle = sink_pad.lifecycle(); - if !lifecycle.releasing { + if !lifecycle.is_released() { // The link is which publication the pad belongs to, not whether that publication is // still open. Dropping it after the end would answer the next buffer with Flushing // instead of the terminal result it earned. @@ -871,8 +876,8 @@ impl MoqSink { if let Some(state) = control.live.as_ref().filter(|state| state.is_open()) { let _rt = RUNTIME.enter(); let mut lifecycle = sink_pad.lifecycle(); - if !lifecycle.releasing { - lifecycle.ended = true; + if !lifecycle.is_released() { + lifecycle.phase = Phase::Eos; retired = lifecycle.retire_bandwidth(); if let Some(catalog) = &state.catalog && let Err(err) = lifecycle.media.end_unresolved(catalog) @@ -907,8 +912,8 @@ impl MoqSink { if let Some(state) = control.live.as_ref().filter(|state| state.is_open()) { let _rt = RUNTIME.enter(); let mut lifecycle = sink_pad.lifecycle(); - if !lifecycle.releasing { - lifecycle.ended = false; + if !lifecycle.is_released() { + lifecycle.phase = Phase::Streaming; if let Some(catalog) = &state.catalog { lifecycle.media.reserve(catalog, state.wall.clone(), &state.names); } @@ -929,10 +934,10 @@ impl MoqSink { Some(state) => { let _rt = RUNTIME.enter(); let mut lifecycle = sink_pad.lifecycle(); - match lifecycle.releasing { + match lifecycle.is_released() { true => None, false => { - lifecycle.ended = false; + lifecycle.phase = Phase::Streaming; lifecycle.media.flush(); let catalog = state.catalog.as_ref(); if let Some(catalog) = catalog { @@ -995,9 +1000,9 @@ impl MoqSink { let completion = control.live.as_ref().map(|state| state.session.completion()); let mut lifecycle = pad.lifecycle(); // Decided here, holding both locks. `owns_pad` cannot answer it: a pad stays the element's - // between being marked `releasing` and being removed, and a second look at the publication + // between being marked released and being removed, and a second look at the publication // would read a different instant than the one this confirmation ran in. - let admission = match lifecycle.releasing { + let admission = match lifecycle.is_released() { true => Admission::Rejected, false => { let failed = completion @@ -1028,7 +1033,7 @@ impl MoqSink { .into_iter() .filter_map(|pad| pad.downcast::().ok()) .collect::>(); - let all_ended = !pads.is_empty() && pads.iter().all(|pad| pad.lifecycle().ended); + let all_ended = !pads.is_empty() && pads.iter().all(|pad| pad.lifecycle().phase == Phase::Eos); if !all_ended || !state.is_open() { return Finished::default(); } @@ -1039,7 +1044,7 @@ impl MoqSink { let mut closed = Vec::new(); for pad in pads { let mut lifecycle = pad.lifecycle(); - if lifecycle.releasing || !self.owns_pad(&pad) { + if lifecycle.is_released() || !self.owns_pad(&pad) { continue; } let (track, result) = lifecycle.media.finish(); @@ -1101,7 +1106,7 @@ impl MoqSink { let linger = state.linger; if linger.is_zero() { drop(finished); - state.drained = true; + state.drain = Drain::Closed; return claim_eos(control); } gst::info!( @@ -1114,7 +1119,7 @@ impl MoqSink { self.obj().downgrade(), state.session.completion(), )); - state.lingering = Some(task.abort_handle()); + state.drain = Drain::Lingering(task.abort_handle()); Posted::Nothing } @@ -1123,7 +1128,12 @@ impl MoqSink { let message = { let mut control = self.control.lock().unwrap(); match control.live.as_mut() { - Some(state) if std::sync::Arc::ptr_eq(&state.session.completion(), session) => state.drained = true, + Some(state) + if std::sync::Arc::ptr_eq(&state.session.completion(), session) + && matches!(state.drain, Drain::Lingering(_)) => + { + state.drain = Drain::Closed + } _ => return, } claim_eos(&mut control) @@ -1214,7 +1224,7 @@ impl MoqSink { .completion .as_ref() .is_some_and(|completion| std::sync::Arc::ptr_eq(completion, session)); - (!lifecycle.releasing && belongs).then(|| PadUpdate { + (!lifecycle.is_released() && belongs).then(|| PadUpdate { pad: pad.clone(), changes: lifecycle.fail(format!("session failed: {error}")), }) @@ -2177,7 +2187,7 @@ mod tests { element.set_state(gst::State::Paused).expect("start session"); let pad = pad.downcast::().expect("MoqSinkPad"); - pad.lifecycle().releasing = true; + pad.lifecycle().phase = Phase::Released; sink.imp().control.lock().unwrap().admissions.insert(pad.clone()); let (admission, finished) = sink.imp().confirm_admission(&pad); sink.imp().publish_finished(finished); @@ -2188,7 +2198,6 @@ mod tests { "and it did so while the pad still belonged to the element, which is the window \ `owns_pad` cannot see" ); - pad.lifecycle().releasing = false; let _ = element.set_state(gst::State::Null); } @@ -2460,6 +2469,14 @@ mod tests { let start = kio::clock::now(); let finished = moq_mux::Linger::new([broadcast], track, linger); let lingering = tokio::spawn(linger_task(finished, sink.downgrade(), session)); + sink.imp() + .control + .lock() + .unwrap() + .live + .as_mut() + .expect("live session") + .drain = Drain::Lingering(lingering.abort_handle()); kio::clock::sleep(linger - Duration::from_secs(1)).await; let mut late = consumer.track("video").unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 806abe8e5d5..33b4013e8d6 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -96,9 +96,10 @@ impl Names { /// Keep finished rendition owners until a whole run's catalog has closed. #[must_use] +#[derive(Default)] pub(super) struct Closed { - track: Option, - /// The catalog `track` published in, kept open until the owner drops. + _track: Option, + /// The catalog `_track` published in, kept open until the owner drops. _catalog: Option, } @@ -292,23 +293,40 @@ pub enum PushOutcome { Failed(String), } +/// Where a pad's producer is in its life. +enum Producer { + /// No producer and no catalog slot. `caps` are the ones a finished producer was built from: CAPS + /// stay sticky across a flush, so a resumed stream rebuilds from them. + Idle { caps: Option }, + /// The requested pad gates the first catalog even before CAPS can name its rendition. + Reserved { + slot: Box, + caps: Option, + }, + /// CAPS built a producer, which publishes the pad's buffers. + Publishing(Box), + /// A producer build or write rejected this pad's caps or bitstream; further buffers are dropped + /// and the track stays finalized. Isolated to the pad, so the session and other pads keep going. + /// The reason is not kept here: whichever call failed returns it. + Failed, +} + +/// A live producer and what it was built from. +struct Publishing { + track: Sink, + /// The catalog `track` publishes in. + catalog: moq_mux::catalog::Producer, + caps: gst::Caps, + /// Whether `track` has a configured name, which may be requested again. A generated one never is. + named: bool, +} + /// One sink pad's producer plus its timeline policy. pub struct Pad { - /// The requested pad gates the first catalog even before CAPS can name its rendition. - reserved: Option, + producer: Producer, wall: Option>, /// The run's, once reserved; until then this pad's own, which still covers renegotiation. names: Names, - track: Option, - /// The catalog `track` publishes in, set with it. - catalog: Option, - /// Whether `track` has a configured name, which may be requested again. A generated one never is. - named: bool, - caps: Option, - /// Set once a producer build rejects this pad's caps or bitstream; further buffers are dropped and - /// the track stays finalized. Isolated to the pad, so the session and other pads keep going. The - /// reason is not kept here: whichever call failed returns it. - failed: bool, state: PadState, segment_info: Option, /// Kept only to map a buffer PTS to a running time. @@ -322,14 +340,9 @@ impl Pad { /// A fresh pad with no caps, no segment, and no producer yet. pub fn new() -> Self { Self { - reserved: None, + producer: Producer::Idle { caps: None }, wall: None, names: Names::default(), - track: None, - catalog: None, - named: false, - caps: None, - failed: false, state: PadState::NoSegment, segment_info: None, segment: None, @@ -346,15 +359,39 @@ impl Pad { ) { self.wall = Some(wall); self.names = names.clone(); - if self.reserved.is_none() && self.track.is_none() && !self.failed { - self.reserved = Some(catalog.reserve()); + if let Producer::Idle { caps } = &mut self.producer { + self.producer = Producer::Reserved { + slot: Box::new(catalog.reserve()), + caps: caps.take(), + }; + } + } + + /// The live producer's track, if any. + fn track(&self) -> Option<&Sink> { + match &self.producer { + Producer::Publishing(publishing) => Some(&publishing.track), + _ => None, + } + } + + /// The live producer's media track, if it is one. + fn media_mut(&mut self) -> Option<&mut Media> { + match &mut self.producer { + Producer::Publishing(publishing) => match &mut publishing.track { + Sink::Media(media) => Some(media), + _ => None, + }, + _ => None, } } /// An ended pad can no longer resolve its config, but resolved tracks keep their usual lifetime. pub(super) fn end_unresolved(&mut self, catalog: &moq_mux::catalog::Producer) -> Result<()> { - self.reserved.take(); - if let Some(Sink::Media(media)) = &self.track { + if let Producer::Reserved { caps, .. } = &mut self.producer { + self.producer = Producer::Idle { caps: caps.take() }; + } + if let Some(Sink::Media(media)) = self.track() { // Read current state, not the gated wire snapshot. An untouched guard emits nothing and // avoids cloning every rendition. Drop it before finalize takes the catalog lock again. let mut catalog = catalog.clone(); @@ -377,15 +414,15 @@ impl Pad { /// The caps to rebuild from when [`end_unresolved`](Self::end_unresolved) finished this pad and its /// stream resumes: CAPS stay sticky across a flush, so none arrives to rebuild it. pub(super) fn resumable_caps(&self) -> Option { - match (&self.track, self.failed) { - (None, false) => self.caps.clone(), - _ => None, + match &self.producer { + Producer::Idle { caps } | Producer::Reserved { caps, .. } => caps.clone(), + Producer::Publishing(_) | Producer::Failed => None, } } /// True once this pad has been invalidated by a bad caps/bitstream; the caller drops its buffers. pub fn is_failed(&self) -> bool { - self.failed + matches!(self.producer, Producer::Failed) } /// A watch-only handle to the active track's subscriber demand, once viewers can find the track. @@ -395,7 +432,7 @@ impl Pad { /// would keep it out of the catalog for good. Opaque data has no catalog entry by design; its /// subscribers name the track directly, so its demand is live from negotiation. pub(super) fn demand(&self, listed: &Listed) -> Option { - let track = self.track.as_ref()?; + let track = self.track()?; match track { Sink::Opaque(_) => {} Sink::Media(_) | Sink::Text(_) if listed.contains(&track.name()) => {} @@ -413,20 +450,32 @@ impl Pad { catalog: &moq_mux::catalog::Producer, options: ProducerOptions<'_>, ) -> CapsOutcome { - if self.failed { - return CapsOutcome::Unchanged; - } - if self.track.is_some() - && let Some(caps) = &self.caps - && same_importer(caps, options.caps) - { - self.caps = Some(options.caps.clone()); - return CapsOutcome::Unchanged; + match &mut self.producer { + Producer::Failed => return CapsOutcome::Unchanged, + Producer::Publishing(publishing) if same_importer(&publishing.caps, options.caps) => { + publishing.caps = options.caps.clone(); + return CapsOutcome::Unchanged; + } + _ => {} } - let reserved = self.reserved.take().unwrap_or_else(|| catalog.reserve()); - match self.build(broadcast, reserved, options) { - Ok(name) => { - self.catalog = Some(catalog.clone()); + let slot = match std::mem::replace(&mut self.producer, Producer::Idle { caps: None }) { + Producer::Reserved { slot, .. } => *slot, + // A live producer stays until the build finalizes it. + previous => { + self.producer = previous; + catalog.reserve() + } + }; + let caps = options.caps.clone(); + let named = options.requested.is_some(); + match self.build(broadcast, slot, options) { + Ok((name, track)) => { + self.producer = Producer::Publishing(Box::new(Publishing { + track, + catalog: catalog.clone(), + caps, + named, + })); CapsOutcome::Active(name) } Err(err) => { @@ -442,7 +491,7 @@ impl Pad { broadcast: &moq_net::broadcast::Producer, reserved: moq_mux::catalog::Reserved, options: ProducerOptions<'_>, - ) -> Result { + ) -> Result<(String, Sink)> { let ProducerOptions { container, caps, @@ -452,7 +501,6 @@ impl Pad { // Renegotiation to new content: finalize the previous producer before replacing it (closed once, // not abandoned), so its name has ended and the replacement takes a fresh one. self.finalize()?; - self.named = requested.is_some(); let requested = requested.map(|name| { let claimed = self.names.claim(name); if claimed != name { @@ -475,9 +523,7 @@ impl Pad { let info = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) .with_max_age(std::time::Duration::from_secs(5)); - self.track = Some(Sink::Opaque(Box::new(request.accept(info)))); - self.caps = Some(caps.clone()); - return Ok(name); + return Ok((name, Sink::Opaque(Box::new(request.accept(info))))); } let mut broadcast = broadcast.clone(); // Every codec converges on one import::Track; only the caps -> importer construction differs. The @@ -489,14 +535,8 @@ impl Pad { // text with a presentation time, so there is nothing to parse, only a text rendition to declare. if structure.name().as_str() == "text/x-raw" { let name = Self::track_name(&broadcast, requested, ".vtt"); - self.track = Some(Sink::Text(Box::new(Self::reserve_text( - &mut broadcast, - reserved, - name.clone(), - structure, - )?))); - self.caps = Some(caps.clone()); - return Ok(name); + let text = Self::reserve_text(&mut broadcast, reserved, name.clone(), structure)?; + return Ok((name, Sink::Text(Box::new(text)))); } let mut pre_skip = None; @@ -618,16 +658,15 @@ impl Pad { } other => anyhow::bail!("unsupported caps: {other}"), }; - self.track = Some(Sink::Media(Box::new(Media { + let media = Media { track, audio, group_start: None, discontinuity: false, keyframe: !audio, pre_skip, - }))); - self.caps = Some(caps.clone()); - Ok(name) + }; + Ok((name, Sink::Media(Box::new(media)))) } /// The name this pad publishes under: the one it was given, else a generated `0{suffix}`. @@ -724,7 +763,7 @@ impl Pad { if let Err(err) = self.finalize() { gst::warning!(CAT, "finalize on failed pad: {err:?}"); } - self.failed = true; + self.producer = Producer::Failed; } /// Invalidate this producer after a failure detected outside the codec importer. @@ -754,7 +793,7 @@ impl Pad { let segment = segment.downcast::().ok(); if self.segment.is_some() && self.segment != segment - && let Some(Sink::Media(media)) = self.track.as_mut() + && let Some(media) = self.media_mut() { media.discontinuity = true; } @@ -785,7 +824,7 @@ impl Pad { /// Restart measurement on the next frame while retaining the current segment. pub fn discontinuity(&mut self) { if self.segment.is_some() - && let Some(Sink::Media(media)) = self.track.as_mut() + && let Some(media) = self.media_mut() { media.discontinuity = true; } @@ -795,32 +834,16 @@ impl Pad { /// decode order and B-frames carry non-monotonic presentation timestamps, so a PTS regression is /// normal reordering. Timeline breaks are caught at the SEGMENT level (the `Invalid` state). fn frame_timestamp(&self, pts: Option) -> Result { - match self.state { - PadState::Active => { - // to_running_time_full is signed: a buffer before the segment returns Negative, which - // frame_micros drops; to_running_time would instead clip it to None and lose the reason. - let running_time = self - .segment - .as_ref() - .zip(pts) - .and_then(|(segment, pts)| segment.to_running_time_full(pts)) - .and_then(signed_nanos); - frame_micros(running_time) - } - PadState::NoSegment => Err("buffer before a valid SEGMENT"), - PadState::Invalid => Err("buffer on an invalidated timeline"), - } + frame_timestamp(self.state, self.segment.as_ref(), pts) } /// Place the run on the wall clock before its first valid timestamp can reach an importer. pub(super) fn place_wall(&self, buffer: &gst::BufferRef, sample: super::wall::Sample) -> Result<()> { let Some(wall) = &self.wall else { return Ok(()) }; - if self.failed || self.track.is_none() { + let Some(track) = self.track() else { return Ok(()); - } - let timestamp = if matches!(self.track, Some(Sink::Opaque(_))) - && buffer.pts().is_none() - && self.state == PadState::Active + }; + let timestamp = if matches!(track, Sink::Opaque(_)) && buffer.pts().is_none() && self.state == PadState::Active { sample .running @@ -843,12 +866,9 @@ impl Pad { /// The PTS `buffer` publishes at: its own, except an Opus packet's, which moves onto hang's /// timeline (see [`PreSkip`]). pub(super) fn timeline_pts(&mut self, buffer: &gst::BufferRef) -> Result> { - match &mut self.track { - Some(Sink::Media(media)) if !self.failed => match &mut media.pre_skip { - Some(pre_skip) => pre_skip.pts(buffer), - None => Ok(buffer.pts()), - }, - _ => Ok(buffer.pts()), + match self.media_mut().and_then(|media| media.pre_skip.as_mut()) { + Some(pre_skip) => pre_skip.pts(buffer), + None => Ok(buffer.pts()), } } @@ -859,24 +879,25 @@ impl Pad { duration: Option, current_running_time: Option, ) -> std::result::Result { - if self.failed { - return Ok(PushOutcome::Dropped); - } - if self.track.is_none() { - gst::warning!(CAT, "dropping buffer received before caps"); - return Ok(PushOutcome::Dropped); - } - let opaque = matches!(self.track.as_ref(), Some(Sink::Opaque(_))); + let publishing = match &mut self.producer { + Producer::Failed => return Ok(PushOutcome::Dropped), + Producer::Publishing(publishing) => publishing, + Producer::Idle { .. } | Producer::Reserved { .. } => { + gst::warning!(CAT, "dropping buffer received before caps"); + return Ok(PushOutcome::Dropped); + } + }; + let opaque = matches!(publishing.track, Sink::Opaque(_)); let timestamp = if opaque && pts.is_none() && self.state == PadState::Active { let running_time = current_running_time.ok_or("no current running time for unstamped opaque data")?; let nanos = i64::try_from(running_time.nseconds()).map_err(|_| "current running time is out of range")?; frame_micros(Some(nanos)) } else { - self.frame_timestamp(pts) + frame_timestamp(self.state, self.segment.as_ref(), pts) }; match timestamp { Ok(micros) => { - let result: Result<()> = match self.track.as_mut().expect("track present") { + let result: Result<()> = match &mut publishing.track { Sink::Media(media) => match media.write(&data, micros) { Ok(false) => { gst::debug!( @@ -943,27 +964,64 @@ impl Pad { /// Finish once, retaining rendition owners so closing a run cannot publish their removal. pub(super) fn finish(&mut self) -> (Closed, Result) { - self.reserved.take(); - let mut closed = Closed { - track: self.track.take(), - _catalog: self.catalog.take(), - }; - let Some(track) = closed.track.as_mut() else { - return (closed, Ok(false)); + let publishing = match std::mem::replace(&mut self.producer, Producer::Idle { caps: None }) { + Producer::Publishing(publishing) => publishing, + Producer::Reserved { caps, .. } => { + self.producer = Producer::Idle { caps }; + return (Closed::default(), Ok(false)); + } + unchanged => { + self.producer = unchanged; + return (Closed::default(), Ok(false)); + } }; - let result = match track { + let Publishing { + mut track, + catalog, + caps, + named, + } = *publishing; + let result = match &mut track { Sink::Media(media) => media.track.finish().map_err(anyhow::Error::from), Sink::Text(text) => text.producer.finish().map_err(anyhow::Error::from), Sink::Opaque(producer) => producer.clone().finish().map_err(anyhow::Error::from), }; - if self.named { + if named { self.names.end(track.name()); } - self.failed |= result.is_err(); + self.producer = match result { + Ok(()) => Producer::Idle { caps: Some(caps) }, + Err(_) => Producer::Failed, + }; + let closed = Closed { + _track: Some(track), + _catalog: Some(catalog), + }; (closed, result.map(|()| true)) } } +/// Map `pts` onto the timeline `state` and `segment` anchor, in microseconds. +fn frame_timestamp( + state: PadState, + segment: Option<&gst::FormattedSegment>, + pts: Option, +) -> Result { + match state { + PadState::Active => { + // to_running_time_full is signed: a buffer before the segment returns Negative, which + // frame_micros drops; to_running_time would instead clip it to None and lose the reason. + let running_time = segment + .zip(pts) + .and_then(|(segment, pts)| segment.to_running_time_full(pts)) + .and_then(signed_nanos); + frame_micros(running_time) + } + PadState::NoSegment => Err("buffer before a valid SEGMENT"), + PadState::Invalid => Err("buffer on an invalidated timeline"), + } +} + /// The mapping fields on an `audio/x-opus` caps structure. Absent fields stay absent: /// a present field of the wrong type is refused rather than treated as missing. struct OpusDeclared { diff --git a/rs/moq-gst/src/sink/request_pad.rs b/rs/moq-gst/src/sink/request_pad.rs index 7291f38d478..06ffe44f4f5 100644 --- a/rs/moq-gst/src/sink/request_pad.rs +++ b/rs/moq-gst/src/sink/request_pad.rs @@ -61,13 +61,25 @@ struct Bandwidth { watch_task: Option>, } +/// Where a request pad's stream is, from its request to its release. +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] +pub(super) enum Phase { + /// Its stream is flowing, or has yet to start. + #[default] + Streaming, + /// Its stream reached EOS; a flush or a new stream starts it again. Unlike [`Status::Ended`], the + /// track may still be live: the element finalizes the tracks once every pad is here. + Eos, + /// Being released, or released. Nothing moves it out again. + Released, +} + /// Everything owned by one request pad, protected by one lock. pub(super) struct PadLifecycle { settings: Settings, pub(super) media: Pad, bandwidth: Option, - pub(super) ended: bool, - pub(super) releasing: bool, + pub(super) phase: Phase, /// This pad's link to its publication. `None` is no live session for the pad, which is why a buffer /// arriving before one exists is refused rather than dropped. pub(super) completion: Option, @@ -79,8 +91,7 @@ impl Default for PadLifecycle { settings: Settings::default(), media: Pad::new(), bandwidth: None, - ended: false, - releasing: false, + phase: Phase::Streaming, completion: None, } } @@ -219,7 +230,12 @@ impl Settings { } impl PadLifecycle { - /// The configured track name while this pad is not releasing. + /// Whether the pad is being released, or was: nothing changes it any more. + pub(super) fn is_released(&self) -> bool { + self.phase == Phase::Released + } + + /// The configured track name. pub(super) fn requested(&self) -> Option<&str> { self.settings.requested.as_deref() } @@ -276,8 +292,8 @@ impl PadLifecycle { pad: &MoqSinkPad, listed: &Listed, ) -> Option { - // An ended pad reports nothing until it resumes; a failed one has no track left. - if self.ended || self.releasing { + // An ended pad reports nothing until it resumes; a released one has no track left. + if self.phase != Phase::Streaming { return None; } self.restore_bandwidth(allocator, pad, listed) @@ -345,7 +361,9 @@ impl PadLifecycle { let status = self.settings.set_status(Status::Pending); let demand = self.bandwidth.take().is_some(); self.media = Pad::new(); - self.ended = false; + if self.phase == Phase::Eos { + self.phase = Phase::Streaming; + } self.completion = None; Notifications { track, @@ -435,7 +453,7 @@ impl ObjectImpl for MoqSinkPadImp { fn set_property(&self, _id: usize, value: &glib::Value, pspec: &glib::ParamSpec) { let mut lifecycle = self.lifecycle.lock().unwrap(); - if lifecycle.releasing { + if lifecycle.is_released() { gst::warning!( CAT, obj = self.obj(), @@ -528,13 +546,12 @@ impl MoqSinkPad { } } - /// Reset a detached pad without asking GStreamer to remove it twice. + /// Reset and release a detached pad without asking GStreamer to remove it twice. pub(super) fn reset_detached(&self) { let changes = { let mut lifecycle = self.lifecycle(); - let changes = lifecycle.reset(); - lifecycle.releasing = false; - changes + lifecycle.phase = Phase::Released; + lifecycle.reset() }; self.notify_changes(changes); } diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 46bd3c189ee..922ae2c6a7b 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1317,10 +1317,26 @@ struct Attached { /// A rendition a [`Follower`] plays. struct Entry { shape: Shape, - /// Reading the current instance, if it is. - reader: Option, + reading: Reading, +} + +/// Whether a rendition reads the current instance. +enum Reading { + /// No reader: no instance yet, or one that does not serve it. + Idle, + Reader(ReaderHandle), /// Delisted while reading: plays out the instance it reads, then leaves. - draining: bool, + Draining(ReaderHandle), +} + +impl Reading { + /// The running reader, draining or not. + fn reader(&self) -> Option<&ReaderHandle> { + match self { + Reading::Idle => None, + Reading::Reader(reader) | Reading::Draining(reader) => Some(reader), + } + } } /// A running [`Reader`], cancelled when dropped. @@ -1448,23 +1464,35 @@ impl Follower { // warmup for the next one. let reshaped = shape != entry.shape; entry.shape = shape; - if reshaped { - entry.reader = None; - fresh.insert(rendition.clone()); - } - entry.draining = false; + entry.reading = match std::mem::replace(&mut entry.reading, Reading::Idle) { + _ if reshaped => { + fresh.insert(rendition.clone()); + Reading::Idle + } + Reading::Reader(reader) | Reading::Draining(reader) => Reading::Reader(reader), + Reading::Idle => Reading::Idle, + }; true } // A delisted rendition plays out the instance it reads, then leaves. One that never // took its pad, or that is disabled or now reads another broadcast, stops now. None => { - entry.draining = !pads.is_listed(rendition) + let drains = !pads.is_listed(rendition) && !disabled.contains(rendition) && entry - .reader - .as_ref() + .reading + .reader() .is_some_and(|reader| reader.live.load(Ordering::Acquire)); - entry.draining + if !drains { + return false; + } + // A later catalog update finds it already draining: it keeps playing out. + if let Reading::Reader(reader) | Reading::Draining(reader) = + std::mem::replace(&mut entry.reading, Reading::Idle) + { + entry.reading = Reading::Draining(reader); + } + true } }); for (rendition, shape) in wanted { @@ -1473,8 +1501,7 @@ impl Follower { rendition, Entry { shape, - reader: None, - draining: false, + reading: Reading::Idle, }, ); } @@ -1557,9 +1584,10 @@ impl Follower { /// Stop reading the instance. A draining rendition leaves with it. fn idle(&mut self) { - self.renditions.retain(|_, entry| !entry.draining); + self.renditions + .retain(|_, entry| !matches!(entry.reading, Reading::Draining(_))); for entry in self.renditions.values_mut() { - entry.reader = None; + entry.reading = Reading::Idle; } } @@ -1577,7 +1605,10 @@ impl Follower { return; }; for (rendition, entry) in &mut self.renditions { - if entry.reader.is_none() && only(rendition) && serves(instance, entry.shape.instance.as_ref()) { + if matches!(entry.reading, Reading::Idle) + && only(rendition) + && serves(instance, entry.shape.instance.as_ref()) + { self.next_id += 1; let (cancel, cancelled) = watch::channel(false); let live = Arc::new(AtomicBool::new(false)); @@ -1603,7 +1634,7 @@ impl Follower { }), RUNTIME.handle(), ); - entry.reader = Some(ReaderHandle { id, live, cancel }); + entry.reading = Reading::Reader(ReaderHandle { id, live, cancel }); } } } @@ -1613,11 +1644,10 @@ impl Follower { let Some(entry) = self.renditions.get_mut(&rendition) else { return; }; - if entry.reader.as_ref().is_none_or(|reader| reader.id != id) { + if entry.reading.reader().is_none_or(|reader| reader.id != id) { return; } - entry.reader = None; - if entry.draining { + if let Reading::Draining(_) = std::mem::replace(&mut entry.reading, Reading::Idle) { self.renditions.remove(&rendition); } else if let Exit::Unlisted = exit && self.playback.session.pads.is_listed(&rendition) @@ -3256,7 +3286,8 @@ mod session_tests { /// short: the pad owes downstream every frame of the track and an EOS. /// /// The subscriber's view of that arrival order is reproduced exactly: the head of the track, - /// then the catalog update, then the tail and the clean end. + /// then the catalog update, then the tail and the clean end. A second update lands while the + /// rendition drains, which must leave it draining. #[test] fn a_retired_rendition_drains_to_eos() { const HEAD: u64 = 3; @@ -3273,6 +3304,9 @@ mod session_tests { let _audio = broadcast .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); + let _audio2 = broadcast + .create_track("audio2", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); { let mut guard = catalog.modify().unwrap(); guard.video.renditions = BTreeMap::from([("video".to_string(), video_rendition())]); @@ -3345,6 +3379,18 @@ mod session_tests { } await_pad(&element, "audio_"); + // A second update while the video drains, whose new audio pad proves it was acted on. + let (added, added_rx) = std::sync::mpsc::channel(); + let handler = element.connect_pad_added(move |_, pad| { + let _ = added.send(pad.name().to_string()); + }); + { + let mut guard = catalog.modify().unwrap(); + guard.audio.renditions.insert("audio2".to_string(), audio_rendition()); + } + while !added_rx.recv().expect("the element is alive").starts_with("audio_") {} + element.disconnect(handler); + // A reader the update cancelled still has to notice. It takes its pad with it when it does, // so the wait is only ever served in full by one that is still reading. for _ in 0..10 { diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 78766cb3a37..751b74a1972 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -132,8 +132,6 @@ struct Handle { /// The query pinning the track instance. Even an info query creates publisher demand, /// so a lazy rendition holds it only while serving media. track: Option, - /// The bound sibling ended, so only its retained rows drain. - ended: bool, } impl Handle { @@ -159,7 +157,6 @@ impl Media { let mut handle = Handle { binding: Arc::new(source.bind(rel, reference.instance())?), track: None, - ended: false, }; if !lazy && let Poll::Ready(Ok(broadcast)) = handle.binding.poll_broadcast(&kio::Waiter::noop()) { handle.capture(&broadcast, track); @@ -173,10 +170,11 @@ impl Media { }) } - /// Whether incoming rows should be listed: not once the bound sibling ended. + /// Whether incoming rows should be listed: not once the window stopped listing, as it does + /// when the bound sibling ends. fn admits(&self, window: &segments::Producer) -> bool { self.sync(window); - !self.handle.lock().expect("media lock poisoned").ended + window.lists() } /// End the window when a bound sibling has ended; retain its rows and media for draining. @@ -191,10 +189,9 @@ impl Media { if !self.lazy { handle.capture(&broadcast, &self.track); } - if self.sibling && !handle.ended && broadcast.poll_closed(waiter).is_ready() { + if self.sibling && broadcast.poll_closed(waiter).is_ready() { // End and Restart both drain only the pinned instance. Looking its path up again // could serve a replacement under the old track's rows. - handle.ended = true; window.end(); } } @@ -405,10 +402,9 @@ pub struct Rendition { fanout: renditions::Fanout, /// Follows the media track's groups into [`live`](Self::live); ends when the rendition drops. watcher: Mutex, - /// Set once the catalog drops or replaces the rendition (see [`retire`](Self::retire)). - retiring: kio::Producer, - /// Which segments this instance lists. - claim: Mutex, + /// Which segments this instance lists. A channel so the media watcher wakes once a + /// [`retire`](Self::retire) leaves no segment pending. + claim: kio::Producer, /// The retired instance this one replaced under the same playlist URI, whose segments its playlist /// still lists ahead of its own until the window slides past them (see [`after`](Self::after)). /// Released once none is listed, or by a restart. @@ -528,7 +524,7 @@ impl kio::Task for Idle { let Some(rendition) = self.rendition.upgrade() else { return Poll::Ready(()); }; - let mut claim = rendition.claim.lock().expect("claim lock poisoned"); + let mut claim = rendition.claim(); let mut watcher = rendition.watcher.lock().expect("watcher lock poisoned"); // A finished window keeps listing what it listed, inherited predecessor rows included, // and keeps its track pin: reads of its retained groups go through it, since a closed @@ -685,8 +681,7 @@ impl Rendition { live: Arc::new(segments::Producer::new(0)), fanout, watcher: Mutex::default(), - retiring: kio::Producer::new(false), - claim: Mutex::default(), + claim: kio::Producer::default(), previous: Mutex::new(None), media: Arc::new(media), run: kio::Producer::default(), @@ -728,8 +723,7 @@ impl Rendition { live: Arc::new(segments::Producer::new(0)), fanout, watcher: Mutex::default(), - retiring: kio::Producer::new(false), - claim: Mutex::default(), + claim: kio::Producer::default(), previous: Mutex::new(None), media: Arc::new(media), run: kio::Producer::default(), @@ -779,7 +773,7 @@ impl Rendition { // The playlist URI stays the same, so it keeps its target duration (RFC 8216 6.2.1). self.target_duration = handoff.target_duration; let start = handoff.next; - self.claim = Mutex::new(Claim { + self.claim = kio::Producer::new(Claim { start, next: start, ..Claim::default() @@ -800,7 +794,7 @@ impl Rendition { /// the media and the catalog are separate tracks, so the successor's first group can arrive first. pub(crate) fn retire(self: &Arc, successor: Option<&VideoConfig>) -> Handoff { let (next, pending) = { - let mut claim = self.claim.lock().expect("claim lock poisoned"); + let mut claim = self.claim(); claim.retired = true; claim.boundary = claim.seen; if let Some(resized) = self.handover(&claim, successor) { @@ -816,10 +810,6 @@ impl Rendition { } (claim.next, claim.pending) }; - *self - .retiring - .write() - .unwrap_or_else(|_| unreachable!("the rendition holds its producer")) = true; // Once retired, one that neither lists nor waits to list a segment never will, so the // replacement keeps only what this one was keeping: churn can't stack empty instances. let lists = pending || !self.live.window().segments.is_empty(); @@ -852,6 +842,12 @@ impl Rendition { (same_track && resizes && resized.group >= unplaced).then_some(resized) } + fn claim(&self) -> kio::Mut<'_, Claim> { + self.claim + .write() + .unwrap_or_else(|_| unreachable!("the rendition holds its claim")) + } + fn previous(&self) -> Option> { self.previous.lock().expect("previous lock poisoned").clone() } @@ -1985,22 +1981,16 @@ fn broken(segments: &[u64], inherited: usize) -> usize { .unwrap_or(0) } -/// Ready once `rendition` is retired with no segment left waiting to list, or is gone. -/// -/// The claim is read on every poll, so a retire that leaves nothing pending wakes it. -fn poll_retired(retiring: &kio::Consumer, rendition: &Weak, waiter: &kio::Waiter) -> Poll<()> { - // Upgraded outside the channel's lock, so the last strong reference never drops under it. - let Some(rendition) = rendition.upgrade() else { - return Poll::Ready(()); - }; - let done = |retiring: &bool| *retiring && !rendition.claim.lock().expect("claim lock poisoned").pending; +/// Ready once the rendition is retired with no segment left waiting to list, or is gone. +fn poll_retired(claim: &kio::Consumer, waiter: &kio::Waiter) -> Poll<()> { // A closed channel means the rendition is gone, which ends the watch all the same. - retiring - .poll(waiter, |retiring| match done(retiring) { - true => Poll::Ready(()), - false => Poll::Pending, - }) - .map(|_| ()) + match claim.poll(waiter, |claim| match claim.retired && !claim.pending { + true => Poll::Ready(()), + false => Poll::Pending, + }) { + Poll::Ready(_) => Poll::Ready(()), + Poll::Pending => Poll::Pending, + } } /// Follows a rendition's media track into its window, numbering its groups on the grid, until the @@ -2012,7 +2002,7 @@ fn poll_retired(retiring: &kio::Consumer, rendition: &Weak, wai /// lists that segment whole, and the same URL must name the same bytes everywhere. struct WatchMedia { rendition: Weak, - retiring: kio::Consumer, + claim: kio::Consumer, /// Taken from the rendition on the first poll. follow: Option, /// The rendition's media and the binding it is read through, held while the watch runs. @@ -2139,7 +2129,7 @@ impl Follow { return Some(Ok(())); }; // Held while listing, so a retire sees exactly what this instance lists. - let mut claim = rendition.claim.lock().expect("claim lock poisoned"); + let mut claim = rendition.claim(); // Retired, a group past the last it had read is the replacement's: this instance lists // the segments and gaps before the first holding one, and its own part of that one, then // stops there. @@ -2243,7 +2233,7 @@ impl WatchMedia { fn new(rendition: &Arc) -> Self { Self { rendition: Arc::downgrade(rendition), - retiring: rendition.retiring.consume(), + claim: rendition.claim.consume(), follow: None, held: None, groups: None, @@ -2254,7 +2244,7 @@ impl WatchMedia { fn poll_watch(&mut self, waiter: &kio::Waiter) -> Poll> { let follow = self.follow.as_mut().expect("taken on the first poll"); loop { - let retired = || poll_retired(&self.retiring, &self.rendition, waiter).is_ready(); + let retired = || poll_retired(&self.claim, waiter).is_ready(); match &mut self.step { Step::Start => { // A replacement lists nothing until its predecessor has listed all it will, so @@ -2275,7 +2265,7 @@ impl WatchMedia { } ready!(previous.live.poll_closed(waiter)); let (next, boundary) = { - let claim = previous.claim.lock().expect("claim lock poisoned"); + let claim = previous.claim(); (claim.next, claim.boundary) }; // Another track, or the same name in another broadcast, numbers its groups afresh. @@ -2285,7 +2275,7 @@ impl WatchMedia { .is_some_and(|rendition| rendition.continues(previous)); follow.after = boundary.filter(|_| continues); if let Some(rendition) = self.rendition.upgrade() { - let mut claim = rendition.claim.lock().expect("claim lock poisoned"); + let mut claim = rendition.claim(); claim.start = claim.start.max(next); claim.next = claim.next.max(next); } @@ -2395,9 +2385,10 @@ impl kio::Task for WatchMedia { let track = self.follow.take().expect("taken on the first poll").track; match result { Ok(()) => rendition.end(), - // A bound sibling that ended takes its track down with it: that ends the rendition, - // whose retained rows drain, rather than failing it. - Err(_) if !rendition.media.admits(&rendition.live) => rendition.end(), + // A bound sibling that ended takes its track down with it: that ended the rendition, + // whose retained rows drain, rather than failing it. A window cut or failed already + // keeps how it stopped. + Err(_) if !rendition.media.admits(&rendition.live) => {} // Never retried (the origin already rides out transient source failures), and not // papered over with gaps: the rendition's playlist answers the error. Err(err) => { @@ -2892,7 +2883,6 @@ mod tests { let mut handle = Handle { binding: Arc::new(moq_mux::Binding::new(consumer.clone())), track: None, - ended: false, }; handle.capture(&consumer, "video"); assert!(serve.track.lock().unwrap().is_some(), "the query was served"); diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index 795b4e8f1e2..21f0e793761 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -82,18 +82,26 @@ struct State { sequence: u64, /// The newest discontinuity seen, retained when the playlist window becomes empty. discontinuity: u64, - /// The media track ended: the rendition is over (`EXT-X-ENDLIST`). - ended: bool, - /// The run was replaced: the listed rows are final, so nothing appends, trims, or fails them. - cut: bool, - /// The media track or the catalog failed, so every listing refuses with this error. - failed: Option, + /// Whether rows still arrive, and if not, why. + phase: Phase, /// Bumped whenever the window is cleared, so a cursor can tell its position is stale. resets: u64, /// Total rows appended, so a cursor can detect eviction even before its first read. produced: u64, } +/// Whether a window still lists new rows, and if not, why. Each later phase is final. +enum Phase { + /// Rows arrive as the media watcher reads them. + Live, + /// The media track ended, or the bound sibling did: the rendition is over (`EXT-X-ENDLIST`). + Ended, + /// The run was replaced: the listed rows are final, so nothing appends, trims, or fails them. + Cut, + /// The media track or the catalog failed, so every listing refuses with this error. + Failed(crate::Error), +} + /// The most segments a playlist window lists, however short they are. /// /// Bounds the window however short its segments are, so an edge that joined long ago lists no @@ -193,8 +201,8 @@ impl State { sequence: self.sequence, discontinuity: self.rows.front().map_or(self.discontinuity, |row| row.discontinuity), segments: self.rows.iter().cloned().collect(), - ended: self.ended, - failed: self.failed.clone(), + ended: matches!(self.phase, Phase::Ended | Phase::Cut), + failed: self.failure(), closed: false, } } @@ -207,10 +215,21 @@ impl State { } Ok(match self.rows.get((position.1 - first) as usize) { Some(row) => Next::Ready(row.clone()), - None if self.ended || self.failed.is_some() => Next::Done, - None => Next::Pending, + None if self.live() => Next::Pending, + None => Next::Done, }) } + + fn live(&self) -> bool { + matches!(self.phase, Phase::Live) + } + + fn failure(&self) -> Option { + match &self.phase { + Phase::Failed(err) => Some(err.clone()), + _ => None, + } + } } impl Producer { @@ -222,21 +241,20 @@ impl Producer { rows: VecDeque::new(), sequence: start, discontinuity: 0, - ended: false, - cut: false, - failed: None, + phase: Phase::Live, resets: 0, produced: 0, }), } } - /// Append a row, evicting the front of the window past `window` (see [`evicts`]). + /// Append a row, evicting the front of the window past `window` (see [`evicts`]). A window + /// that ended, failed, or was cut lists nothing more. pub fn push(&self, row: Row, window: Duration) { let Ok(mut state) = self.state.write() else { return; }; - if state.cut { + if !state.live() { return; } @@ -267,10 +285,11 @@ impl Producer { state.sequence = state.rows.front().unwrap().segment; } - /// Clear every retained row after the media timestamps went back. + /// Clear every retained row, after the media timestamps went back or a new publisher run + /// replaced them. An ended or failed window stays so; a cut window keeps what it listed. pub fn clear(&self) { if let Ok(mut state) = self.state.write() - && !state.cut + && !matches!(state.phase, Phase::Cut) { state.rows.clear(); state.resets += 1; @@ -279,18 +298,21 @@ impl Producer { /// Mark the media finished: the playlist gets `EXT-X-ENDLIST` and cursors end once drained. pub fn end(&self) { - if let Ok(mut state) = self.state.write() { - state.ended = true; + if let Ok(mut state) = self.state.write() + && state.live() + { + state.phase = Phase::Ended; } } /// Mark the window failed with `err`: every listing refuses with it instead of ending, and - /// cursors return it once drained. No row is pushed after. + /// cursors return it once drained. No row is pushed after. The first failure stays, and a cut + /// window keeps the rows it listed. pub fn fail(&self, err: crate::Error) { if let Ok(mut state) = self.state.write() - && !state.cut + && matches!(state.phase, Phase::Live | Phase::Ended) { - state.failed.get_or_insert(err); + state.phase = Phase::Failed(err); } } @@ -298,9 +320,10 @@ impl Producer { /// playlist gets `EXT-X-ENDLIST`, cursors drain those rows and then end, and whatever the /// replaced run sends later is refused. A window that already failed keeps its failure. pub fn cut(&self) { - if let Ok(mut state) = self.state.write() { - state.cut = true; - state.ended = true; + if let Ok(mut state) = self.state.write() + && matches!(state.phase, Phase::Live | Phase::Ended) + { + state.phase = Phase::Cut; } self.close(); } @@ -310,12 +333,17 @@ impl Producer { #[cfg(feature = "server")] pub fn finished(&self) -> bool { let state = self.state.read(); - state.ended || state.failed.is_some() || state.is_closed() + !state.live() || state.is_closed() + } + + /// Whether the window still lists new rows: it has not ended, failed, or been cut. + pub(crate) fn lists(&self) -> bool { + self.state.read().live() } /// Why the window failed, if it did. pub fn failure(&self) -> Option { - self.state.read().failed.clone() + self.state.read().failure() } /// Close the channel: no more rows will arrive. A [`Consumer`] drains the segments it @@ -382,12 +410,12 @@ impl Producer { /// Poll until the window lists a row, ends, fails, or closes. pub fn poll_listed(&self, waiter: &kio::Waiter) -> Poll<()> { - match self.state.poll_ref(waiter, |state| { - match !state.rows.is_empty() || state.ended || state.failed.is_some() { + match self + .state + .poll_ref(waiter, |state| match !state.rows.is_empty() || !state.live() { true => Poll::Ready(()), false => Poll::Pending, - } - }) { + }) { Poll::Ready(_) => Poll::Ready(()), Poll::Pending => Poll::Pending, } @@ -425,9 +453,9 @@ impl Producer { allow(dead_code, reason = "only the `server` feature uses it") )] pub fn poll_failed(&self, waiter: &kio::Waiter) -> Poll<()> { - match self.state.poll_ref(waiter, |state| match state.failed { - Some(_) => Poll::Ready(()), - None => Poll::Pending, + match self.state.poll_ref(waiter, |state| match state.phase { + Phase::Failed(_) => Poll::Ready(()), + _ => Poll::Pending, }) { Poll::Ready(Ok(())) => Poll::Ready(()), _ => Poll::Pending, @@ -671,6 +699,34 @@ mod tests { assert!(live.window().ended); } + // An ended window lists nothing more: the playlist already went out with `EXT-X-ENDLIST`. + #[test] + fn an_ended_window_refuses_rows() { + let live = Producer::new(0); + let window = Duration::from_secs(30); + live.push(row(0, 0, 0, 2_000), window); + live.end(); + live.push(row(1, 1, 2_000, 2_000), window); + let snapshot = live.window(); + assert!(snapshot.ended); + let segments: Vec<_> = snapshot.segments.iter().map(|row| row.segment).collect(); + assert_eq!(segments, [0]); + } + + // A restart still drops an ended window's rows, so the new run's generation never lists the + // previous run's segments. The window stays ended. + #[test] + fn an_ended_window_still_clears() { + let live = Producer::new(0); + let window = Duration::from_secs(30); + live.push(row(0, 0, 0, 2_000), window); + live.end(); + live.clear(); + let snapshot = live.window(); + assert!(snapshot.ended); + assert!(snapshot.segments.is_empty()); + } + // A cut freezes the listed rows: later records, trims, resets, and failures are refused, and // the window reads as ended. One that failed first keeps its failure. #[test] diff --git a/rs/moq-hls/src/import.rs b/rs/moq-hls/src/import.rs index 88678186379..125cb33b9ea 100644 --- a/rs/moq-hls/src/import.rs +++ b/rs/moq-hls/src/import.rs @@ -400,12 +400,9 @@ struct TrackState { /// separate audio rendition publishes video only). select: select::Broadcast, sink: Sink, - /// The importer for the current init segment generation, minted by [`Self::ensure_map`]. - importer: Option, + /// The current init segment's importer, minted by [`Self::ensure_map`]. + generation: Option, next_sequence: Option, - next_discontinuity: Option, - /// The `EXT-X-MAP` resource the current `importer` was initialized from. - map: Option, media_range: RangeCursor, /// Consecutive failed ingest attempts, reset by any successful one. See /// [`MAX_RENDITION_FAILURES`]. @@ -417,6 +414,15 @@ struct TrackState { followed: bool, } +/// One init segment's importer, and where it reached on the media timeline. +struct Generation { + /// The `EXT-X-MAP` resource the importer was initialized from. + map: Resource, + importer: Fmp4, + /// The discontinuity sequence of the last segment imported, `None` before the first. + discontinuity: Option, +} + impl TrackState { fn new(label: String, playlist: Url, select: select::Broadcast, sink: Sink) -> Self { Self { @@ -424,10 +430,8 @@ impl TrackState { playlist, select, sink, - importer: None, + generation: None, next_sequence: None, - next_discontinuity: None, - map: None, media_range: RangeCursor::default(), failures: 0, ended: false, @@ -441,8 +445,7 @@ impl TrackState { /// players stop selecting a rendition that no longer advances; a later successful step rebuilds /// it from the init segment. fn evict(&mut self) { - self.importer = None; - self.map = None; + self.generation = None; self.reanchor(); } @@ -599,7 +602,11 @@ impl TrackState { let resource = resolve_map(url, map.byte_range.as_ref())?; // The resolved resource IS the init segment's identity: same bytes, same generation. - if self.map.as_ref() == Some(&resource) { + if self + .generation + .as_ref() + .is_some_and(|generation| generation.map == resource) + { return Ok(()); } @@ -613,12 +620,14 @@ impl TrackState { // The old generation must finish before retiring its catalog entries, so a subscriber // draining its final group sees a clean end instead of a dropped producer. - if let Some(previous) = self.importer.as_mut() { - previous.finish()?; + if let Some(previous) = self.generation.as_mut() { + previous.importer.finish()?; } - self.importer = Some(importer); - self.map = Some(resource); - self.next_discontinuity = None; + self.generation = Some(Generation { + map: resource, + importer, + discontinuity: None, + }); info!(label = %self.label, "loaded HLS init segment generation"); Ok(()) } @@ -647,15 +656,16 @@ impl TrackState { // (and so validate) the sequence on that path so media sequence can't silently // auto-increment into the discontinuity bits. let group_sequence = moq_sequence(discontinuity_sequence, sequence)?; - let reanchored = - self.next_sequence != Some(sequence) || self.next_discontinuity != Some(discontinuity_sequence); // `consume_segments` resolves the effective map before every segment, so a missing // importer means the playlist never carried an `EXT-X-MAP`. - let importer = self.importer.as_mut().ok_or(Error::MissingMap)?; + let generation = self.generation.as_mut().ok_or(Error::MissingMap)?; + let reanchored = + self.next_sequence != Some(sequence) || generation.discontinuity != Some(discontinuity_sequence); + let importer = &mut generation.importer; // Only a discontinuity starts a new media timeline; a sequence skip must keep advancing. - if self - .next_discontinuity + if generation + .discontinuity .is_some_and(|previous| previous != discontinuity_sequence) { importer.discontinuity()?; @@ -667,7 +677,11 @@ impl TrackState { // carries no styp. Every rendition declares the same ones; the HLS segmenter drops a cut // that would land inside its minimum segment duration, so the duplicates cost nothing. importer.cut()?; - importer.decode(&bytes).map_err(|err| match err { + let decoded = importer.decode(&bytes); + if decoded.is_ok() { + generation.discontinuity = Some(discontinuity_sequence); + } + decoded.map_err(|err| match err { // Timestamp resets are unsupported: the published tracks never rewind, and no later // pass can import this segment, so it is refused rather than retried. moq_mux::Error::TimestampRewind(_) @@ -685,7 +699,6 @@ impl TrackState { self.media_range = range; self.next_sequence = Some(sequence + 1); - self.next_discontinuity = Some(discontinuity_sequence); Ok(()) } @@ -835,8 +848,8 @@ impl Import { /// broadcast to a [`moq_mux::Linger`] to keep them up for late subscribers. pub fn finish(&mut self) -> Result<()> { for track in self.video.iter_mut().chain(self.audio.iter_mut()) { - if let Some(importer) = &mut track.importer { - importer.finish()?; + if let Some(generation) = &mut track.generation { + generation.importer.finish()?; } } self.sink.catalog.finish()?; @@ -851,14 +864,14 @@ impl Import { /// the import: every rendition is dead afterwards. pub fn abort(mut self, err: moq_net::Error) { for track in &mut self.video { - if let Some(importer) = track.importer.take() { - importer.abort(err.clone()); + if let Some(generation) = track.generation.take() { + generation.importer.abort(err.clone()); } } if let Some(track) = &mut self.audio - && let Some(importer) = track.importer.take() + && let Some(generation) = track.generation.take() { - importer.abort(err.clone()); + generation.importer.abort(err.clone()); } self.sink.catalog.clone().abort(err); } @@ -915,7 +928,7 @@ impl Import { // drop the rest or abort the whole step. OnError::Warn => { track.failures += 1; - if track.failures >= MAX_RENDITION_FAILURES && track.importer.is_some() { + if track.failures >= MAX_RENDITION_FAILURES && track.generation.is_some() { warn!(label = %track.label, %err, failures = track.failures, "rendition import keeps failing, dropping it until it recovers"); track.evict(); } else { @@ -1987,7 +2000,7 @@ mod tests { let (mut import, catalog) = write_import(&temp_dir(), &resource, &playlist); assert!(matches!(import.init().await, Err(Error::PlaylistEnded))); - assert!(import.video[0].importer.is_none(), "nothing was imported"); + assert!(import.video[0].generation.is_none(), "nothing was imported"); assert!(catalog.snapshot().video.renditions.is_empty()); let run = kio::clock::timeout(Duration::from_secs(5), import.run()) @@ -2082,7 +2095,7 @@ mod tests { let (mut import, _catalog) = write_import(&dir, &resource, &playlist); import.init().await.unwrap(); - assert!(import.video[0].importer.is_some(), "the rendition imported once"); + assert!(import.video[0].generation.is_some(), "the rendition imported once"); // The source goes away underneath us. std::fs::remove_file(dir.join("media.m3u8")).unwrap(); @@ -2090,13 +2103,13 @@ mod tests { for _ in 0..MAX_RENDITION_FAILURES - 1 { import.step(OnError::Warn).await.unwrap(); assert!( - import.video[0].importer.is_some(), + import.video[0].generation.is_some(), "a transient failure keeps the rendition" ); } import.step(OnError::Warn).await.unwrap(); - assert!(import.video[0].importer.is_none(), "the dead rendition is retired"); + assert!(import.video[0].generation.is_none(), "the dead rendition is retired"); } /// A decode refusal retires its importer at once, rather than after @@ -2125,7 +2138,7 @@ mod tests { std::fs::write(dir.join("media.m3u8"), format!("{playlist}#EXTINF:1,\nvideo1.m4s\n")).unwrap(); let step = import.step(OnError::Warn).await.unwrap(); assert!(step.failed.is_some()); - assert!(import.video[0].importer.is_none()); + assert!(import.video[0].generation.is_none()); std::fs::write(dir.join("video1.m4s"), &segment).unwrap(); let step = import.step(OnError::Warn).await.unwrap(); assert!(step.failed.is_none()); @@ -2157,7 +2170,7 @@ mod tests { for _ in 0..MAX_RENDITION_FAILURES { assert!(import.step(OnError::Warn).await.unwrap().ended); } - assert!(import.video[0].importer.is_some(), "the ended rendition is kept"); + assert!(import.video[0].generation.is_some(), "the ended rendition is kept"); } /// A live window longer than `ANCHOR_SEGMENTS` is joined mid-playlist, which means the @@ -2196,7 +2209,7 @@ mod tests { let track = &import.video[0]; assert!( - track.importer.is_some(), + track.generation.is_some(), "the EXT-X-MAP from the skipped prefix must initialize the importer" ); // Four segments and a three-segment rewind, so segment 0 is skipped: the one @@ -2232,7 +2245,7 @@ mod tests { assert_eq!(snapshot.video.renditions.len(), 1); assert_eq!(snapshot.audio.renditions.len(), 1); assert_eq!( - import.video[0].map.as_ref().unwrap().range.unwrap().start, + import.video[0].generation.as_ref().unwrap().map.range.unwrap().start, second_init as u64 ); } diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index 7a0fa308224..c86fc6be1f7 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -30,7 +30,7 @@ struct State { /// Gates the initial catalog publish until all reservations resolve (see /// [`reserve`](Producer::reserve)). - reservations: Reservations, + gate: Gate, /// Why the catalog tracks are closed, so [`Producer::modify`] refuses further edits with the /// cause: [`Producer::finish`], [`Producer::abort`], or a failed drop-time publish. @@ -67,6 +67,12 @@ impl State { /// promises no frames, so it doesn't count. A listed rendition covers application-defined /// sections the base fields can't see, and an importer that lists tracks in the extension /// reports them through [`ext_tracks`](Self::ext_tracks). + /// Whether a buffering gate opens now: no reservation is outstanding and the catalog lists a + /// track. The track scan runs last, so releasing each of many reservations stays linear. + fn gate_opens(&mut self) -> bool { + matches!(self.gate, Gate::Buffering { reservers: 0, .. }) && self.lists_track() + } + fn lists_track(&mut self) -> bool { use std::any::TypeId; // Video and audio carry `enabled`, which only the base check reads. @@ -242,7 +248,7 @@ fn adopt( /// /// A panic under this lock comes from code we hand the catalog to: a [`RenditionConfig::insert`] /// implementation, or serializing an extension during a publish. Neither leaves the state -/// inconsistent (at worst the catalog is missing an entry, while `owned` and `reservations` still +/// inconsistent (at worst the catalog is missing an entry, while `owned` and `gate` still /// describe exactly what is live), so poisoning protects nothing here. It would only turn the next /// [`Rendition`](super::Rendition) drop into a panic during unwinding, which aborts the process. fn take(state: &Mutex>) -> MutexGuard<'_, State> { @@ -256,23 +262,24 @@ fn owner_key(name: &str) -> (std::any::TypeId, String) { /// The initial-publish gate, tracking the [`Reserved`](super::Reserved) handles still outstanding. /// -/// The initial catalog snapshot is withheld from the broadcast until `reservers == 0`. A live -/// `Reserved` counts as one reserver; a [`Rendition`](super::Rendition) holds its own `Reserved` -/// clone until it's fulfilled (or dropped), so an unresolved rendition keeps the gate shut too. See -/// [`Reserved`](super::Reserved). +/// A live `Reserved` counts as one reserver; a [`Rendition`](super::Rendition) holds its own +/// `Reserved` clone until it's fulfilled (or dropped), so an unresolved rendition keeps the gate +/// shut too. See [`Reserved`](super::Reserved). #[derive(Default)] -struct Reservations { - /// Live `Reserved` handles (including the one each unfulfilled `Rendition` holds). - reservers: usize, - /// A catalog change was made while buffering and is awaiting the initial publish. Without this - /// we'd emit an empty snapshot when the gate opens on a catalog nobody ever touched. - pending: bool, - /// Whether the initial snapshot has been published (buffering is over). - published: bool, - /// Whether anything ever reserved, making this an importer's catalog: its initial snapshot also - /// waits for a [listed track](State::lists_track), so input that declares none never announces. - /// An incremental producer that never reserves publishes as it goes. - reserved: bool, +enum Gate { + /// Nothing ever reserved: an incremental producer publishes as it goes. + #[default] + Unreserved, + /// An importer's catalog, withholding its initial snapshot until no reservation is outstanding + /// and it [lists a track](State::lists_track), so input that declares none never announces. + Buffering { + reservers: usize, + /// A catalog change was made while buffering and is awaiting the initial publish. Without + /// this we'd emit an empty snapshot when the gate opens on a catalog nobody ever touched. + pending: bool, + }, + /// The initial snapshot went out: every change publishes. + Published, } /// The catalog tracks. @@ -512,7 +519,7 @@ impl Producer { catalog, owned: BTreeMap::new(), ext_tracks: None, - reservations: Reservations::default(), + gate: Gate::default(), closed: None, clock, anchored, @@ -807,8 +814,17 @@ impl Producer { /// Register a live [`Reserved`](super::Reserved) handle. pub(super) fn add_reserver(&self) { let mut state = take(&self.current); - state.reservations.reservers += 1; - state.reservations.reserved = true; + match &mut state.gate { + Gate::Unreserved => { + state.gate = Gate::Buffering { + reservers: 1, + pending: false, + } + } + Gate::Buffering { reservers, .. } => *reservers += 1, + // Only the initial publish waits for reservations. + Gate::Published => {} + } } /// Drop a [`Reserved`](super::Reserved) handle, flushing the initial snapshot if that was the @@ -816,8 +832,9 @@ impl Producer { pub(super) fn release_reserver(&mut self) { { let mut state = take(&self.current); - let r = &mut state.reservations; - r.reservers = r.reservers.saturating_sub(1); + if let Gate::Buffering { reservers, .. } = &mut state.gate { + *reservers = reservers.saturating_sub(1); + } } self.flush_if_ready(); } @@ -825,16 +842,12 @@ impl Producer { /// Publish the buffered snapshot once, if buffering has just finished with a change staged. pub(super) fn flush_if_ready(&mut self) { let mut state = take(&self.current); - let r = &state.reservations; // Nothing was staged (e.g. every stream was ignored): stay unpublished so a later change - // still triggers the first emit, rather than publishing an empty catalog now. The track - // scan runs last, so releasing each of many reservations stays linear. - if r.published || r.reservers != 0 || !r.pending || !state.lists_track() { + // still triggers the first emit, rather than publishing an empty catalog now. + if !matches!(state.gate, Gate::Buffering { pending: true, .. }) || !state.gate_opens() { return; } - let r = &mut state.reservations; - r.pending = false; - r.published = true; + state.gate = Gate::Published; // A snapshot on the wire is a mapping a reader may have copied. state.anchored = true; state.estimates.fold(); @@ -1142,20 +1155,16 @@ impl Guard<'_, E> { self.state.catalog.media.clock = self.state.clock.wall(); adopted?; - { - // Withhold every emit while still buffering the initial reserved set, or until a reserved - // catalog names a track; the mutation stays in `current` and `pending` marks it for the - // flush once the gate opens. The track scan runs last, so a published catalog skips it. - let r = &self.state.reservations; - let withhold = !r.published && (r.reservers != 0 || (r.reserved && !self.state.lists_track())); - let r = &mut self.state.reservations; - if withhold { - r.pending = true; - return Ok(()); + // Withhold every emit while still buffering the initial reserved set, or until a reserved + // catalog names a track; the mutation stays in `current` and `pending` marks it for the + // flush once the gate opens. + if matches!(self.state.gate, Gate::Buffering { .. }) && !self.state.gate_opens() { + if let Gate::Buffering { pending, .. } = &mut self.state.gate { + *pending = true; } - r.pending = false; - r.published = true; + return Ok(()); } + self.state.gate = Gate::Published; // A snapshot on the wire is a mapping a reader may have copied. self.state.anchored = true; diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index fbfd63b514c..29d0872c2a7 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -127,8 +127,7 @@ pub(crate) enum Item { /// moves on to the next group like a skip past a slow group, read or not: the consumer can hold no /// more of what it would wait behind. pub struct Consumer { - // Dropped once an error ends the reader, releasing the publisher's demand. - track: Option, + reader: Reader, name: std::sync::Arc, format: F, @@ -152,13 +151,8 @@ pub struct Consumer { // once a skip refunds room: it pulls again itself. gated: bool, - // The subscription named no floor when the consumer was built, so the cursor has yet to - // choose its first group: the floor once resolved, raised to the publisher's resolved - // start, or else the first arrivals. Cleared once one is chosen. - startup: bool, - - // Latch onto the newest group instead, discarding what arrived below it. - newest: bool, + // How the cursor chooses its first group. + startup: Startup, // How far behind the live edge an unfloored start reaches, before the warmup: see `Delay::min`. min_delay: std::time::Duration, @@ -166,9 +160,6 @@ pub struct Consumer { // How much further than the min delay an unfloored start reaches: see `Playout`. warmup: std::time::Duration, - // When the newest group had landed as the first one arrived, once an unfloored start waits. - anchor: Option, - // The point an unfloored start reached back to, the live edge less the reach, once it chose. target: Option, @@ -207,9 +198,31 @@ pub struct Consumer { // The group the last event came from. group: u64, +} - // The track failed, so no group can arrive. Returned once the groups already here drain. - track_error: Option, +/// Whether a [`Consumer`] still reads its subscription. +enum Reader { + /// Receiving groups. + Reading(moq_net::track::Subscriber), + /// The track failed, so no group can arrive. The error is returned once the groups already here + /// drain. + Failed(moq_net::track::Subscriber, E), + /// An error ended the reader, which reads as finished from then on. The subscription is + /// released, and the publisher's demand with it. + Ended, +} + +/// How a [`Consumer`]'s cursor chooses its first group. +#[derive(Clone, Copy)] +enum Startup { + /// The floor once resolved, raised to the publisher's resolved start, or else the first + /// arrivals. `anchor` is when the newest group had landed as the first one arrived, once such a + /// start waits for its reach. + Earliest { anchor: Option }, + /// The newest group, discarding what arrived below it. + Newest, + /// The cursor is on its first group or past it. + Started, } /// Two adjacent groups are timeline-contiguous when the next start is within this slack @@ -366,7 +379,7 @@ impl Consumer { .min(track.info().max_age.unwrap_or(std::time::Duration::MAX)); Self { name: track.name().into(), - track: Some(track), + reader: Reader::Reading(track), format, current: start.unwrap_or(0), pending: VecDeque::new(), @@ -374,11 +387,9 @@ impl Consumer { collect_at: 1, memory: Memory::new(DEFAULT_MAX_BUFFER), gated: false, - startup: true, - newest: false, + startup: Startup::Earliest { anchor: None }, min_delay: subscription.delay.min.unwrap_or_default(), warmup: std::time::Duration::ZERO, - anchor: None, target: None, warmed: None, max_delay, @@ -390,7 +401,6 @@ impl Consumer { gap: false, next: None, group: 0, - track_error: None, } } @@ -399,8 +409,7 @@ impl Consumer { /// subscription keeps its budget, so every group after the start arrives as it would for any /// reader; what arrived below the start is discarded. pub(crate) fn live(mut self) -> Self { - self.startup = true; - self.newest = true; + self.startup = Startup::Newest; self } @@ -486,14 +495,14 @@ impl Consumer { pub(crate) fn poll_event(&mut self, waiter: &kio::Waiter) -> Poll, F::Error>> { // An error ended the reader, which reads as finished from then on: a decode error has // already consumed the frame it came from, so reading on would skip it. - if self.track.is_none() { + if let Reader::Ended = self.reader { return Poll::Ready(Ok(None)); } let event = ready!(self.poll_event_inner(waiter)); if event.is_err() { // Nothing more is read, so release the subscription and the groups it holds rather // than pin the publisher's demand and cache for as long as the caller keeps this. - self.track = None; + self.reader = Reader::Ended; self.pending.clear(); } Poll::Ready(event) @@ -520,7 +529,7 @@ impl Consumer { // below, since timestamps can't reveal it: a gap below the served window looks like // in-flight groups until the budget expires, or forever on a quiet track. Skipping // stays the budget's job. - if self.startup && !self.newest { + if let Startup::Earliest { .. } = self.startup { let floor = self.subscriber().floor(); let served = match self.subscriber().poll_start(waiter) { Poll::Ready(served) => served, @@ -535,10 +544,10 @@ impl Consumer { if let Some(start) = start { self.pending.retain(|group| group.sequence >= start); self.current = start; - self.startup = false; + self.startup = Startup::Started; } } - if self.startup { + if !matches!(self.startup, Startup::Started) { // NOTE: poll_min_timestamp buffers at least one frame per group and // registers the waiter on the ones still empty. Any wire frame counts, so a // paused track whose only group is a marker still reads its end. The oldest @@ -553,7 +562,7 @@ impl Consumer { // largest names it before its stream lands: the backlog's oldest group can arrive // first, and starting there loses the groups after it once the live edge moves a // budget past them. - let start = match self.newest { + let start = match matches!(self.startup, Startup::Newest) { true => { let mut start = self.pending.back().expect("a group has a frame").sequence; while let Poll::Ready(Some(largest)) = self.subscriber().poll_largest(waiter) { @@ -570,7 +579,7 @@ impl Consumer { // Nothing has been read, so discarding what lies below the start is no gap. self.discard(|group| group.sequence < start)?; self.current = start; - self.startup = false; + self.startup = Startup::Started; } } @@ -734,10 +743,12 @@ impl Consumer { let since = front.late; let elapsed = since.elapsed() >= self.max_delay; let aged = next_group.is_some_and(|(_, start)| max_timestamp.saturating_sub(start) >= self.max_delay); - let excluded = self - .track - .as_ref() - .is_some_and(|track| track.next_in_range(self.current).is_none_or(|next| next >= sequence)); + let excluded = match &self.reader { + Reader::Reading(track) | Reader::Failed(track, _) => { + track.next_in_range(self.current).is_none_or(|next| next >= sequence) + } + Reader::Ended => false, + }; // The groups past the hole already fill the max buffer, so it can hold none of what // would arrive into it. let full = self.memory.full(); @@ -799,7 +810,9 @@ impl Consumer { } if finished && self.pending.is_empty() { - if let Some(err) = self.track_error.take() { + if let Reader::Failed(..) = self.reader + && let Reader::Failed(_, err) = std::mem::replace(&mut self.reader, Reader::Ended) + { // The caller only gets the bare error, with nothing to say which track died. tracing::warn!(track = &*self.name, error = ?err, "track failed; ending the reader"); return Poll::Ready(Err(err)); @@ -961,9 +974,11 @@ impl Consumer { } // Wall time: the newest group landed a whole reach ago. - let arrived = *self - .anchor - .get_or_insert_with(|| self.pending.back().expect("a group has a frame").group.arrived()); + let landed = self.pending.back().expect("a group has a frame").group.arrived(); + let arrived = match &mut self.startup { + Startup::Earliest { anchor } => *anchor.get_or_insert(landed), + Startup::Newest | Startup::Started => landed, + }; if arrived.elapsed() >= reach { return Some(lowest); } @@ -985,7 +1000,10 @@ impl Consumer { // The subscription, which only an error ending the reader drops. fn subscriber(&mut self) -> &mut moq_net::track::Subscriber { - self.track.as_mut().expect("read only until an error ends the reader") + match &mut self.reader { + Reader::Reading(track) | Reader::Failed(track, _) => track, + Reader::Ended => unreachable!("read only until an error ends the reader"), + } } // Media this reader will never deliver: the next item is preceded by a gap. @@ -1008,11 +1026,11 @@ impl Consumer { /// Receive group handles and wait for the track and every received group to finish. pub(crate) fn poll_received(&mut self, waiter: &kio::Waiter) -> Poll<()> { - if self.track.is_none() { + if let Reader::Ended = self.reader { return Poll::Ready(()); } ready!(self.poll_read_finish(waiter)); - if self.track_error.is_some() { + if let Reader::Failed(..) = self.reader { return Poll::Pending; } let first = self @@ -1033,7 +1051,7 @@ impl Consumer { fn poll_read_finish(&mut self, waiter: &kio::Waiter) -> Poll<()> { self.collect_pending(waiter); self.gated = false; - if self.track_error.is_some() { + if let Reader::Failed(..) = self.reader { return Poll::Ready(()); } loop { @@ -1046,7 +1064,9 @@ impl Consumer { let next = match ready!(self.subscriber().poll_recv_group(waiter)) { Ok(next) => next, Err(err) => { - self.track_error = Some(err.into()); + if let Reader::Reading(track) = std::mem::replace(&mut self.reader, Reader::Ended) { + self.reader = Reader::Failed(track, err.into()); + } return Poll::Ready(()); } }; @@ -1163,7 +1183,7 @@ impl Consumer { /// nothing older. pub fn set_delay(&mut self, delay: Delay) { // An ended reader has no subscription left to tune. - let Some(track) = &mut self.track else { + let (Reader::Reading(track) | Reader::Failed(track, _)) = &mut self.reader else { return; }; self.min_delay = delay.min.unwrap_or_default(); @@ -1516,6 +1536,14 @@ mod tests { use super::Container as ContainerTrait; use super::*; use crate::catalog::hang::Container; + + /// The subscription a consumer still reads. + fn subscribed(consumer: &Consumer) -> &moq_net::track::Subscriber { + match &consumer.reader { + Reader::Reading(track) | Reader::Failed(track, _) => track, + Reader::Ended => panic!("the reader ended"), + } + } use std::time::Duration; use bytes::Bytes; @@ -3731,7 +3759,7 @@ mod tests { max: Some(Duration::from_millis(500)), }); assert!( - consumer.startup, + matches!(consumer.startup, Startup::Earliest { .. }), "a local range names no start, so the start still reaches back" ); @@ -3799,7 +3827,7 @@ mod tests { Duration::from_millis(200), Duration::from_millis(300), ); - let subscription = consumer.track.as_ref().unwrap().subscription(); + let subscription = subscribed(&consumer).subscription(); assert_eq!(subscription.delay.min, Some(Duration::from_secs(2))); assert_eq!(subscription.delay.max, Some(Duration::from_millis(500))); assert_eq!(consumer.max_delay, Duration::from_millis(200)); @@ -3817,7 +3845,7 @@ mod tests { let consumer_track = track.subscribe(moq_net::track::Subscription::default().with_delay(delay)); let consumer = Playout::new(delay, Duration::from_millis(300)) .consumer(consumer_track, Container::Legacy(crate::container::Kind::Data)); - let subscription = consumer.track.as_ref().unwrap().subscription(); + let subscription = subscribed(&consumer).subscription(); assert_eq!(subscription.delay.min, Some(Duration::from_millis(100))); assert_eq!(subscription.delay.max, Some(Duration::from_millis(500))); assert_eq!(consumer.max_delay, Duration::from_millis(200)); @@ -3837,7 +3865,7 @@ mod tests { min: Some(Duration::from_millis(500)), max: None, }); - assert_eq!(consumer.track.as_ref().unwrap().subscription().delay.max, None); + assert_eq!(subscribed(&consumer).subscription().delay.max, None); write_group(&mut track, 5, &[ts(5_000_000)]); assert!( diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index 99f4e56a7a4..106addf2edc 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -58,17 +58,41 @@ impl VideoTransform { /// A subscription that resolves on first poll, then the live consumer. enum SourceState { /// Waiting for the target broadcast (the catalog broadcast, or a cross-broadcast - /// reference) to resolve; the track (by name) is subscribed once it does. - Requesting(crate::Binding, String), + /// reference) to resolve; [`Target::track`] is subscribed once it does. + Requesting { binding: crate::Binding, start: Start }, /// Waiting for the subscription to resolve (blocks on the publisher's SUBSCRIBE_OK). - Subscribing(kio::Pending), + Subscribing { + pending: Box>, + media: HangContainer, + live: bool, + instance: Option, + }, /// The resolved consumer, reading frames. Boxed because it's much larger than - /// the `Subscribing` variant (clippy `large_enum_variant`). - Active(Box>), - /// The sibling instance it read went, and its rendition with it. + /// the other variants (clippy `large_enum_variant`). + Active(Box), + /// The track ended, the sibling instance it read went, or the source was stopped. Ended, } +/// How a source subscribes, fixed before its first poll. +struct Start { + /// Wire format the consumer decodes. + media: HangContainer, + /// Start at the newest group, rather than the oldest the max delay still reaches. + live: bool, + /// Read only groups after this one, so a resubscription skips groups already read. + after: Option, +} + +/// A resolved subscription. +struct Active { + consumer: Consumer, + /// Keeps the subscription's priority registered while it reads. + _priority: crate::source::Priority, + /// The sibling broadcast the rendition reads: its end ends the rendition. + instance: Option, +} + /// The track a source reads: its broadcast's path, the instance that broadcast must have, and /// the track's name there. #[derive(Clone, Debug, PartialEq, Eq)] @@ -88,9 +112,15 @@ impl Target { }) } - fn request(&self, source: &crate::Source) -> SourceState { - let binding = source.request_path(&self.path, self.instance.as_ref()); - SourceState::Requesting(binding, self.track.clone()) + fn request(&self, source: &crate::Source, media: HangContainer) -> SourceState { + SourceState::Requesting { + binding: source.request_path(&self.path, self.instance.as_ref()), + start: Start { + media, + live: false, + after: None, + }, + } } } @@ -118,16 +148,9 @@ pub(crate) struct ExportSource { /// The rendition's ID in the catalog. name: String, source: crate::Source, - priority_control: Option, target: Target, state: SourceState, - /// Wire format, consumed when the subscription resolves into a consumer. - media: Option, max_delay: std::time::Duration, - /// Start at the newest group, rather than the oldest the max delay still reaches. - live: bool, - /// Read only groups after this one, so a resubscription skips groups already read. - after: Option, transform: Option, /// Resolved codec configuration record (avcC / hvcC / AudioSpecificConfig / /// OpusHead). Some once the codec config is available - from the catalog @@ -155,8 +178,6 @@ pub(crate) struct ExportSource { delivered: Option, /// Set while continuing another source, until the first sync frame past what it delivered. splice: Option, - /// The sibling broadcast the rendition reads, once resolved: its end ends the rendition. - instance: Option, } impl ExportSource { @@ -280,13 +301,9 @@ impl ExportSource { Self { name: name.to_string(), source: source.clone(), - priority_control: None, - state: target.request(source), + state: target.request(source, media), target, - media: Some(media), max_delay, - live: false, - after: None, transform: None, description: None, video_codec: None, @@ -301,7 +318,6 @@ impl ExportSource { latest: None, delivered: None, splice: None, - instance: None, } } @@ -340,9 +356,9 @@ impl ExportSource { /// that still does fails with [`Error::RenditionRewound`](crate::Error::RenditionRewound). pub(crate) fn resuming(mut self, resume: &Resume) -> Self { if resume.target == self.target { - self.after = resume.group; + self.start().after = resume.group; } else { - self.live = true; + self.start().live = true; self.splice = resume.latest.map(|read| Splice { read, group: None }); } self.latest = resume.latest; @@ -354,15 +370,24 @@ impl ExportSource { /// hop drops each group a newer one supersedes, and raising it later cannot recover the /// groups that follow the edge. pub fn live(mut self) -> Self { - self.live = true; + self.start().live = true; self } + /// The subscription options a builder sets. Each builder consumes a source no poll has + /// moved out of [`SourceState::Requesting`], since only the constructors hand one out. + fn start(&mut self) -> &mut Start { + match &mut self.state { + SourceState::Requesting { start, .. } => start, + _ => unreachable!("configured after polling"), + } + } + /// The group sequence of the last frame read, or None until the subscription resolves. /// Meaningful only once a frame was read. pub(crate) fn group(&self) -> Option { match &self.state { - SourceState::Active(consumer) => Some(consumer.group()), + SourceState::Active(active) => Some(active.consumer.group()), _ => None, } } @@ -451,7 +476,7 @@ impl ExportSource { /// Receive group handles and wait for all input bytes while frame delivery is backpressured. pub fn poll_received(&mut self, waiter: &kio::Waiter) -> Poll<()> { match &mut self.state { - SourceState::Active(consumer) => consumer.poll_received(waiter), + SourceState::Active(active) => active.consumer.poll_received(waiter), SourceState::Ended => Poll::Ready(()), _ => Poll::Pending, } @@ -504,73 +529,75 @@ impl ExportSource { /// Read the track's normalized media or a clean group boundary. fn poll_track(&mut self, waiter: &kio::Waiter) -> Poll>> { - if matches!(self.state, SourceState::Ended) { - return Poll::Ready(Ok(None)); - } - // Resolve a cross-broadcast reference into a broadcast before subscribing. - if matches!(self.state, SourceState::Requesting(..)) { - let (broadcast, name, sibling) = { - let SourceState::Requesting(pending, name) = &self.state else { - unreachable!("just matched Requesting"); - }; - (ready!(pending.poll_broadcast(waiter))?, name.clone(), pending.sibling()) - }; - if sibling { - self.instance = Some(broadcast.clone()); - } + if let SourceState::Requesting { binding, start } = &self.state { + let broadcast = ready!(binding.poll_broadcast(waiter))?; + let instance = binding.sibling().then(|| broadcast.clone()); let mut subscription = moq_net::track::Subscription::default() .with_delay(moq_net::track::Delay::default().with_max(self.max_delay)); - if let Some(after) = self.after { + if let Some(after) = start.after { subscription = subscription.with_range((Bound::Excluded(after), Bound::Unbounded)); } - let track = match broadcast.track(&name) { + let track = match broadcast.track(&self.target.track) { Ok(track) => track, - Err(_) if self.instance_ended(waiter) => return self.end(), + Err(_) if instance.as_ref().is_some_and(|i| i.poll_closed(waiter).is_ready()) => return self.end(), Err(err) => return Poll::Ready(Err(err.into())), }; - self.state = SourceState::Subscribing(track.subscribe(self.source.subscription(subscription))); + let pending = Box::new(track.subscribe(self.source.subscription(subscription))); + let SourceState::Requesting { start, .. } = std::mem::replace(&mut self.state, SourceState::Ended) else { + unreachable!("just matched Requesting"); + }; + self.state = SourceState::Subscribing { + pending, + media: start.media, + live: start.live, + instance, + }; } // Resolve the subscription before reading any frames. - if matches!(self.state, SourceState::Subscribing(_)) { - // Scope the `pending` borrow so it ends before we touch `self.media`/`self.state`. - let track = { - let SourceState::Subscribing(pending) = &self.state else { - unreachable!("just matched Subscribing"); - }; - match pending.poll_ok(waiter) { - Poll::Ready(Ok(track)) => track, - Poll::Ready(Err(_)) | Poll::Pending if self.instance_ended(waiter) => return self.end(), - Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), - Poll::Pending => return Poll::Pending, + if let SourceState::Subscribing { pending, instance, .. } = &self.state { + let track = match pending.poll_ok(waiter) { + Poll::Ready(Ok(track)) => track, + Poll::Ready(Err(_)) | Poll::Pending + if instance.as_ref().is_some_and(|i| i.poll_closed(waiter).is_ready()) => + { + return self.end(); } + Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), + Poll::Pending => return Poll::Pending, + }; + let priority = self.source.control(track.control())?; + let SourceState::Subscribing { + media, live, instance, .. + } = std::mem::replace(&mut self.state, SourceState::Ended) + else { + unreachable!("just matched Subscribing"); }; - let media = self - .media - .take() - .expect("media present until the subscription resolves"); - self.priority_control = Some(self.source.control(track.control())?); let consumer = Consumer::new(track, media); - let consumer = match self.live { + let consumer = match live { true => consumer.live(), false => consumer, }; - self.state = SourceState::Active(Box::new(consumer)); + self.state = SourceState::Active(Box::new(Active { + consumer, + _priority: priority, + instance, + })); } loop { // Scope the consumer borrow to the poll so `self.transform` / // `self.refresh_description` can borrow `self` afterwards. let (frame, arrived) = { - let SourceState::Active(consumer) = &mut self.state else { - unreachable!("subscription resolved into an Active consumer"); + let SourceState::Active(active) = &mut self.state else { + return Poll::Ready(Ok(None)); }; + let consumer = &mut active.consumer; let item = match consumer.poll_item(waiter) { Poll::Ready(Ok(item)) => item, // Only an orderly shutdown of the instance is its end: malformed media or a - // failed transport still fails the export. The field, not `instance_ended`, so - // the borrow stays off the consumer. + // failed transport still fails the export. Poll::Ready(Err(crate::Error::Moq( moq_net::Error::Cancel | moq_net::Error::Closed @@ -579,7 +606,7 @@ impl ExportSource { | moq_net::Error::Session(moq_net::SessionError::Cancel), ))) | Poll::Pending - if self + if active .instance .as_ref() .is_some_and(|instance| instance.poll_closed(waiter).is_ready()) => @@ -630,11 +657,7 @@ impl ExportSource { self.cuts += u64::from(std::mem::take(&mut self.open)); return Poll::Ready(Ok(Some(Event::Cut { observed }))); } - None => { - self.priority_control = None; - self.finish_ends(); - return Poll::Ready(Ok(None)); - } + None => return self.end(), } }; @@ -669,29 +692,29 @@ impl ExportSource { } } - /// Whether the sibling broadcast this rendition reads has stopped serving, registering - /// `waiter` for when it does. Its track stalling or failing then is that instance's end, - /// which ends the rendition rather than the export once what it delivered is read; following - /// the instance that replaces it is the export's own call. - fn instance_ended(&self, waiter: &kio::Waiter) -> bool { - self.instance - .as_ref() - .is_some_and(|instance| instance.poll_closed(waiter).is_ready()) - } - /// Release a replaced instance's subscription while keeping its resolved metadata. pub(crate) fn stop(&mut self) { self.finish_ends(); self.state = SourceState::Ended; - self.priority_control = None; - self.instance = None; } - /// End the rendition with its instance. + /// Whether the sibling broadcast this rendition reads has stopped serving. + #[cfg(test)] + fn instance_ended(&self, waiter: &kio::Waiter) -> bool { + let instance = match &self.state { + SourceState::Subscribing { instance, .. } => instance.as_ref(), + SourceState::Active(active) => active.instance.as_ref(), + _ => None, + }; + instance.is_some_and(|instance| instance.poll_closed(waiter).is_ready()) + } + + /// End the rendition: its track ended, or the sibling instance it read went. Its track + /// stalling or failing then is that instance's end, which ends the rendition rather than the + /// export once what it delivered is read; following the instance that replaces it is the + /// export's own call. fn end(&mut self) -> Poll>> { - self.finish_ends(); - self.state = SourceState::Ended; - self.priority_control = None; + self.stop(); Poll::Ready(Ok(None)) } @@ -1355,14 +1378,15 @@ mod tests { .produce() .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); - let consumer = Consumer::new( - track.subscribe( - moq_net::track::Subscription::default() - .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(10))), - ), - HangContainer::Legacy(crate::container::Kind::Audio), + let subscribed = track.subscribe( + moq_net::track::Subscription::default() + .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(10))), ); - export.state = SourceState::Active(Box::new(consumer)); + export.state = SourceState::Active(Box::new(Active { + _priority: export.source.control(subscribed.control()).unwrap(), + consumer: Consumer::new(subscribed, HangContainer::Legacy(crate::container::Kind::Audio)), + instance: None, + })); (track, export) } diff --git a/rs/moq-mux/src/jitter.rs b/rs/moq-mux/src/jitter.rs index 00209a8c89d..a654f641ddb 100644 --- a/rs/moq-mux/src/jitter.rs +++ b/rs/moq-mux/src/jitter.rs @@ -221,7 +221,9 @@ impl Buffer { let cut = std::mem::take(&mut track.queue).len() as u64; track.bytes = 0; // A cancel resumes the old publisher, whose next frames may reference the cut ones. - track.waiting |= cut > 0; + if cut > 0 { + track.admit = Admit::Waiting; + } match track.started { true => self.active.dropped += cut, false => self.active.trimmed += cut, @@ -741,6 +743,18 @@ struct Floor { began: Instant, } +/// Which frames a track admits to its queue. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +enum Admit { + /// Every frame that makes its deadline. + Flowing, + /// None until the next sync frame. + Waiting, + /// It resumed at its last sync frame after waiting, whose leading frames are dropped too: + /// they reference the frames dropped while waiting. + Resumed, +} + struct Track { /// Frames in arrival order, each with its generation, decode time, deadline and bytes. queue: VecDeque<(u64, Decode, Instant, T, usize)>, @@ -754,11 +768,7 @@ struct Track { arrived: Instant, /// The generation of the last frame. generation: u64, - /// Frames are dropped until the next sync frame. - waiting: bool, - /// Whether the track resumed at its last sync frame after waiting, whose leading frames are - /// dropped too. - resumed: bool, + admit: Admit, /// Whether a frame of it has gone out. Until one has, a loss takes everything it holds. started: bool, } @@ -1035,8 +1045,7 @@ impl Engine { decode: arrival.decode, arrived: arrival.arrived, generation, - waiting: false, - resumed: false, + admit: Admit::Flowing, started: false, }); track.restart = arrival.restart; @@ -1045,16 +1054,19 @@ impl Engine { track.generation = generation; let push = match deadline { _ if stale => { - track.waiting = true; + track.admit = Admit::Waiting; Push::Waiting } - _ if track.waiting && !arrival.sync => Push::Waiting, - _ if track.resumed && arrival.leading => Push::Waiting, + _ if track.admit == Admit::Waiting && !arrival.sync => Push::Waiting, + _ if track.admit == Admit::Resumed && arrival.leading => Push::Waiting, Some(deadline) if arrival.arrived <= deadline || self.delay.is_zero() => { + // A frame past the checks above while waiting is a sync frame. if arrival.sync { - track.resumed = track.waiting; + track.admit = match track.admit { + Admit::Waiting => Admit::Resumed, + Admit::Flowing | Admit::Resumed => Admit::Flowing, + }; } - track.waiting = false; let cost = arrival.cost(); track.bytes += cost; track @@ -1065,7 +1077,7 @@ impl Engine { } // Past the deadline, or so far off the clock that no instant holds it. _ => { - track.waiting = true; + track.admit = Admit::Waiting; Push::Late } }; @@ -1073,7 +1085,7 @@ impl Engine { Push::Queued => {} _ if track.started => self.dropped += 1, // A leading frame of the sync frame the track starts at, which stays queued. - _ if !track.waiting => self.trimmed += 1, + _ if track.admit != Admit::Waiting => self.trimmed += 1, _ => { self.trimmed += 1 + track.queue.len() as u64; track.queue.clear(); diff --git a/rs/moq-rtmp/src/rml/sessions/server/mod.rs b/rs/moq-rtmp/src/rml/sessions/server/mod.rs index c92f804eb33..bd1c0605424 100644 --- a/rs/moq-rtmp/src/rml/sessions/server/mod.rs +++ b/rs/moq-rtmp/src/rml/sessions/server/mod.rs @@ -52,7 +52,6 @@ pub struct ServerSession { start_time: Instant, serializer: ChunkSerializer, deserializer: ChunkDeserializer, - connected_app_name: Option, request: Option, current_state: SessionState, fms_version: String, @@ -75,7 +74,6 @@ impl ServerSession { start_time: Instant::now(), serializer: ChunkSerializer::new(), deserializer: ChunkDeserializer::new(), - connected_app_name: None, request: None, current_state: SessionState::Started, fms_version: config.fms_version, @@ -487,7 +485,7 @@ impl ServerSession { transaction_id: f64, command_object: Value<'_>, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Started || self.request.is_some() { + if !matches!(self.current_state, SessionState::Started) || self.request.is_some() { return Err(ServerSessionError::RepeatedConnect); } @@ -649,13 +647,8 @@ impl ServerSession { &mut self, mut arguments: Values<'_>, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { return Ok(Vec::new()); - } - - let app_name = match self.connected_app_name { - Some(ref name) => name.clone(), - None => return Ok(Vec::new()), }; // First argument should be the stream id to close @@ -720,7 +713,7 @@ impl ServerSession { &mut self, transaction_id: f64, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected || self.active_stream.is_some() { + if self.app_name().is_none() || self.active_stream.is_some() { let packet = self.create_error_packet( "NetConnection.Call.Failed", "one stream is allowed after connect", @@ -763,7 +756,7 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { let packet = self.create_error_packet( "NetStream.Publish.Start", "Can't publish before connecting", @@ -771,7 +764,7 @@ impl ServerSession { stream_id, )?; return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } + }; if !matches!( self.active_stream.as_ref().filter(|_| stream_id == 1), @@ -788,19 +781,6 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - let app_name = match self.connected_app_name { - Some(ref name) => name.clone(), - None => { - let packet = self.create_error_packet( - "NetStream.Publish.Start", - "Can't publish before connecting", - transaction_id, - stream_id, - )?; - return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } - }; - let stream_key = match arguments.next().unwrap() { Value::Utf8String(stream_key) => stream_key.to_owned(), _ => { @@ -880,7 +860,7 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { let packet = self.create_error_packet( "NetStream.Play.Start", "Can't play before connecting", @@ -888,7 +868,7 @@ impl ServerSession { stream_id, )?; return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } + }; if !matches!( self.active_stream.as_ref().filter(|_| stream_id == 1), @@ -905,19 +885,6 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - let app_name = match self.connected_app_name { - Some(ref name) => name.clone(), - None => { - let packet = self.create_error_packet( - "NetStream.Play.Start", - "Can't play before connecting", - transaction_id, - stream_id, - )?; - return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } - }; - let stream_key = match arguments.next().unwrap() { Value::Utf8String(stream_key) => stream_key.to_owned(), _ => { @@ -1024,7 +991,7 @@ impl ServerSession { return None; } - let app_name = self.connected_app_name.clone()?; + let app_name = self.app_name()?; let StreamState::Publishing { ref stream_key, .. } = self.active_stream.as_ref().filter(|_| stream_id == 1)?.current_state else { @@ -1049,14 +1016,9 @@ impl ServerSession { stream_id: u32, timestamp: RtmpTimestamp, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { // Audio data sent before connected, just ignore it. return Ok(Vec::new()); - } - - let app_name = match self.connected_app_name { - Some(ref x) => x.clone(), - None => return Ok(Vec::new()), // No app name so we aren't in a valid connection state. }; let publish_stream_key = match self.active_stream.as_ref().filter(|_| stream_id == 1) { @@ -1133,14 +1095,9 @@ impl ServerSession { stream_id: u32, timestamp: RtmpTimestamp, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { // Video data sent before connected, just ignore it. return Ok(Vec::new()); - } - - let app_name = match self.connected_app_name { - Some(ref x) => x.clone(), - None => return Ok(Vec::new()), // No app name so we aren't in a valid connection state. }; let publish_stream_key = match self.active_stream.as_ref().filter(|_| stream_id == 1) { @@ -1172,13 +1129,22 @@ impl ServerSession { Ok(Vec::new()) } + /// The app name a connect accepted, while connected. + fn app_name(&self) -> Option { + match &self.current_state { + SessionState::Connected { app_name } => Some(app_name.clone()), + SessionState::Started | SessionState::Completed => None, + } + } + fn accept_connection_request( &mut self, app_name: String, transaction_id: f64, ) -> Result, ServerSessionError> { - self.connected_app_name = Some(app_name.clone()); - self.current_state = SessionState::Connected; + self.current_state = SessionState::Connected { + app_name: app_name.clone(), + }; let mut command_object_properties = HashMap::new(); command_object_properties.insert("fmsVer".to_string(), Amf0Value::Utf8String(self.fms_version.clone())); diff --git a/rs/moq-rtmp/src/rml/sessions/server/session_state.rs b/rs/moq-rtmp/src/rml/sessions/server/session_state.rs index 330bec0e73e..c887317fbac 100644 --- a/rs/moq-rtmp/src/rml/sessions/server/session_state.rs +++ b/rs/moq-rtmp/src/rml/sessions/server/session_state.rs @@ -1,6 +1,8 @@ -#[derive(Eq, PartialEq)] pub enum SessionState { Started, - Connected, + /// A connect was accepted for `app_name`. + Connected { + app_name: String, + }, Completed, } diff --git a/rs/moq-webrtc/src/ice/agent.rs b/rs/moq-webrtc/src/ice/agent.rs index 04d29b17453..324c7e16674 100644 --- a/rs/moq-webrtc/src/ice/agent.rs +++ b/rs/moq-webrtc/src/ice/agent.rs @@ -38,7 +38,7 @@ const STUN_SENDS: u32 = 7; const STUN_LAST_WAIT: u32 = 16; /// Why an [`Agent`] stopped. -#[derive(Debug, thiserror::Error)] +#[derive(Clone, Debug, thiserror::Error)] pub enum Error { /// The peer disconnected, str0m closed the connection, or the inbound queue ended. #[error("peer connection closed")] @@ -92,6 +92,19 @@ struct Query { deadline: Instant, } +/// Where the connection is in its life. +enum Phase { + /// An offer awaits its answer, which holds off the [`ESTABLISH_TIMEOUT`]. + Held, + /// ICE has yet to connect; the [`ESTABLISH_TIMEOUT`] runs from `started`. + Establishing { + started: Instant, + }, + Connected, + /// The connection ended, for this reason: every later [`Agent::next`] reports it. + Failed(Error), +} + /// Drives one [`Rtc`] over a UDP socket until the connection ends. pub struct Agent { rtc: Rtc, @@ -109,15 +122,11 @@ pub struct Agent { /// When every STUN query answered or gave up, once [`Event::Gathered`] went out. gathered: Option, events: VecDeque, - /// Why the connection ended, found while draining and reported by the next [`Agent::next`]. - failed: Option, /// When str0m next wants a timeout, as of the last drain. timeout: Instant, /// Datagrams the socket refused for lack of buffer space, sent first next time. outbox: VecDeque<(Vec, SocketAddr)>, - /// When the [`ESTABLISH_TIMEOUT`] started, or `None` while an offer awaits its answer. - started: Option, - connected: bool, + phase: Phase, } impl Agent { @@ -139,11 +148,9 @@ impl Agent { stun: Vec::new(), gathered: None, events: VecDeque::new(), - failed: None, timeout: now, outbox: VecDeque::new(), - started: Some(now), - connected: false, + phase: Phase::Establishing { started: now }, }; // Signaling already changed the connection. agent.drain(); @@ -189,14 +196,18 @@ impl Agent { /// for an offer whose answer has yet to arrive: signaling time is the caller's. #[cfg_attr(not(feature = "p2p"), allow(dead_code, reason = "only the p2p transport offers"))] pub fn awaiting_answer(mut self) -> Self { - self.started = None; + self.phase = Phase::Held; self } /// Change the connection through a guard that drains what the change produced /// when dropped: transmits are sent, and events wait for [`Agent::next`]. pub fn rtc_mut(&mut self) -> RtcMut<'_> { - self.started.get_or_insert_with(Instant::now); + if let Phase::Held = self.phase { + self.phase = Phase::Establishing { + started: Instant::now(), + }; + } self.change() } @@ -214,8 +225,8 @@ impl Agent { if let Some(event) = self.events.pop_front() { return Ok(event); } - if let Some(err) = self.failed.take() { - return Err(err); + if let Phase::Failed(err) = &self.phase { + return Err(err.clone()); } if self.gathered.is_none() && self.stun.is_empty() { self.gathered = Some(Instant::now()); @@ -233,11 +244,13 @@ impl Agent { // A dead Rtc (DTLS failure, explicit disconnect) reports a never-firing // timeout instead of an error, which would park this loop forever. if !self.rtc.is_alive() { - return Err(Error::Closed); + self.fail(Error::Closed); + continue; } let establish = self.establish(); if establish.is_some_and(|at| at <= Instant::now()) { - return Err(Error::Timeout); + self.fail(Error::Timeout); + continue; } let deadline = self.stun.iter().map(|q| q.deadline).chain(establish); @@ -249,7 +262,8 @@ impl Agent { packet = self.inbound.packets.recv() => { let Some((data, src)) = packet else { // Every sender dropped: nothing more will arrive. - return Err(Error::Closed); + self.fail(Error::Closed); + continue; }; self.receive(&data, src); continue; @@ -267,24 +281,26 @@ impl Agent { } } - /// When [`ESTABLISH_TIMEOUT`] expires, or `None` while it is held or ICE connected. + /// When [`ESTABLISH_TIMEOUT`] expires, or `None` while it is held, gathering, or over. fn establish(&self) -> Option { - match (self.started, self.gathered) { - (Some(started), Some(gathered)) if !self.connected => Some(started.max(gathered) + ESTABLISH_TIMEOUT), + match (&self.phase, self.gathered) { + (Phase::Establishing { started }, Some(gathered)) => Some((*started).max(gathered) + ESTABLISH_TIMEOUT), _ => None, } } /// Poll str0m until it asks for a timeout: transmits are sent, events queued. fn drain(&mut self) { - while self.failed.is_none() { + while !matches!(self.phase, Phase::Failed(_)) { let output = match self.rtc.poll_output() { Ok(output) => output, // Before ICE connects no DTLS record can reach the peer, so a DTLS failure // is its handshake giving up on retransmitting into the void. Its flights // (~31s, randomly jittered) race the establishment deadline, so report // either as ICE never connecting. - Err(str0m::RtcError::Dtls(_)) if !self.connected => return self.fail(Error::Timeout), + Err(str0m::RtcError::Dtls(_)) if !matches!(self.phase, Phase::Connected) => { + return self.fail(Error::Timeout); + } Err(err) => return self.fail(Error::rtc(err)), }; match output { @@ -300,7 +316,9 @@ impl Agent { if *state == IceConnectionState::Disconnected { return self.fail(Error::Closed); } - self.connected |= state.is_connected(); + if state.is_connected() { + self.phase = Phase::Connected; + } } self.events.push_back(Event::Rtc(event)); } @@ -310,7 +328,9 @@ impl Agent { /// Keep the first reason the connection ended. fn fail(&mut self, err: Error) { - self.failed.get_or_insert(err); + if !matches!(self.phase, Phase::Failed(_)) { + self.phase = Phase::Failed(err); + } } /// Send without waiting, keeping the datagram for later when the socket is full. @@ -501,12 +521,12 @@ mod tests { #[tokio::test] async fn awaiting_answer_holds_the_deadline() { let mut agent = unpolled().awaiting_answer(); - assert_eq!(agent.started, None); + assert!(matches!(agent.phase, Phase::Held)); // The agent's own changes, such as timeouts and STUN, leave it held. drop(agent.change()); - assert_eq!(agent.started, None); + assert!(matches!(agent.phase, Phase::Held)); drop(agent.rtc_mut()); - assert!(agent.started.is_some()); + assert!(matches!(agent.phase, Phase::Establishing { .. })); } #[tokio::test] @@ -554,6 +574,9 @@ mod tests { }; assert!(matches!(err, Error::Timeout), "{err:?}"); assert_eq!(agent.establish(), None, "the deadline had yet to start"); + // The reason sticks: driving the agent again reports it again. + let again = agent.next().await; + assert!(matches!(again, Err(Error::Timeout)), "{again:?}"); } #[test] diff --git a/rs/moq-webrtc/src/p2p/mod.rs b/rs/moq-webrtc/src/p2p/mod.rs index 755aba406ad..5de3512b8e1 100644 --- a/rs/moq-webrtc/src/p2p/mod.rs +++ b/rs/moq-webrtc/src/p2p/mod.rs @@ -537,8 +537,7 @@ impl Peer { role, max_message, channel: None, - waiter: None, - taken: false, + handout: Handout::Unasked, }; use tracing::Instrument; tokio::spawn(moq_tokio::panic::isolate(driver.run()).instrument(tracing::Span::current())); @@ -643,10 +642,17 @@ struct Driver { /// The remote peer's SCTP message limit, once its description is applied. max_message: Option, channel: Option>, - /// The session waiting for the channel to open. - waiter: Option>>, - /// Whether a session already asked for the channel, which only one may carry. - taken: bool, + handout: Handout, +} + +/// Which session the channel goes to: only one may carry it. +enum Handout { + /// No session asked for the channel yet. + Unasked, + /// A session waits for the channel to open or fail to. + Waiting(oneshot::Sender>), + /// A session took the channel, or heard why it never opened. + Taken, } impl Driver { @@ -684,7 +690,7 @@ impl Driver { Error::Closed => tracing::debug!("peer connection closed"), err => tracing::debug!(%err, "peer connection failed"), } - if let Some(waiter) = self.waiter.take() { + if let Handout::Waiting(waiter) = self.handout { let _ = waiter.send(Err(err)); } } @@ -748,12 +754,11 @@ impl Driver { } Command::Candidate(candidate) => self.agent.rtc_mut().add_remote_candidate(candidate), Command::Channel(reply) => { - if self.taken { + if !matches!(self.handout, Handout::Unasked) { let _ = reply.send(Err(Error::Taken)); return; } - self.taken = true; - self.waiter = Some(reply); + self.handout = Handout::Waiting(reply); self.deliver(); } } @@ -873,7 +878,9 @@ impl Driver { let Some(channel) = &mut self.channel else { return; }; - let Some(waiter) = self.waiter.take() else { + let handout = std::mem::replace(&mut self.handout, Handout::Taken); + let Handout::Waiting(waiter) = handout else { + self.handout = handout; return; }; let result = match channel {