diff --git a/py/moq-rs/tests/test_testing_clock.py b/py/moq-rs/tests/test_testing_clock.py index 2feeb195bdc..10f6256de7d 100644 --- a/py/moq-rs/tests/test_testing_clock.py +++ b/py/moq-rs/tests/test_testing_clock.py @@ -31,7 +31,7 @@ async def main(): # Group 0 stalls with no frame, so the in-order read waits on it until # group 1 has been out for max_delay: a native timer is pending. - track.append_group() + _stalled = track.append_group() later = track.append_group() later.write_frame(b"later") later.finish() diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index fb4613e002b..3f5981bacde 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -101,7 +101,6 @@ Work owned by this README, after the children land: ## Required -- [One group writer](/quest/m1/public-model/group-writer.md) - `group::Producer` is not `Clone`; the model and sessions hold a crate-private handle that cannot write or finish - [Public ingest](/quest/m1/public-model/ingest.md) - a custom subscriber writes received groups, frames, starts, and ends into a track through public calls - [Public serving](/quest/m1/public-model/serve.md) - a custom publisher reads a track's start, cursor, and group expiry for its wire through public calls - [Public routes and answering](/quest/m1/public-model/answer.md) - a custom relay ingests routes, answers broadcast and track requests on demand, and advertises without echoing a peer's routes back diff --git a/quest/m1/public-model/group-writer.md b/quest/m1/public-model/group-writer.md deleted file mode 100644 index 578e67f3f2e..00000000000 --- a/quest/m1/public-model/group-writer.md +++ /dev/null @@ -1,118 +0,0 @@ -# [M] One group writer - -## Goal - -`moq_net::group::Producer` is not `Clone`. Each group has exactly one -writer, so every frame write, `finish`, and abort on it is ordered by -ownership and `&mut self` rather than by lock ordering. The track cache, the -reader handoff, and the built-in sessions hold a crate-private handle that -cannot write or finish. No reader-visible change except the teardown below, -and no wire change. - -## Plan - -Follow-up to #5725 (live largest), chosen by the maintainer there: its -decision 10 ordered frame writes against `finish` with the group lock because -a frame write on one clone could race `finish` on another. - -This is the "drop public `Clone`" half of the owned frame writer decision in -[Public ingest](/quest/m1/public-model/ingest.md) (settled 2026-10-16, -#5717), split out because it stands alone. Ingest keeps the public owned -chunked writer (`create_frame(self)`); this quest only makes it possible. - -What clones a group producer today (compile probe on #5725's head, deleting -`impl Clone`): - -- Outside moq-net, tests only: moq-ffi `MoqGroupProducer::used`, - `rs/moq-net/benches/track.rs` (2), and `rs/moq-net/tests/loom.rs`. -- moq-net unit tests: `group.rs` (6), `track.rs` (2), the IETF publisher - (1) and subscriber (1). -- 13 library sites in moq-net, in four groups: - - Track cache slots (`Slot::group` and the fetched `head` in `track.rs`, - from `insert_group`): cache accounting, eviction, demotion, `bound`, - reads, and abort. - - Reader handoff: `poll_recv_group` and `poll_next_in_range` return a - clone that the caller turns into a consumer. - - Abort through a shared reference, because `abort(self)` consumes: - `Slot::abort`, track abort, the IETF subscriber's fill, and - `group::Producer::frame_abort`. - - Wire ingest: `create_frame_owned` (`frame::ProducerOwned` holds a clone - across polls), the IETF ingest's `writing` clone, the observers for - `demand` (`poll_unused`, `abort_unused`) and `closed` (`poll_closed`), - and the lite subscriber's `reveal_group`. - -Shape: - -- One public writer, `group::Producer`, with no `Clone`. -- A crate-private `group::Handle` minted from the writer that reads group state, - hands out consumers, waits on `poll_closed` and `poll_unused`, aborts - through `&self` (`abort`, `abort_unused`), and backs the cache slot's - accounting and `reveal_group`. It has no write or finish. The 13 sites - above move onto it. It stays crate-private until a third-party session - needs to abort or watch a group it does not own; the ingest decision - already says that need gets a non-writing handle, never `Clone`. -- `frame::ProducerOwned` takes the writer by value and hands it back when - the frame finishes, instead of cloning it. The wire drivers keep the - handle for `poll_closed` and demand while a frame is open. Making that - owned writer public stays with ingest. -- `answer.md`'s public `poll_unused` and `abort_unused` stay on the writer; - the handle carries the same calls for the sessions. -- Once one writer orders writes against `finish`, simplify the group-lock - ordering #5725 added for that race if nothing else needs it, and replace - the loom model `a_frame_racing_finish_never_reopens_the_largest` (it - races two handles, which no longer compiles) with a `compile_fail` - doctest that `let _: group::Producer = producer.clone();` is refused. - Keep any loom coverage that still races a writer against the handle's - abort. - -Behavior change to verify: the "dropped without `finish()` or `abort()`" -teardown (`group::Alive`'s `Drop`, which warns and releases the cached -frames) runs today only when the last clone drops, and the cache slot holds -one, so a writer that drops an unfinished group leaves its readers waiting -until the slot goes. After the split it runs when the writer drops. Split -`Alive` so the handle shares the atomics (`aborted`, `cut`, `checked`, -`access`) but not the drop guard. The guard must now mark the group dead, -not only release its frames: today it leaves `aborted` false and -`GroupState::abort` unset, which was harmless because no handle outlived -it. A surviving `Handle` would then keep serving the released group -(`Slot::is_live`), and `covering_group` would refuse a same-sequence -replacement as `Duplicate`. So a writer dropped unfinished commits an abort -(`Dropped`) through the same path as `abort`. Then check, each with a -mock-time test: - -- A reader of an unfinished group sees `Dropped` when its writer drops, and - the cache releases the frames. -- After that drop, a new reader does not get the dead group, and the - publisher can recreate the same sequence. -- A route that dies mid-group still resumes on its replacement from the - committed frame (`resume_frame`, `resume_position`), which reads the count - that outlives the released cache. -- The sessions' `crate::recv::Group` guard and moq-ffi's - `MoqGroupProducer` still end every group they drop with a terminal. - -If any of those reads worse than today, bring it to the maintainer before -landing. - -Decided by the maintainer on 2026-10-18 (#5892): - -- m1, under the public-model epic, since #5717 already put the Clone - removal there. The public owned chunked writer stays in ingest, which - requires this quest. -- The handle is `group::Handle`. -- Delete the public `Error::FrameOpen`: one writer makes it unreachable. - The in-flight-frame check becomes a `debug_assert`. Update any remaining - references to it. -- `finish(&mut self)`, like every other write. -- Keep `Deref`. A downstream `producer.clone()` now silently - copies the `Copy` `Info` and fails later, so MIGRATE.md names that. - -Landing: breaking public API (no `Clone`, no `FrameOpen`, `finish` takes -`&mut self`), so `rs/moq-net/MIGRATE.md` gets an entry under -`## Unreleased` that says how to migrate: keep the one writer, and watch -readers or closure through `demand()` (its `closed()`), read through -`consume()`, and move a writer that several places used into one owner -(pass it by value, or guard it with a lock). It also names the `Info` -pitfall, `FrameOpen`'s removal, and `finish(&mut self)`. moq-ffi's gets one if -its exported surface changes (it should not). JS has no equivalent: a JS -`Group.Producer` is a single object and needs no change. Docs: none beyond -MIGRATE, since `doc/` never documents cloning a group producer. diff --git a/quest/m1/public-model/ingest.md b/quest/m1/public-model/ingest.md index 8eae9269e6b..3c328a23b16 100644 --- a/quest/m1/public-model/ingest.md +++ b/quest/m1/public-model/ingest.md @@ -64,7 +64,7 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: it). - ✅ Make one open frame per group a compile-time guarantee. Drop public `Clone` from `group::Producer`; the model and sessions keep a - crate-private duplicate. The chunked writer is owned: + crate-private non-writing handle. The chunked writer is owned: `group::Producer::create_frame(self, info) -> Result` aborts the group with the error on failure (an oversized frame, a timestamp mismatch, or a closed group are bugs or protocol errors), @@ -72,14 +72,12 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: back, and `frame.group()` gives read access (demand, info, closed) while the frame is open. `write_frame(&mut self)` stays for one-shot frames. The borrowing `create_frame` and `ProducerOwned` go, with the - stale "caller's promise" doc; `FrameOpen` stays only as a backstop for - crate-internal duplicates. `track::Producer` keeps `Clone`: several + stale "caller's promise" doc. `track::Producer` keeps `Clone`: several writers creating groups is legitimate, and `claim_sequence` already refuses a duplicate sequence. - - Dropping `Clone` and the crate-private non-writing handle moved to - [One group writer](/quest/m1/public-model/group-writer.md), which - names the handle `group::Handle` and deletes `FrameOpen` (decided - 2026-10-18, #5892), so the backstop above goes. This item keeps the + - #6020 dropped `Clone`, added the crate-private non-writing + `group::Handle`, and deleted `FrameOpen` (decided 2026-10-18, #5892), + so the backstop above goes. This item keeps the public owned chunked writer. Its callers that hold a `&mut group::Producer` (hang's `Frame::write_to`, moq-mux's LOC and fMP4 encoders) cannot call a consuming `create_frame(self)`; weigh @@ -207,10 +205,6 @@ Tests: each public call gets a mock-time test in its language, and the built-in subscribers move onto the public calls, so their existing suites cover the behavior. -## Required - -- [One group writer](/quest/m1/public-model/group-writer.md) - the non-Clone writer the owned chunked writer builds on - ## Closes - [#5862](https://github.com/moq-dev/moq/issues/5862) - no way to accept a track::Request with content diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 67b9105269e..6ed31705677 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -901,7 +901,7 @@ impl Publish { /// Finish a raw group. No more frames can be written. pub fn group_finish(&mut self, group: Id) -> Result<(), Error> { - let group = self.groups.remove(group).ok_or(Error::GroupNotFound)?; + let mut group = self.groups.remove(group).ok_or(Error::GroupNotFound)?; group.finish()?; Ok(()) } diff --git a/rs/moq-e2ee/src/group.rs b/rs/moq-e2ee/src/group.rs index 187b3971216..594ba5dcea4 100644 --- a/rs/moq-e2ee/src/group.rs +++ b/rs/moq-e2ee/src/group.rs @@ -90,7 +90,7 @@ impl Producer { /// # Errors /// /// A net error if the group is already closed. - pub fn finish(self) -> Result<()> { + pub fn finish(mut self) -> Result<()> { self.inner.finish()?; Ok(()) } diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index e0798506645..e3468a11de4 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -683,8 +683,8 @@ impl MoqGroupProducer { impl MoqGroupProducer { /// Wait until a consumer has this group. pub(crate) async fn used(&self) -> Result<(), MoqError> { - let producer = self.inner.lock().unwrap().as_ref().ok_or(MoqError::Closed)?.clone(); - Ok(producer.demand().used().await?) + let demand = self.inner.lock().unwrap().as_ref().ok_or(MoqError::Closed)?.demand(); + Ok(demand.used().await?) } } @@ -692,6 +692,23 @@ impl MoqGroupProducer { mod metadata_tests { use super::*; + #[test] + fn dropping_a_group_binding_ends_its_unfinished_group() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("test", moq_net::track::Info::default()).unwrap(); + let group = track.append_group().unwrap(); + let mut consumer = group.consume(); + let binding = MoqGroupProducer { + sequence: group.sequence, + inner: std::sync::Mutex::new(Some(group)), + }; + drop(binding); + assert!(matches!( + consumer.poll_read_frame(&moq_net::kio::Waiter::noop()), + std::task::Poll::Ready(Err(moq_net::Error::Dropped)) + )); + } + #[test] fn untimed_info_round_trips_through_the_binding() { let original = moq_net::track::Info::default(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 58ea35e056d..f2a606538a6 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1298,7 +1298,7 @@ async fn json_consumer_takes_an_unread_track() { .subscribe_track("events".into(), None) .await .unwrap(); - track.append_group().unwrap(); + track.append_group().unwrap().finish().unwrap(); tokio::time::timeout(TIMEOUT, read.recv_group()) .await .expect("timed out waiting for a group") diff --git a/rs/moq-flate/src/stream/producer.rs b/rs/moq-flate/src/stream/producer.rs index 5f0db989b6d..37fefe79c8e 100644 --- a/rs/moq-flate/src/stream/producer.rs +++ b/rs/moq-flate/src/stream/producer.rs @@ -181,7 +181,7 @@ impl Inner { // second group, and (with compression) write into it from a window the consumer never // received. That is exactly the split log ending the track exists to prevent. let group = match self.group.take() { - Some(group) => group.finish(), + Some(mut group) => group.finish(), None => Ok(()), }; let track = self.track.finish(); diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index 26295ace55f..a64e03ab71e 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -372,7 +372,7 @@ struct Track { impl Track { /// Finish the open group without opening a replacement. fn cut(&mut self) -> Result<()> { - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } Ok(()) @@ -401,7 +401,7 @@ impl Track { /// Close the open group and write a snapshot as the first frame of a new one. fn write_snapshot(&mut self, timestamp: Option, payload: bytes::Bytes) -> Result<()> { // The previous group is complete; no more frames will be appended to it. - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } @@ -434,7 +434,7 @@ impl Track { } fn finish(&mut self) -> Result<()> { - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } self.inner.finish()?; diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index 6b7551aa026..305df0f888d 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -222,7 +222,7 @@ impl Track { // second group, and (with compression) write into it from a window the consumer never // received. That is exactly the split log ending the track exists to prevent. let group = match self.group.take() { - Some(group) => group.finish(), + Some(mut group) => group.finish(), None => Ok(()), }; let track = self.inner.finish(); diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index babb9356a24..fca8ebd605b 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -140,7 +140,7 @@ impl Inner { } fn cut(&mut self) -> Result<()> { - let Some(group) = self.track.group.take() else { + let Some(mut group) = self.track.group.take() else { return Ok(()); }; // The group closes either way, so reset first: a `finish` error must not leave the encoder @@ -205,7 +205,7 @@ impl Track { /// Close the open group and write the header as the first frame of a new one. fn write_header(&mut self, timestamp: Option, payload: bytes::Bytes) -> Result<()> { // The previous group is complete; no more frames will be appended to it. - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } @@ -232,7 +232,7 @@ impl Track { } fn finish(&mut self) -> Result<()> { - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } self.inner.finish()?; diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 40251d198b6..150766f8345 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -3710,7 +3710,7 @@ mod tests { track.subscribe(moq_net::track::Subscription::default().with_max_delay(Duration::from_millis(500))); let mut consumer = Consumer::new(consumer_track, Container::Legacy(crate::container::Kind::Data)); - let group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); group0.finish().unwrap(); write_group(&mut track, 1, &[ts(30_000)]); diff --git a/rs/moq-mux/src/container/fmp4/import.rs b/rs/moq-mux/src/container/fmp4/import.rs index 4e1b97a0e2a..8d1d17092d4 100644 --- a/rs/moq-mux/src/container/fmp4/import.rs +++ b/rs/moq-mux/src/container/fmp4/import.rs @@ -1012,7 +1012,7 @@ impl Import { let new_segment = track.segment != Some(self.segment); let start_group = track.group.is_none() || new_segment; let mut g = if start_group { - if let Some(prev) = track.group.take() { + if let Some(mut prev) = track.group.take() { prev.finish()?; if let Some(recorder) = track.recorder.as_mut() { recorder.finish_group(prev.sequence); @@ -1085,7 +1085,7 @@ impl Import { for track in self.tracks.values_mut() { track.estimator.cut(None); track.publish_estimate()?; - if let Some(g) = track.group.take() { + if let Some(mut g) = track.group.take() { g.finish()?; if let Some(recorder) = track.recorder.as_mut() { recorder.finish_group(g.sequence); @@ -1128,7 +1128,7 @@ impl Import { for track in self.tracks.values_mut() { track.estimator.cut(None); track.publish_estimate()?; - if let Some(g) = track.group.take() { + if let Some(mut g) = track.group.take() { g.finish()?; if let Some(recorder) = track.recorder.as_mut() { recorder.finish_group(g.sequence); diff --git a/rs/moq-mux/src/container/mkv/import.rs b/rs/moq-mux/src/container/mkv/import.rs index 54ecf13ecb9..d2668937ffb 100644 --- a/rs/moq-mux/src/container/mkv/import.rs +++ b/rs/moq-mux/src/container/mkv/import.rs @@ -637,7 +637,7 @@ impl Import { // No frame follows to anchor the clock, so publish the declared track set now. self.initial_reservation = None; for track in self.tracks.values_mut() { - if let Some(g) = track.group.take() { + if let Some(mut g) = track.group.take() { g.finish()?; } track.track.finish()?; diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index fc63b19569e..7e524e525b2 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -545,7 +545,7 @@ where if let Some(group) = self.group.as_mut() { self.container.finish_group(group, tail_end)?; } - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; if let Some(recorder) = self.recorder.as_mut() { recorder.finish_group(group.sequence); diff --git a/rs/moq-mux/src/container/ts/export_timing_test.rs b/rs/moq-mux/src/container/ts/export_timing_test.rs index 01282108118..26d0326f5c6 100644 --- a/rs/moq-mux/src/container/ts/export_timing_test.rs +++ b/rs/moq-mux/src/container/ts/export_timing_test.rs @@ -214,7 +214,7 @@ impl Live { } else { let tick = self.tick; let keyframe = tick.is_multiple_of(GOP); - if keyframe && let Some(group) = self.group.take() { + if keyframe && let Some(mut group) = self.group.take() { match std::mem::take(&mut self.stalling) { true => self.stalled.push(group), false => group.finish().unwrap(), @@ -281,7 +281,7 @@ impl Live { /// End the broadcast and let every leg render what it holds. async fn finish(&mut self, legs: &mut [&mut Leg]) { - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish().unwrap(); } self.stalled.clear(); diff --git a/rs/moq-mux/src/container/ts/release_test.rs b/rs/moq-mux/src/container/ts/release_test.rs index 784973bf57a..6b71b858b1a 100644 --- a/rs/moq-mux/src/container/ts/release_test.rs +++ b/rs/moq-mux/src/container/ts/release_test.rs @@ -144,7 +144,7 @@ fn republish_cut( } /// Finish `group`, or abort it as evicted if it is one of the `cut`. -fn end(sequence: u64, group: moq_net::group::Producer, cut: &[u64]) { +fn end(sequence: u64, mut group: moq_net::group::Producer, cut: &[u64]) { match cut.contains(&sequence) { true => group.abort(moq_net::Error::Old).unwrap(), false => group.finish().unwrap(), diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index dead14e4b55..f86f29361e9 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,15 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Each group has one writer (#6020) + +`group::Producer` no longer implements `Clone`: keep one writer and move it by value between owners, or put it behind a lock when several callers write it. +Use `consume()` to read and `demand()` to watch readers or closure with `closed()`. +`Deref` remains, so `producer.clone()` can now copy the `Info` instead of a writer and fail at a later call; remove those clones explicitly. +`finish` now takes `&mut self`. `Error::FrameOpen` is removed because owning the writer prevents concurrent frame writes or finishing with an open frame. +Dropping an unfinished writer now aborts the group with `Error::Dropped` immediately, even while the track cache retains the group. +`group::Producer` is `#[must_use]`, so a discarded `track.append_group()?;` now warns: finish the group, or hold the writer while it stays open. + ### Ranges filter each subscriber's reads (#5929) A `track::Subscriber` now reads only the groups its own `Subscription::ranges` cover, resolved again whenever `update` replaces them; before, they only set where its reads started. diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 5d34818d408..45c61b29b30 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -539,7 +539,7 @@ fn bench_fanout_frame(c: &mut Criterion) { let mut elapsed = Duration::ZERO; for _ in 0..iterations { if written == FRAMES_PER_GROUP { - if let Some(open) = open.take() { + if let Some(mut open) = open.take() { open.finish().unwrap(); } open = Some(fanout.track.append_group().unwrap()); diff --git a/rs/moq-net/src/coding/reader.rs b/rs/moq-net/src/coding/reader.rs index 5c3bf08ec8a..d61f6f411e8 100644 --- a/rs/moq-net/src/coding/reader.rs +++ b/rs/moq-net/src/coding/reader.rs @@ -428,7 +428,7 @@ mod tests { kio::Waiter, Arc, ) { - let mut group = crate::group::Info { sequence: 0 }.produce(); + let group = crate::group::Info { sequence: 0 }.produce(); let mut consumer = group.consume(); let frame = group .create_frame_owned( @@ -640,7 +640,7 @@ mod tests { )); assert_eq!(wakes.count(), 1, "a full frame woke before it was committed"); - frame.finish().unwrap(); + let _group = frame.finish().unwrap(); assert_eq!(wakes.count(), 2); } diff --git a/rs/moq-net/src/error.rs b/rs/moq-net/src/error.rs index 6bbdfcdfe4e..50236cead74 100644 --- a/rs/moq-net/src/error.rs +++ b/rs/moq-net/src/error.rs @@ -483,14 +483,6 @@ pub enum Error { #[error("group too large")] GroupTooLarge, - /// A whole-frame write was refused because a frame is already open on the group. - /// - /// A [`crate::group::Producer`] streaming a frame with `create_frame` blocks the - /// whole-frame writes on every clone of that producer until it finishes, since - /// appending around it would reorder the group. - #[error("frame already open")] - FrameOpen, - /// A frame's timestamp doesn't fit its track: it's missing on a timed track, present /// on an untimed track, out of range for the track's timescale, or starts a group /// earlier than the group before it. @@ -664,7 +656,6 @@ impl From<&Error> for SessionError { | Error::Unroutable | Error::FrameTooLarge | Error::GroupTooLarge - | Error::FrameOpen | Error::TimestampMismatch | Error::MalformedTrack | Error::UnsupportedExtension => Self::Internal, @@ -732,7 +723,6 @@ impl From<&Error> for StreamError { | Error::UnsupportedExtension | Error::InvalidRange | Error::InvalidJoiningRequestId - | Error::FrameOpen | Error::Encode(_) => Self::Internal, // A producer dropped without an end is a bug here, so it is never given a meaning. Error::Dropped => Self::Internal, diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 442fead6fed..4e167a16d34 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -52,7 +52,7 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr }; let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); frame.write(payload.clone()).unwrap(); - frame.finish().unwrap(); + group = frame.finish().unwrap(); } group.finish().unwrap(); (broadcast, track, group) @@ -1122,7 +1122,6 @@ pub fn seeds() -> Vec { /// the bytes received. pub struct FrameRecv { streams: Vec, frame::ProducerOwned)>>, - groups: Vec, // Keeps the groups' track alive. _track: track::Producer, _broadcast: broadcast::Producer, @@ -1145,16 +1144,14 @@ impl FrameRecv { let budget = budget.map(frame::Budget::new).unwrap_or_default(); let payload = bytes::Bytes::from(vec![0u8; size]); - let mut groups = Vec::with_capacity(streams); let streams = (0..streams) .map(|_| { - let mut group = track.append_group().unwrap(); + let group = track.append_group().unwrap(); let info = frame::Info { size: size as u64, timestamp: Some(crate::Timestamp::ZERO), }; let frame = group.create_frame_owned(info, &budget).unwrap(); - groups.push(group); let stream = Chunks { payload: payload.clone(), chunk, @@ -1166,7 +1163,6 @@ impl FrameRecv { Self { streams, - groups, _track: track, _broadcast: broadcast, } @@ -1182,14 +1178,12 @@ impl FrameRecv { if let std::task::Poll::Ready(res) = reader.poll_read_frame(&mut cx, frame) { res.unwrap(); let (_, frame) = slot.take().unwrap(); - frame.finish().unwrap(); + let mut group = frame.finish().unwrap(); + group.finish().unwrap(); open -= 1; } } } - for group in &self.groups { - group.finish().unwrap(); - } } } diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 14da04d6b7d..a6df970a8ee 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -5308,7 +5308,7 @@ mod group_priority_test { ); assert!(serve.poll(&kio::Waiter::noop()).is_pending()); if finished { - group.clone().finish().unwrap(); + group.finish().unwrap(); assert!(serve.poll(&kio::Waiter::noop()).is_pending()); assert!(log.trail().iter().any(|(_, event)| matches!(event, Sent::Finish))); } @@ -10021,7 +10021,7 @@ mod serve_tests { for version in [Version::Draft20, Version::Draft21, Version::Draft22] { let mut h = serve(version); publish_pairs(&mut h, 5, None); - let empty = h.track.create_group(group::Info { sequence: 5 }).unwrap(); + let mut empty = h.track.create_group(group::Info { sequence: 5 }).unwrap(); empty.finish().unwrap(); settle().await; diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 499c3453c8c..8dc33aefc3a 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -182,7 +182,7 @@ impl State { let _ = producer.abort_session(err.clone()); } if let Fill::Ready { producer, .. } = &*track.fill.read() { - let _ = producer.clone().abort(err.clone()); + let _ = producer.handle().abort(err.clone()); } } for (_, producer) in self.lingering.drain() { @@ -320,7 +320,7 @@ impl Fill { /// stitched. Finishing rather than aborting, because the head is a valid prefix of the /// group: it starts at the group's first object and has no holes. fn release(&mut self) { - if let Fill::Ready { producer, .. } = std::mem::replace(self, Fill::Done) { + if let Fill::Ready { mut producer, .. } = std::mem::replace(self, Fill::Done) { let _ = producer.finish(); } } @@ -4003,19 +4003,19 @@ where // Guarded: this handler can be dropped at any await below, and a group producer // that dies without a terminal leaves its consumer waiting on nothing. - let producer = crate::recv::Group::new(producer); + let mut producer = crate::recv::Group::new(producer); + let observing = producer.handle().clone(); + let mut ingest = GroupIngest::new(self, &group, timescale, resume.map(|_| start)); let res = { - let mut ingest = GroupIngest::new(self, &group, timescale, resume.map(|_| start)); - let mut writing = producer.clone(); kio::wait(|waiter| { if let Poll::Ready(err) = track.poll_closed(waiter) { return Poll::Ready(Err(err)); } - if let Poll::Ready(err) = producer.poll_closed(waiter) { + if let Poll::Ready(err) = observing.poll_closed(waiter) { return Poll::Ready(Err(err)); } - ingest.poll(stream, &mut writing, waiter) + ingest.poll(stream, &mut producer, waiter) }) .await }; @@ -4772,7 +4772,7 @@ where async fn recv_fetch_payload( &self, stream: &mut Reader, - producer: &mut group::Producer, + producer: &mut crate::recv::Group, payload: FetchPayload, ) -> Result { let FetchPayload { @@ -4831,7 +4831,7 @@ where let _ = frame.abort(err.clone()); return Err(err); } - frame.finish()?; + producer.restore(frame.finish()?); Ok(Fetched::Frame) } @@ -5031,7 +5031,7 @@ where let _ = stream.writer.close().await; return; } - let demand = producer.clone(); + let demand = producer.handle(); if let Ok(mut state) = slot.write() { *state = GroupFetch::Ready { producer, @@ -5181,7 +5181,7 @@ where last: None, })?; - let closed = producer.clone(); + let closed = producer.handle(); let mut producer = crate::recv::Group::new(producer); let res = { let mut receive = std::pin::pin!(crate::util::sendable(self.recv_group_fetch_objects( @@ -5225,7 +5225,7 @@ where async fn recv_group_fetch_objects( &self, stream: &mut Reader, - producer: &mut group::Producer, + producer: &mut crate::recv::Group, start: u64, end: Option, timescale: Option, @@ -5568,7 +5568,7 @@ impl GroupIngest { fn poll( &mut self, reader: &mut Reader, - group: &mut group::Producer, + group: &mut crate::recv::Group, waiter: &kio::Waiter, ) -> Poll> { let mut cx = waiter.context(); @@ -5626,7 +5626,7 @@ impl GroupIngest { let timestamp = object_time(self.timescale, *timestamp)?; let header = self.header(group, frame::Info { size: 0, timestamp })?; let frame = group.create_frame_owned(header, &self.budget)?; - frame.finish()?; + group.restore(frame.finish()?); } self.phase = IngestPhase::Delta; continue; @@ -5659,7 +5659,7 @@ impl GroupIngest { unreachable!() }; match failed { - None => frame.finish()?, + None => group.restore(frame.finish()?), Some(err) => { // Fail the group with the reason, not the Drop fallback's // generic `Dropped`. @@ -12489,11 +12489,13 @@ mod stitch_tests { // The next relay reads the same objects into its cache, up to the same end. let end = last + u64::from(Filter::is_draft20(version)); let mut run = GroupFetchRun::new(version, decoder.rest().to_vec()).await; - let mut producer = run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + let mut producer = + crate::recv::Group::new(run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap()); run.subscriber .recv_group_fetch_objects(&mut run.stream, &mut producer, 0, Some(end), None) .await .unwrap_or_else(|err| panic!("{version}: {err}")); + let mut producer = producer.into_inner(); producer.finish().unwrap(); let mut reader = producer.consume(); for id in [6, 8] { @@ -12616,11 +12618,13 @@ mod stitch_tests { objects.push(99); } let mut run = GroupFetchRun::new(version, objects.clone()).await; - let mut producer = run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + let mut producer = + crate::recv::Group::new(run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap()); run.subscriber .recv_group_fetch_objects(&mut run.stream, &mut producer, 0, Some(9), None) .await .unwrap(); + let mut producer = producer.into_inner(); producer.finish().unwrap(); let mut reader = producer.consume(); for id in [6, 8] { @@ -14381,9 +14385,18 @@ mod stitch_tests { async fn recv_objects(&mut self, start: u64, end: Option) -> Result<(), Error> { let mut group = self.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); group.start_at(start).unwrap(); - self.subscriber + let mut group = crate::recv::Group::new(group); + match self + .subscriber .recv_group_fetch_objects(&mut self.stream, &mut group, start, end, None) .await + { + Ok(()) => group.finish(), + Err(err) => { + let _ = group.abort(err.clone()); + Err(err) + } + } } } } @@ -15002,7 +15015,7 @@ mod joining_fetch_tests { let GroupFetch::Ready { producer, .. } = &*state else { panic!("accepted slot") }; - producer.clone() + producer.handle() }; if stage == FetchStage::Accepted { drop(group); @@ -15461,6 +15474,8 @@ mod new_group_tests { probe: Subscriber, peer: memory::Session, serving: moq_clock::sim::JoinHandle<()>, + /// Landed groups stay open, as a live publisher's would. + landed: Vec, _broadcast: crate::broadcast::Producer, _tasks: TaskSet, } @@ -15498,6 +15513,7 @@ mod new_group_tests { probe, peer, serving, + landed: Vec::new(), _broadcast: broadcast, _tasks: task_set, }; @@ -15525,7 +15541,7 @@ mod new_group_tests { } /// Group `sequence` lands in the copy: a first frame, and a delta when `delta`. - fn land(&self, sequence: u64, delta: bool) { + fn land(&mut self, sequence: u64, delta: bool) { let state = self.probe.state.lock(); let copy = state.subscribes.values().next().unwrap().producer.clone().unwrap(); drop(state); @@ -15534,6 +15550,7 @@ mod new_group_tests { if delta { group.write_frame(None, b"delta".as_slice()).unwrap(); } + self.landed.push(group); } /// A downstream subscriber joins the copy. diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index ce8a6b85f0c..df417183cad 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2459,7 +2459,11 @@ mod test { let mut subscriber = producer.subscribe(None); // The last group is 6 (exclusive 7), but only group 5 has been produced so far. - producer.create_group(group::Info { sequence: 5 }).unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); producer.finish_at(track::Position::group(7)).unwrap(); // Group 5 is delivered first. @@ -2477,7 +2481,11 @@ mod test { // The caller stops requesting the boundary once sent. The trailing group arrives, // then the track finishes. - producer.create_group(group::Info { sequence: 6 }).unwrap(); + producer + .create_group(group::Info { sequence: 6 }) + .unwrap() + .finish() + .unwrap(); match recv_next(&mut subscriber, false, false).await.unwrap() { Recv::Group(group) => assert_eq!(group.sequence, 6), _ => panic!("expected group 6"), @@ -2498,14 +2506,22 @@ mod test { let mut producer = track_producer("test"); let mut subscriber = producer.subscribe(track::Subscription::default().with_max_delay(Duration::from_secs(5))); - producer.create_group(group::Info { sequence: 2 }).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); match recv_next(&mut subscriber, false, false).await.unwrap() { Recv::Group(group) => assert_eq!(group.sequence, 2), _ => panic!("expected group 2"), } // Group 1 lands after group 2 was already served. - producer.create_group(group::Info { sequence: 1 }).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); match recv_next(&mut subscriber, false, false).now_or_never() { Some(Ok(Recv::Group(group))) => assert_eq!(group.sequence, 1), Some(_) => panic!("expected the late-arriving group"), diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 8758fe03f7a..273260027d7 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -942,13 +942,13 @@ impl GroupRecv { if let Poll::Ready(err) = track.poll_closed(waiter) { break 'serve Err(err); } - if let Poll::Ready(err) = group.poll_closed(waiter) { + if let Poll::Ready(err) = group.handle().poll_closed(waiter) { break 'serve Err(err); } let res = ingest.poll(&mut self.reader, group, waiter); // Shown once its first frame opens, even mid-payload. - if !*shown && group.is_started() { - track.reveal_group(group); + if !*shown && group.handle().is_started() { + track.reveal_group(group.handle()); *shown = true; } match res { @@ -970,7 +970,7 @@ impl GroupRecv { unreachable!() }; // A group that ended without a frame shows once it settles. - let handle = (!shown).then(|| (*group).clone()); + let handle = (!shown).then(|| group.handle().clone()); let res = match res { Ok(()) => { let _ = group.finish(); @@ -1037,7 +1037,7 @@ impl FrameIngest { fn poll( &mut self, reader: &mut Reader, - group: &mut group::Producer, + group: &mut crate::recv::Group, waiter: &kio::Waiter, ) -> Poll> { let mut cx = waiter.context(); @@ -1086,7 +1086,7 @@ impl FrameIngest { unreachable!() }; match failed { - None => frame.finish()?, + None => group.restore(frame.finish()?), Some(err) => { // Fail the group with the reason, not the Drop fallback's // generic `Dropped`. @@ -6328,7 +6328,7 @@ enum FetchRunState { }, Ingest { stream: Stream, - producer: group::Producer, + producer: crate::recv::Group, // The accepted request's demand: fetches that joined it but have not yet // picked the group up from the cache. joined: kio::Producer, @@ -6392,7 +6392,10 @@ impl Drop for FetchServeRun { } } FetchRunState::Ingest { - mut stream, producer, .. + mut stream, + producer, + ingest: _ingest, + .. } => { stream.reader.abort(&err); stream.writer.abort(&err); @@ -6577,7 +6580,7 @@ impl kio::Task for FetchServeRun { self.state = FetchRunState::Ingest { stream, - producer, + producer: crate::recv::Group::new(producer), joined, ingest: Box::new(FrameIngest::new(&self.serve.subscriber, self.timescale)), }; @@ -6593,10 +6596,11 @@ impl kio::Task for FetchServeRun { // wants the rest (no joined fetch left to pick it up, no reader), // cancel upstream and abort the truncated group, never caching it // as complete. The abort is atomic with a new reader arriving. - if joined.poll_unused(waiter).is_pending() || producer.poll_unused(waiter).is_pending() { + if joined.poll_unused(waiter).is_pending() || producer.handle().poll_unused(waiter).is_pending() + { return Poll::Pending; } - if !producer.abort_unused(Error::Cancel) { + if !producer.handle().abort_unused(Error::Cancel) { continue; } tracing::debug!(track = %self.serve.name, group = self.group, "fetch abandoned"); diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index c77c979c977..f21764656c2 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -1386,7 +1386,7 @@ mod test { let producer = Info::new().produce(); let consumer = producer.consume(); let track = producer.create_track("a", crate::track::Info::timed()).unwrap(); - track.append_group().unwrap(); + let _open = track.append_group().unwrap(); let handle = consumer.track("a").unwrap(); assert_eq!(handle.latest_sequence(), Some(0)); drop(track); @@ -1420,7 +1420,7 @@ mod test { let producer = Info::new().produce(); let consumer = producer.consume(); let track = producer.create_track("a", crate::track::Info::timed()).unwrap(); - track.append_group().unwrap(); + let _open = track.append_group().unwrap(); let handle = consumer.track("a").unwrap(); producer.close(); drop(track); @@ -1565,7 +1565,7 @@ mod test { // Create the track before any consumer exists. let track1 = producer.assert_create_track("track1", crate::track::Info::timed()); - track1.append_group().unwrap(); + track1.append_group().unwrap().finish().unwrap(); let consumer = producer.consume(); @@ -1579,7 +1579,7 @@ mod test { let mut track2_consumer = consumer2.track("track2").unwrap().subscribe(None).await.unwrap(); track2_consumer.assert_no_group(); - track2.append_group().unwrap(); + track2.append_group().unwrap().finish().unwrap(); track2_consumer.assert_group(); } @@ -1667,7 +1667,7 @@ mod test { track3.subscribe(None).assert_is_clone(&track1); // Append a group and make sure they all get it. - track3.append_group().unwrap(); + track3.append_group().unwrap().finish().unwrap(); track1.assert_group(); track2.assert_group(); @@ -1693,7 +1693,7 @@ mod test { let mut track1 = track1_fut.await.unwrap(); // Close the producer (simulating publisher disconnect). - producer1.append_group().unwrap(); + producer1.append_group().unwrap().finish().unwrap(); producer1.finish().unwrap(); drop(producer1); @@ -1708,7 +1708,11 @@ mod test { track2.assert_not_clone(&track1); // The new consumer should receive the new group, which continues past the first's. - producer2.create_group(crate::group::Info { sequence: 1 }).unwrap(); + producer2 + .create_group(crate::group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); track2.assert_group(); } @@ -1725,7 +1729,7 @@ mod test { let mut first = dynamic.assert_request().accept(crate::track::Info::timed()); assert_eq!(first.append_group().unwrap().sequence, 0); assert_eq!(first.append_datagram(crate::Timestamp::ZERO, b"x").unwrap(), 1); - first.create_group(crate::group::Info { sequence: 8 }).unwrap(); + let _open = first.create_group(crate::group::Info { sequence: 8 }).unwrap(); first.insert_datagram(12, crate::Timestamp::ZERO, b"x").unwrap(); first.finish().unwrap(); drop((first, track)); @@ -1739,7 +1743,7 @@ mod test { )); // An explicit first write picks the start, and appends continue from there. - second.create_group(crate::group::Info { sequence: 13 }).unwrap(); + let _open = second.create_group(crate::group::Info { sequence: 13 }).unwrap(); assert_eq!(second.append_datagram(crate::Timestamp::ZERO, b"x").unwrap(), 14); second.finish().unwrap(); drop((second, track)); @@ -1880,7 +1884,7 @@ mod test { let mut sub = subscribing.await.expect("fulfilled by create_track"); // The fulfilled subscription is live against this very producer. - track.append_group().unwrap(); + track.append_group().unwrap().finish().unwrap(); sub.recv_group().await.expect("recv").expect("group"); // The handler never sees the request; a fresh subscribe reuses the track. @@ -2045,7 +2049,7 @@ mod test { let track = consumer.track("track1").unwrap(); let pending_fetch = track.fetch_group(0, None); let fetch = dynamic.requested_group().await.unwrap(); - let group = fetch.accept(crate::track::Info::timed()).unwrap(); + let mut group = fetch.accept(crate::track::Info::timed()).unwrap(); group.finish().unwrap(); pending_fetch.await.unwrap(); @@ -2071,7 +2075,7 @@ mod test { producer.close(); assert!(matches!(consumer.track("track1"), Err(Error::Unroutable))); - track.append_group().unwrap(); + track.append_group().unwrap().finish().unwrap(); subscriber.assert_group(); track.finish().unwrap(); } @@ -2156,7 +2160,7 @@ mod test { assert!(!track.is_closed()); let mut subscriber = viewer.await.unwrap(); subscriber.assert_no_group(); - track.append_group().unwrap(); + track.append_group().unwrap().finish().unwrap(); assert!(subscriber.recv_group().await.unwrap().is_some()); // Once the viewer really leaves, the same teardown commits, and the lookup diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index d7f5bcb2df4..0846c7ff098 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -431,11 +431,13 @@ impl FrameBuf { /// The writer behind [`Producer`] and [`ProducerOwned`], generic over how it /// reaches the parent group (an exclusive borrow, or an owned clone). struct Raw> { - group: G, + group: Option, buf: FrameBuf, info: Info, // Set once the frame is committed (finished) or aborted, so Drop is a no-op. done: bool, + // An owned receive frame carries its handler's cancellation cleanup across polls. + cancel_on_drop: bool, // Ingress payload meter, inherited from the parent group. Counts each written // chunk's bytes. Empty (no-op) for an untagged group. stats: stats::Meter, @@ -475,16 +477,24 @@ impl> Raw { return Err(Error::WrongSize); } let payload = self.buf.freeze(); - self.group.borrow_mut().frame_commit(Frame { - timestamp: self.info.timestamp, - payload, - })?; + self.group + .as_mut() + .expect("frame owns its group") + .borrow_mut() + .frame_commit(Frame { + timestamp: self.info.timestamp, + payload, + })?; self.done = true; Ok(()) } fn abort(&mut self, err: Error) -> Result<()> { - self.group.borrow_mut().frame_abort(err); + self.group + .as_mut() + .expect("frame owns its group") + .borrow_mut() + .frame_abort(err); self.done = true; Ok(()) } @@ -497,14 +507,21 @@ impl> Drop for Raw { // consumers surface an error instead of hanging on the partial forever. // A group already aborted (superseded, evicted, cancelled) carries its own // reason, so cutting its in-flight frame short is expected. - let group = self.group.borrow_mut(); - if !group.is_aborted() { + let Some(group) = self.group.as_mut() else { + return; + }; + let group = group.borrow_mut(); + if !group.is_aborted() && !self.cancel_on_drop { tracing::warn!( group = group.info().sequence, "frame::Producer dropped before writing all bytes" ); } - group.frame_abort(Error::Dropped); + group.frame_abort(if self.cancel_on_drop { + Error::Cancel + } else { + Error::Dropped + }); } } } @@ -532,10 +549,11 @@ impl std::ops::Deref for Producer<'_> { impl<'a> Producer<'a> { pub(super) fn new(group: &'a mut group::Producer, buf: FrameBuf, info: Info) -> Self { Self(Raw { - group, + group: Some(group), buf, info, done: false, + cancel_on_drop: false, stats: stats::Meter::default(), }) } @@ -548,7 +566,7 @@ impl<'a> Producer<'a> { /// The parent group this frame belongs to. pub fn group(&self) -> group::Info { - self.0.group.info() + self.0.group.as_ref().expect("frame owns its group").info() } /// Bytes still needed to complete the frame. @@ -561,7 +579,7 @@ impl<'a> Producer<'a> { /// Returns [`Error::WrongSize`] if the chunk would exceed the remaining bytes. pub fn write(&mut self, chunk: B) -> Result<()> { self.0.write(chunk)?; - self.0.group.frame_notify(); + self.0.group.as_mut().expect("frame owns its group").frame_notify(); Ok(()) } @@ -581,9 +599,8 @@ impl<'a> Producer<'a> { /// The owned counterpart of [`Producer`], for the wire drivers that stream a /// frame across polls and cannot hold the group borrowed inside their state. /// -/// Crate-private on purpose: the exclusivity the public borrow enforces (one -/// live frame per group) becomes the holder's promise here. Do not open another -/// frame on the group until this one is finished or aborted. +/// Owns the only group writer until the frame finishes and returns it, so another +/// frame or a group finish cannot race this frame. /// /// Holds the frame's share of the session's [`Budget`], if it got one, until then. #[cfg_attr(not(feature = "async"), allow(dead_code))] @@ -602,14 +619,24 @@ impl std::ops::Deref for ProducerOwned { } impl ProducerOwned { + /// Transfer a receive handler's cancellation cleanup into its in-flight frame. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: capability gap + // Public drivers still borrow frames; the owned public writer belongs to ingest. + pub(crate) fn cancel_on_drop(mut self) -> Self { + self.raw.cancel_on_drop = true; + self + } + #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) fn new(group: group::Producer, buf: FrameBuf, info: Info, reserved: Option) -> Self { Self { raw: Raw { - group, + group: Some(group), buf, info, done: false, + cancel_on_drop: false, stats: stats::Meter::default(), }, _reserved: reserved, @@ -647,13 +674,14 @@ impl ProducerOwned { #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: tuning pub(crate) fn notify(&self) { - self.raw.group.frame_notify(); + self.raw.group.as_ref().expect("frame owns its group").frame_notify(); } /// Commit the frame, verifying that all bytes were written. #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub fn finish(mut self) -> Result<()> { - self.raw.finish() + pub fn finish(mut self) -> Result { + self.raw.finish()?; + Ok(self.raw.group.take().expect("frame owns its group")) } /// Abort the frame (and its group) with the given error. diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 8fc2bb600dc..6498967b55d 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -49,7 +49,7 @@ const FRAME_SLOTS: usize = 4; /// bookkeeping in [`track::CACHE_OVERHEAD`]. /// /// A group is one kio channel (allocated whether or not anything ever parks on it), the -/// `Arc` its producer clones share, and the frame slots the first write rounds up +/// `Arc` its writer and observers share, and the frame slots the first write rounds up /// to. Half of [`cache::ENTRY_OVERHEAD`]; see it for why this is derived rather than /// measured. pub(super) const CACHE_OVERHEAD: u64 = (kio::Producer::::HEAP @@ -192,7 +192,7 @@ pub(super) struct GroupState { // cache policy moves the frames to them rather than dropping them. handoff: Mutex>, - // Whether an adopted head (see [`Producer::adopt_head`]) begins at the group's first + // Whether an adopted head (see [`Handle::adopt_head`]) begins at the group's first // object, for a wire header that arrives after it. adopted: Option, } @@ -659,51 +659,40 @@ fn modify(state: &kio::Producer) -> Result> /// Each group is delivered independently over a QUIC stream. /// Use [Self::write_frame] for simple single-buffer frames, /// or [Self::create_frame] for multi-chunk streaming writes. +/// +/// The writer cannot be cloned; move it to its next owner instead. +/// +/// ```compile_fail +/// # fn cannot_clone(producer: moq_net::group::Producer) { +/// let _: moq_net::group::Producer = producer.clone(); +/// # } +/// ``` +#[must_use = "dropping an unfinished group aborts it with `Dropped`"] pub struct Producer { - // Mutable stream state. - state: kio::Producer, + handle: Handle, + stats: stats::Meter, +} - // The group header containing the sequence number. A small `Copy` value, - // inherited by each frame (see [`Self::create_frame`]). +/// Shared group state without permission to write frames or finish the group. +#[derive(Clone)] +// private: capability gap +// Sessions need an abortable observer while public callers use Demand. +pub(crate) struct Handle { + state: kio::Producer, info: Info, - - // The parent track's properties, inherited rather than passed piecemeal. Its - // `timescale` is used by [`Self::create_frame`] to normalize every frame's - // timestamp into the track scale before it enters the stream. Threaded down by - // value from [`track::Producer::create_group`] / `append_group`. track: track::Info, - - // The parent track's account against the shared cache pool. Held here as well as - // in the group's `cache::Charge` so a frame write can settle the track's eviction - // debt with the group lock released. cache: Arc, - - // Ingress payload meter, set by a tagged [`track::Producer`] via - // [`Self::with_meter`]. Empty (no-op) for an untagged group. - stats: stats::Meter, - - // Shared by every clone: its `Drop` is the abrupt-teardown, running exactly once - // when the last of them goes. alive: Arc, } -/// Ends the group when the last [`Producer`] clone drops, including the clone the -/// parent track holds in its cache. -/// -/// A refcount rather than a "am I the last one?" check inside `Drop`: that answer is -/// a snapshot, and acting on it is exactly what can invalidate it. Holding a producer -/// of its own also keeps the state writable until the teardown has run, whatever order -/// the last owner's fields drop in. struct Alive { - info: Info, - state: kio::Producer, // Monotone mirror of `GroupState::abort` for track scans that already hold the // track lock. A stale false only hands out a group that is concurrently aborting; // true is stored after the abort exists, so it can never hide a live group. // // Only ever read on its own. A decision that pairs the abort with something else // out of `GroupState` has to read both under one guard, or the two halves can - // straddle the abort: see `Producer::live_first_frame`. + // straddle the abort: see `Handle::live_first_frame`. aborted: AtomicBool, // Set once frame 0's rewind check ran, so later writes skip the track lock it takes. A // stale false only takes that lock once more. @@ -717,38 +706,22 @@ struct Alive { access: Arc, } -impl Drop for Alive { +impl Drop for Producer { fn drop(&mut self) { - // See track::Alive: the last producer dropping without a clean finish releases - // the cached frames so a stale consumer can't pin their buffers forever. A - // finished group keeps its cache so consumers can drain. - // - // Check Ok and Err: Ok is unreachable after a deliberate close. - match self.state.write() { - Ok(mut state) => { - if state.fin.is_some() || state.abort.is_some() { - return; - } - tracing::warn!( - sequence = self.info.sequence, - "group::Producer dropped without finish() or abort()" - ); - state.release(true); - } - Err(state) => { - if state.fin.is_some() || state.abort.is_some() { - return; - } - tracing::warn!( - sequence = self.info.sequence, - "group::Producer dropped without finish() or abort()" - ); + if let Ok(state) = self.handle.state.write() { + if state.fin.is_some() || state.abort.is_some() { + return; } + tracing::warn!( + sequence = self.sequence, + "group::Producer dropped without finish() or abort()" + ); + self.handle.commit_abort(state, Error::Dropped); } } } -impl std::ops::Deref for Producer { +impl std::ops::Deref for Handle { type Target = Info; fn deref(&self) -> &Self::Target { @@ -756,17 +729,25 @@ impl std::ops::Deref for Producer { } } +impl std::ops::Deref for Producer { + type Target = Info; + + fn deref(&self) -> &Self::Target { + &self.handle.info + } +} + impl Producer { #[cfg(feature = "async")] // private: passthrough pub(crate) fn wire(&self) -> Option { - self.state.read().wire().cloned() + self.handle.state.read().wire().cloned() } #[cfg(feature = "async")] // private: passthrough pub(crate) fn set_wire(&self, mut wire: Wire) -> Result<()> { - let mut state = modify(&self.state)?; + let mut state = modify(&self.handle.state)?; // A head adopted before the header arrived holds the objects below the stream's. if let Some(first_object) = state.adopted { wire.first_object = first_object; @@ -783,7 +764,7 @@ impl Producer { if gap.is_some_and(|gap| gap > id) { return Err(Error::MalformedTrack); } - let mut state = modify(&self.state)?; + let mut state = modify(&self.handle.state)?; let offset = state.offset as u64; if let Some(wire) = state.wire_mut() { let missing = match wire.last { @@ -805,7 +786,7 @@ impl Producer { #[cfg(feature = "async")] // private: passthrough pub(crate) fn set_end_object(&self, fields: super::object::Fields) -> Result<()> { - let mut state = modify(&self.state)?; + let mut state = modify(&self.handle.state)?; if state.fin.is_some() || state.relay.as_ref().is_some_and(|relay| relay.end_object.is_some()) { return Err(Error::MalformedTrack); } @@ -839,20 +820,20 @@ impl Producer { let access = charge.access(); state.write().ok().expect("a new group is open").charge = charge; let alive = Arc::new(Alive { - info, - state: state.clone(), aborted: AtomicBool::new(false), checked: AtomicBool::new(false), cut: AtomicBool::new(false), access, }); Self { - info, - state, - track, - cache, + handle: Handle { + info, + state, + track, + cache, + alive, + }, stats: stats::Meter::default(), - alive, } } @@ -867,12 +848,12 @@ impl Producer { /// The group header. // pending: /quest/m1/public-model/ingest.md pub(crate) fn info(&self) -> Info { - self.info + self.handle.info } /// The parent track's timescale, or `None` when it declared no timeline. pub fn timescale(&self) -> Option { - self.track.timescale + self.handle.track.timescale } /// The track to check this group's start against, while frame 0 may still be unwritten. @@ -881,10 +862,10 @@ impl Producer { /// one step against every other group's (locks are ordered track then group). Only a /// timed group not yet checked pays for it, once. fn first_frame_track(&self) -> Option> { - if self.track.timescale.is_none() || self.alive.checked.load(Ordering::Relaxed) { + if self.handle.track.timescale.is_none() || self.handle.alive.checked.load(Ordering::Relaxed) { return None; } - self.cache.track() + self.handle.cache.track() } /// Start the group at frame `index` rather than 0, so the first frame written lands @@ -906,7 +887,7 @@ impl Producer { return Err(Error::BoundsExceeded(crate::coding::BoundsExceeded)); } - let mut state = modify(&self.state)?; + let mut state = modify(&self.handle.state)?; // Every write advances `next_index` past `offset`, so this is "nothing written // yet". if state.fin.is_some() || state.next_index != state.offset { @@ -918,74 +899,6 @@ impl Producer { Ok(()) } - /// Adopt the frames of `head` below where this copy starts, so it holds the group - /// from `head`'s start, as if this route had delivered them. - /// - /// A no-op unless `head` starts below this copy and reaches it, and the frames fit the - /// group's budget. Readers keep their positions, since frames keep their indices. A - /// group whose frames build on earlier ones (a compressed group) primes its decoder - /// from the adopted frames here. - pub(super) fn adopt_head(&self, head: &Head) { - let Ok(mut state) = self.state.write() else { - return; - }; - let offset = state.offset; - let reaches = head.start.saturating_add(head.frames.len()) >= offset; - if state.abort.is_some() || state.sparse() || head.start >= offset || !reaches { - return; - } - let count = offset - head.start; - let frames = &head.frames[..count]; - let fields = || head.objects.iter().take(count).flatten(); - let payload: u64 = frames.iter().map(|frame| frame.payload.len() as u64).sum(); - let metadata: u64 = fields().map(|fields| fields.heap()).sum(); - // The in-flight frame's remainder was admitted at its open and is charged as it - // streams in, without another check. - if state.would_overflow(count, payload + metadata + state.unwritten()) { - return; - } - - let before = state.frames.capacity().saturating_sub(FRAME_SLOTS); - state.frames.reserve(count); - let mut growth = ((state.frames.capacity().saturating_sub(FRAME_SLOTS) - before) * size_of::()) as u64; - for frame in frames.iter().rev() { - state.frames.push_front(frame.clone()); - } - // Keep the fields aligned with the frames: the adopted ones lead. - if fields().next().is_some() || state.relay.as_ref().is_some_and(|relay| !relay.objects.is_empty()) { - let relay = state.relay(); - let before = relay.objects.capacity(); - relay.objects.reserve(count); - let slots = ((relay.objects.capacity() - before) * size_of::>>()) as u64; - for index in (0..count).rev() { - relay.objects.push_front(head.objects.get(index).cloned().flatten()); - } - relay.bytes += slots + metadata; - growth += slots; - } - state.offset = head.start; - state.cache += payload; - let start = frames.iter().find_map(|frame| frame.timestamp); - state.timeline = match (state.timeline, start) { - (Timeline::Timed { latest, .. }, Some(start)) => Timeline::Timed { start, latest }, - (Timeline::Empty, Some(start)) => Timeline::Timed { - start, - latest: frames.iter().rev().find_map(|frame| frame.timestamp).unwrap_or(start), - }, - (Timeline::Empty, None) => Timeline::Untimed, - (timeline, _) => timeline, - }; - state.adopted = Some(head.first_object); - if let Some(wire) = state.wire_mut() { - wire.first_object = head.first_object; - wire.first_id = head.start as u64; - wire.last = wire.last.or(Some(offset as u64 - 1)); - } - let now = state.charge.add(payload + metadata + growth); - drop(state); - self.cache.settle(now); - } - /// A helper method to write a frame from a single byte buffer. /// /// If you want to write multiple chunks, use [Self::create_frame] to get a frame producer. @@ -994,7 +907,7 @@ impl Producer { /// `timestamp` is converted into the parent track's timescale. Pass `None` on an /// untimed track; a frame that doesn't match its track is [`Error::TimestampMismatch`]. pub fn write_frame(&mut self, timestamp: impl Into>, data: B) -> Result<()> { - let timestamp = on_track(timestamp.into(), self.track.timescale)?; + let timestamp = on_track(timestamp.into(), self.handle.track.timescale)?; let payload = data.into_bytes(); if payload.len() as u64 > MAX_CACHE_BYTES { return Err(Error::FrameTooLarge); @@ -1002,14 +915,14 @@ impl Producer { let track = self.first_frame_track(); let track = track.as_ref().map(|track| track.read()); - let neighbors = track.as_ref().and_then(|track| track.neighbors(self.info.sequence)); - let mut state = modify(&self.state)?; + let neighbors = track + .as_ref() + .and_then(|track| track.neighbors(self.handle.info.sequence)); + let mut state = modify(&self.handle.state)?; if state.fin.is_some() { return Err(Error::Closed); } - if state.partial.is_some() { - return Err(Error::FrameOpen); - } + debug_assert!(state.partial.is_none(), "a frame is already open"); let next_index = state .next_index .checked_add(1) @@ -1029,21 +942,21 @@ impl Producer { state.committed = state.next_index; state.stamp(timestamp); let bound = state.settle(origin); - self.alive.checked.store(true, Ordering::Relaxed); + self.handle.alive.checked.store(true, Ordering::Relaxed); self.advance_largest(&state); drop(state); // The group's lock is released first: sharing reads it back through its slot. if let (Some(track), Some(start)) = (&track, bound) { - track.share_bound(self.info.sequence, start); + track.share_bound(self.handle.info.sequence, start); } drop(track); // With the group lock released (lock order is track then group), settle // eviction debt if enough has been written since the track last paid. - self.cache.settle(now); + self.handle.cache.settle(now); // An untimed frame presents nothing, so it can expire no read. if let Some(timestamp) = timestamp { - self.cache.wakes().presented(timestamp); + self.handle.cache.wakes().presented(timestamp); } // Ingress payload: one whole frame written. @@ -1060,11 +973,9 @@ impl Producer { /// /// The batch is validated before anything is written, so a rejected frame leaves /// both the group and the buffer exactly as they were, ready to retry or redirect. - /// Returns [`Error::FrameOpen`] if another handle is streaming a frame into this - /// group, since appending around it would reorder the group. pub fn write_frames(&mut self, frames: &mut frame::Buffer) -> Result<()> { for frame in frames.filled() { - on_track(frame.timestamp, self.track.timescale)?; + on_track(frame.timestamp, self.handle.track.timescale)?; if frame.payload.len() as u64 > MAX_CACHE_BYTES { return Err(Error::FrameTooLarge); } @@ -1074,14 +985,14 @@ impl Producer { let bytes: u64 = frames.filled().iter().map(|frame| frame.payload.len() as u64).sum(); let track = self.first_frame_track(); let track = track.as_ref().map(|track| track.read()); - let neighbors = track.as_ref().and_then(|track| track.neighbors(self.info.sequence)); - let mut state = modify(&self.state)?; + let neighbors = track + .as_ref() + .and_then(|track| track.neighbors(self.handle.info.sequence)); + let mut state = modify(&self.handle.state)?; if state.fin.is_some() { return Err(Error::Closed); } - if state.partial.is_some() { - return Err(Error::FrameOpen); - } + debug_assert!(state.partial.is_none(), "a frame is already open"); let next_index = state .next_index .checked_add(count) @@ -1091,7 +1002,7 @@ impl Producer { let origin = match first { Some(timestamp) => state.check_start( neighbors.as_ref(), - on_track(timestamp, self.track.timescale).expect("timestamp scale checked above"), + on_track(timestamp, self.handle.track.timescale).expect("timestamp scale checked above"), )?, None => state.origin, }; @@ -1103,7 +1014,8 @@ impl Producer { let mut now = None; let mut latest = None; for mut frame in frames.drain() { - frame.timestamp = on_track(frame.timestamp, self.track.timescale).expect("timestamp scale checked above"); + frame.timestamp = + on_track(frame.timestamp, self.handle.track.timescale).expect("timestamp scale checked above"); let size = frame.payload.len() as u64; state.cache += size; let slots = state.reserve_frame(); @@ -1116,19 +1028,19 @@ impl Producer { state.committed = next_index; let bound = state.settle(origin); if count > 0 { - self.alive.checked.store(true, Ordering::Relaxed); + self.handle.alive.checked.store(true, Ordering::Relaxed); self.advance_largest(&state); } drop(state); // The group's lock is released first: sharing reads it back through its slot. if let (Some(track), Some(start)) = (&track, bound) { - track.share_bound(self.info.sequence, start); + track.share_bound(self.handle.info.sequence, start); } drop(track); - self.cache.settle(now); + self.handle.cache.settle(now); if let Some(latest) = latest { - self.cache.wakes().presented(latest); + self.handle.cache.wakes().presented(latest); } self.stats.frames(count as u64); self.stats.bytes(bytes); @@ -1153,15 +1065,14 @@ impl Producer { /// The owned counterpart of [`Self::create_frame`], for the wire drivers that /// stream a frame across polls and cannot hold the group borrowed inside their - /// state. The one-live-frame rule the borrow normally enforces becomes the - /// caller's promise; see [`frame::ProducerOwned`]. + /// state. The frame owns the only writer until its finish returns it. /// /// The declared size is the peer's claim, so the buffer is allocated up front only /// while it fits the session's `budget`; otherwise it grows with the bytes received. #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/ingest.md pub(crate) fn create_frame_owned( - &mut self, + mut self, frame: impl Into, budget: &frame::Budget, ) -> Result { @@ -1172,9 +1083,15 @@ impl Producer { Some(_) => FrameBuf::new(size), None => FrameBuf::growing(size), }; - let info = self.open_frame(frame, &buf)?; + let info = match self.open_frame(frame, &buf) { + Ok(info) => info, + Err(err) => { + let _ = self.handle.abort(err.clone()); + return Err(err); + } + }; let meter = self.stats.clone(); - Ok(frame::ProducerOwned::new(self.clone(), buf, info, reserved).with_meter(meter)) + Ok(frame::ProducerOwned::new(self, buf, info, reserved).with_meter(meter)) } /// Open `buf` as the in-flight frame, returning its header in the track's timescale. @@ -1183,21 +1100,21 @@ impl Producer { /// size is only a promise until they arrive. fn open_frame(&mut self, header: frame::Header, buf: &FrameBuf) -> Result { let frame = header.info; - let timestamp = on_track(frame.timestamp, self.track.timescale)?; + let timestamp = on_track(frame.timestamp, self.handle.track.timescale)?; if frame.size > MAX_CACHE_BYTES { return Err(Error::FrameTooLarge); } let track = self.first_frame_track(); let track = track.as_ref().map(|track| track.read()); - let neighbors = track.as_ref().and_then(|track| track.neighbors(self.info.sequence)); - let mut state = modify(&self.state)?; + let neighbors = track + .as_ref() + .and_then(|track| track.neighbors(self.handle.info.sequence)); + let mut state = modify(&self.handle.state)?; if state.fin.is_some() { return Err(Error::Closed); } - if state.partial.is_some() { - return Err(Error::FrameOpen); - } + debug_assert!(state.partial.is_none(), "a frame is already open"); let next_index = state .next_index .checked_add(1) @@ -1235,20 +1152,20 @@ impl Producer { // place in time is known before a single payload byte streams in. state.stamp(timestamp); let bound = state.settle(origin); - self.alive.checked.store(true, Ordering::Relaxed); + self.handle.alive.checked.store(true, Ordering::Relaxed); drop(state); // The group's lock is released first: sharing reads it back through its slot. if let (Some(track), Some(start)) = (&track, bound) { - track.share_bound(self.info.sequence, start); + track.share_bound(self.handle.info.sequence, start); } drop(track); // With the group lock released (lock order is track then group), settle // eviction debt if enough has been written since the track last paid. - self.cache.settle(now); + self.handle.cache.settle(now); // An untimed frame presents nothing, so it can expire no read. if let Some(timestamp) = timestamp { - self.cache.wakes().presented(timestamp); + self.handle.cache.wakes().presented(timestamp); } // Ingress payload: one frame opened; its bytes are counted per chunk as the @@ -1268,15 +1185,20 @@ impl Producer { // mid-write. `charge_partial` takes `&mut`, which marks the guard modified: kio // only notifies on a mutably-accessed guard's release, and that notify is what // delivers the chunk to parked readers. - let now = self.state.write().ok().and_then(|mut state| state.charge_partial()); + let now = self + .handle + .state + .write() + .ok() + .and_then(|mut state| state.charge_partial()); // A long streamed frame also counts as track activity for the independent // expiry time gate. - self.cache.settle(now); + self.handle.cache.settle(now); } /// Commit the in-flight frame as a completed frame (called by [`frame::Producer::finish`]). pub(super) fn frame_commit(&mut self, frame: Frame) -> Result<()> { - let mut state = modify(&self.state)?; + let mut state = modify(&self.handle.state)?; // Completing the frame charges whatever it wrote since the last notify, and is a // write access like any chunk, and the only one the payload is guaranteed to get: // the wire ingest defers its chunk notifications to the poll boundary, so a tail @@ -1298,16 +1220,14 @@ impl Producer { // With the group lock released (lock order is track then group), settle // eviction debt and age idle content out, reusing the tick above. - self.cache.settle(now); + self.handle.cache.settle(now); Ok(()) } - /// Raise the track's largest to the last frame committed. Called under the group lock, - /// as [`Self::finish`] marks it final, so a write on another handle cannot land after a - /// finish and reopen a final largest group. + /// Raise the track's largest to the last committed frame. fn advance_largest(&self, state: &GroupState) { - self.cache.advance_largest(track::Position { - group: self.info.sequence, + self.handle.cache.advance_largest(track::Position { + group: self.handle.info.sequence, frame: (state.committed - 1) as u64, }); } @@ -1315,15 +1235,190 @@ impl Producer { /// Fail the group because an in-flight frame couldn't complete (called by /// [`frame::Producer::abort`] / its drop). pub(super) fn frame_abort(&mut self, err: Error) { - let _ = self.clone().abort(err); + let _ = self.handle.close_aborted(err); + } + + /// Mark the group as complete; no more frames will be written. + /// + /// Borrows rather than consumes, so a later failure can still be reported through + /// [`abort`](Self::abort). The handle also keeps the cached frames readable. + pub fn finish(&mut self) -> Result<()> { + let mut state = modify(&self.handle.state)?; + debug_assert!(state.partial.is_none(), "a frame is already open"); + state.fin = Some(state.next_index); + // A finished group can no longer raise the track's largest, which may end its stream. + self.handle.cache.finish_largest(self.sequence); + Ok(()) + } + + /// Abort the group with the given error. + /// + /// Consumes the writer. Drops the cached frames so a stale [`Consumer`] can't pin + /// their buffers in memory forever; consumers that haven't drained yet surface the + /// abort error instead of the leftover cache. + pub fn abort(self, err: Error) -> Result<()> { + self.handle.close_aborted(err) + } + + /// Abort a write that would grow the group past its budget, holding the lock already + /// taken for that write so nothing else lands in between. + fn abort_too_large(&self, state: kio::Mut<'_, GroupState>) -> Error { + self.handle.commit_abort(state, Error::GroupTooLarge); + Error::GroupTooLarge + } + + /// Block until the group is aborted, including by eviction. Finishing does not close it. + #[cfg(feature = "async")] + pub async fn closed(&self) -> Error { + kio::wait(|waiter| self.handle.poll_closed(waiter)).await + } + /// The non-writing observer used by the cache and built-in sessions. + // private: capability gap + // Sessions need an abortable observer while public callers use Demand. + pub(crate) fn handle(&self) -> Handle { + self.handle.clone() } /// One past the index of the last frame written (completed or in-flight), which is /// also the index the next frame will get. /// - /// Counts any frames the group [started past](Self::start_at), so it's the group's + /// Counts any frames the group [started past](Producer::start_at), so it's the group's /// logical length rather than the number of frames this handle holds. pub fn frame_count(&self) -> usize { + self.handle.frame_count() + } + + /// Abort with `err` only while nothing consumes the group, returning whether it is + /// closed. Consumer creation and the check share a lock, so a reader arriving after + /// [`poll_unused`](Self::poll_unused) keeps the group alive instead of reading the abort. + #[allow(dead_code)] + // The answering API retains these on the writer as well as the session observer. + // pending: /quest/m1/public-model/answer.md + pub(crate) fn abort_unused(&self, err: Error) -> bool { + self.handle.abort_unused(err) + } + + /// Whether the group has been aborted (including pool eviction). The track's + /// read paths treat an aborted cached group as absent. + /// + /// Reads the mirror rather than the group's state, so a track scan holding the + /// track lock never takes the group's. Monotone, and only ever conservative: a + /// concurrent abort can still read as live for the length of [`Self::abort`], + /// which hands out a group whose consumer then surfaces the abort. + // private: test + pub(crate) fn is_aborted(&self) -> bool { + self.handle.is_aborted() + } + + /// Create a new consumer for the group. + pub fn consume(&self) -> Consumer { + self.handle.consume() + } + + /// Poll until the group is aborted, including by eviction; ready with the cause. + /// Finishing does not close it. + pub fn poll_closed(&self, waiter: &kio::Waiter) -> Poll { + self.handle.poll_closed(waiter) + } + + /// Watch reader demand without keeping the group alive. + pub fn demand(&self) -> Demand { + self.handle.demand() + } + + /// Poll for the group becoming unused (every consumer dropped). + #[allow(dead_code)] + // The answering API retains these on the writer as well as the session observer. + // pending: /quest/m1/public-model/answer.md + pub(crate) fn poll_unused(&self, waiter: &kio::Waiter) -> Poll<()> { + self.handle.poll_unused(waiter) + } +} + +impl Handle { + /// Abort the group without taking ownership of its writer. + // private: capability gap + // Sessions cancel a group while its writer is in a frame. + pub(crate) fn abort(&self, err: Error) -> Result<()> { + self.close_aborted(err) + } + + /// Adopt the frames of `head` below where this copy starts, so it holds the group + /// from `head`'s start, as if this route had delivered them. + /// + /// A no-op unless `head` starts below this copy and reaches it, and the frames fit the + /// group's budget. Readers keep their positions, since frames keep their indices. A + /// group whose frames build on earlier ones (a compressed group) primes its decoder + /// from the adopted frames here. + pub(super) fn adopt_head(&self, head: &Head) { + let Ok(mut state) = self.state.write() else { + return; + }; + let offset = state.offset; + let reaches = head.start.saturating_add(head.frames.len()) >= offset; + if state.abort.is_some() || state.sparse() || head.start >= offset || !reaches { + return; + } + let count = offset - head.start; + let frames = &head.frames[..count]; + let fields = || head.objects.iter().take(count).flatten(); + let payload: u64 = frames.iter().map(|frame| frame.payload.len() as u64).sum(); + let metadata: u64 = fields().map(|fields| fields.heap()).sum(); + // The in-flight frame's remainder was admitted at its open and is charged as it + // streams in, without another check. + if state.would_overflow(count, payload + metadata + state.unwritten()) { + return; + } + + let before = state.frames.capacity().saturating_sub(FRAME_SLOTS); + state.frames.reserve(count); + let mut growth = ((state.frames.capacity().saturating_sub(FRAME_SLOTS) - before) * size_of::()) as u64; + for frame in frames.iter().rev() { + state.frames.push_front(frame.clone()); + } + // Keep the fields aligned with the frames: the adopted ones lead. + if fields().next().is_some() || state.relay.as_ref().is_some_and(|relay| !relay.objects.is_empty()) { + let relay = state.relay(); + let before = relay.objects.capacity(); + relay.objects.reserve(count); + let slots = ((relay.objects.capacity() - before) * size_of::>>()) as u64; + for index in (0..count).rev() { + relay.objects.push_front(head.objects.get(index).cloned().flatten()); + } + relay.bytes += slots + metadata; + growth += slots; + } + state.offset = head.start; + state.cache += payload; + let start = frames.iter().find_map(|frame| frame.timestamp); + state.timeline = match (state.timeline, start) { + (Timeline::Timed { latest, .. }, Some(start)) => Timeline::Timed { start, latest }, + (Timeline::Empty, Some(start)) => Timeline::Timed { + start, + latest: frames.iter().rev().find_map(|frame| frame.timestamp).unwrap_or(start), + }, + (Timeline::Empty, None) => Timeline::Untimed, + (timeline, _) => timeline, + }; + state.adopted = Some(head.first_object); + if let Some(wire) = state.wire_mut() { + wire.first_object = head.first_object; + wire.first_id = head.start as u64; + wire.last = wire.last.or(Some(offset as u64 - 1)); + } + let now = state.charge.add(payload + metadata + growth); + drop(state); + self.cache.settle(now); + } + + /// One past the index of the last frame written (completed or in-flight), which is + /// also the index the next frame will get. + /// + /// Counts any frames the group [started past](Producer::start_at), so it's the group's + /// logical length rather than the number of frames this handle holds. + // private: capability gap + // Sessions observe a group while its sole writer belongs to a frame. + pub(crate) fn frame_count(&self) -> usize { self.state.read().next_index } @@ -1342,30 +1437,6 @@ impl Producer { Ok(()) } - /// Mark the group as complete; no more frames will be written. - /// - /// Borrows rather than consumes, so a later failure can still be reported through - /// [`abort`](Self::abort). The handle also keeps the cached frames readable. - pub fn finish(&self) -> Result<()> { - let mut state = modify(&self.state)?; - if state.partial.is_some() { - return Err(Error::FrameOpen); - } - state.fin = Some(state.next_index); - // A finished group can no longer raise the track's largest, which may end its stream. - self.cache.finish_largest(self.sequence); - Ok(()) - } - - /// Abort the group with the given error. - /// - /// Consumes the handle. Drops the cached frames so a stale [`Consumer`] can't pin - /// their buffers in memory forever; consumers that haven't drained yet surface the - /// abort error instead of the leftover cache. - pub fn abort(self, err: Error) -> Result<()> { - self.close_aborted(err) - } - /// Abort with `err` only while nothing consumes the group, returning whether it is /// closed. Consumer creation and the check share a lock, so a reader arriving after /// [`poll_unused`](Self::poll_unused) keeps the group alive instead of reading the abort. @@ -1400,13 +1471,6 @@ impl Producer { self.cache.aborted(self.sequence, cut); } - /// Abort a write that would grow the group past its budget, holding the lock already - /// taken for that write so nothing else lands in between. - fn abort_too_large(&self, state: kio::Mut<'_, GroupState>) -> Error { - self.commit_abort(state, Error::GroupTooLarge); - Error::GroupTooLarge - } - /// Whether the group has been aborted (including pool eviction). The track's /// read paths treat an aborted cached group as absent. /// @@ -1572,7 +1636,9 @@ impl Producer { } /// Create a new consumer for the group. - pub fn consume(&self) -> Consumer { + // private: capability gap + // Sessions observe a group while its sole writer belongs to a frame. + pub(crate) fn consume(&self) -> Consumer { self.consumer(self.state.consume()) } @@ -1622,20 +1688,18 @@ impl Producer { } } - /// Block until the group is aborted, including by eviction. Finishing does not close it. - #[cfg(feature = "async")] - pub async fn closed(&self) -> Error { - kio::wait(|waiter| self.poll_closed(waiter)).await - } - /// Poll until the group is aborted, including by eviction; ready with the cause. /// Finishing does not close it. - pub fn poll_closed(&self, waiter: &kio::Waiter) -> Poll { + // private: capability gap + // Sessions observe a group while its sole writer belongs to a frame. + pub(crate) fn poll_closed(&self, waiter: &kio::Waiter) -> Poll { self.state.poll_closed(waiter).map(|()| self.abort_reason()) } /// Watch reader demand without keeping the group alive. - pub fn demand(&self) -> Demand { + // private: capability gap + // Sessions observe a group while its sole writer belongs to a frame. + pub(crate) fn demand(&self) -> Demand { Demand { sequence: self.info.sequence, state: DemandSource::Group(self.state.weak()), @@ -1741,19 +1805,6 @@ impl Demand { } } -impl Clone for Producer { - fn clone(&self) -> Self { - Self { - info: self.info, - state: self.state.clone(), - track: self.track.clone(), - cache: self.cache.clone(), - stats: self.stats.clone(), - alive: self.alive.clone(), - } - } -} - /// A small inline batch of completed frames, drained from the shared group state /// under one lock and then handed out without re-locking. /// @@ -2670,7 +2721,7 @@ mod test { }; let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); frame.write(Bytes::from_static(b"f")).unwrap(); - frame.finish().unwrap(); + group = frame.finish().unwrap(); } assert!(pool.used() > plain + 10, "the metadata table is charged"); for _ in 0..Prefetch::CAP { @@ -2812,7 +2863,7 @@ mod test { frame.finish().unwrap(); } } - let capacity = group.state.read().frames.capacity(); + let capacity = group.handle.state.read().frames.capacity(); assert!(capacity > FRAME_SLOTS); assert_eq!( pool.used() - before, @@ -2896,14 +2947,17 @@ mod test { fn an_untimed_frame_still_starts_the_group() { let mut producer = Info { sequence: 0 }.produce_untimed(); let waiter = kio::Waiter::noop(); - assert!(producer.poll_started(&waiter).is_pending(), "nothing presented yet"); + assert!( + producer.handle.poll_started(&waiter).is_pending(), + "nothing presented yet" + ); producer.write_frame(None, Bytes::from_static(b"hello")).unwrap(); producer.finish().unwrap(); - assert!(producer.poll_started(&waiter).is_ready()); - assert_eq!(producer.timestamp(), None); - assert_eq!(producer.latest(), None); + assert!(producer.handle.poll_started(&waiter).is_ready()); + assert_eq!(producer.handle.timestamp(), None); + assert_eq!(producer.handle.latest(), None); let mut consumer = producer.consume(); let frame = consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); @@ -2990,7 +3044,7 @@ mod test { #[test] #[cfg(feature = "async")] fn group_finish_returns_none() { - let producer = Info { sequence: 0 }.produce(); + let mut producer = Info { sequence: 0 }.produce(); producer.finish().unwrap(); let mut consumer = producer.consume(); @@ -3010,7 +3064,7 @@ mod test { .map(|sequence| { let mut group = track.create_group(Info { sequence }).unwrap(); group.write_frame(Timestamp::ZERO, b"f".as_ref()).unwrap(); - group.clone().finish().unwrap(); + group.finish().unwrap(); group }) .collect(); @@ -3018,7 +3072,7 @@ mod test { let waiter = kio::Waiter::noop(); assert!(subscriber.poll_recv_group(&waiter).is_pending()); subscriber.set_groups(..1); - let _unrelated = groups[2].state.read(); + let _unrelated = groups[2].handle.state.read(); let Poll::Ready(Ok(Some(group))) = subscriber.poll_recv_group(&waiter) else { panic!("group zero is in range") }; @@ -3040,7 +3094,7 @@ mod test { fn abort_unused_pairs_with_try_consume() { let producer = Info { sequence: 0 }.produce(); - let consumer = producer.try_consume().expect("open"); + let consumer = producer.handle.try_consume().expect("open"); assert!( !producer.abort_unused(crate::Error::Cancel), "a reader declines the abort" @@ -3048,7 +3102,10 @@ mod test { drop(consumer); assert!(producer.abort_unused(crate::Error::Cancel)); - assert!(producer.try_consume().is_none(), "an aborted group mints no reader"); + assert!( + producer.handle.try_consume().is_none(), + "an aborted group mints no reader" + ); } #[test] @@ -3060,11 +3117,11 @@ mod test { // A stale consumer that never reads must not pin the cached frames. let _consumer = producer.consume(); - assert_eq!(producer.state.read().frames.len(), 1); + assert_eq!(producer.handle.state.read().frames.len(), 1); - producer.clone().abort(crate::Error::Cancel).unwrap(); + producer.handle().abort(crate::Error::Cancel).unwrap(); - let state = producer.state.read(); + let state = producer.handle.state.read(); assert!(state.frames.is_empty(), "cached frames should be dropped on abort"); assert_eq!(state.cache, 0); } @@ -3087,8 +3144,8 @@ mod test { let handoff = producer.consume().handoff(); assert_eq!(handoff.head().map(|head| head.frames.len()), Some(2), "read live"); - producer.clone().abort(err.clone()).unwrap(); - assert!(producer.state.read().frames.is_empty(), "{err}: released"); + producer.handle().abort(err.clone()).unwrap(); + assert!(producer.handle.state.read().frames.is_empty(), "{err}: released"); assert_eq!(pool.used() > 0, kept, "{err}: billed only while held"); let head = handoff.head(); assert_eq!(head.is_some(), kept, "{err}"); @@ -3111,7 +3168,7 @@ mod test { let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); let handoff = producer.consume().handoff(); - producer.clone().abort(Error::Cancel).unwrap(); + producer.handle().abort(Error::Cancel).unwrap(); drop(producer); assert!(handoff.head().is_some()); @@ -3159,7 +3216,7 @@ mod test { let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); let handoff = producer.consume().handoff(); - producer.clone().abort(Error::Cancel).unwrap(); + producer.handle().abort(Error::Cancel).unwrap(); assert!(handoff.head().is_none()); assert_eq!(pool.used(), 0); } @@ -3172,7 +3229,7 @@ mod test { let cache = cache::Track::new(pool, kio::Weak::new()); let mut tail = Producer::new(Info::from(0u64), track::Info::default(), cache); tail.start_at(1).unwrap(); - let adopter = tail.clone(); + let adopter = tail.handle(); let _frame = tail .create_frame(frame::Info { size: MAX_CACHE_BYTES - 1, @@ -3242,18 +3299,21 @@ mod test { let mut reader = tail.consume(); reader.start_at(2); let before = pool.used(); - tail.adopt_head(&head); + tail.handle.adopt_head(&head); assert!(pool.used() >= before + 2, "the adopted frames are charged"); if !wired_first { tail.set_wire(wire.clone()).unwrap(); } - let written = tail.state.read().wire().cloned().unwrap(); + let written = tail.handle.state.read().wire().cloned().unwrap(); assert_eq!( (written.first_object, written.first_id, written.last), (true, 0, Some(1)) ); tail.mark_gap(2, None).unwrap(); - assert!(tail.state.read().wire().unwrap().fetchable, "no gap below the stream"); + assert!( + tail.handle.state.read().wire().unwrap().fetchable, + "no gap below the stream" + ); tail.write_frame(None, Bytes::from_static(b"c")).unwrap(); tail.finish().unwrap(); @@ -3283,8 +3343,8 @@ mod test { #[test] #[cfg(feature = "async")] fn drop_unfinished_clears_cached_frames() { - let producer = Info { sequence: 0 }.produce(); - let mut writer = producer.clone(); + let mut writer = Info { sequence: 0 }.produce(); + let producer = writer.handle(); writer .write_frame(Timestamp::ZERO, Bytes::from_static(b"data")) .unwrap(); @@ -3304,9 +3364,9 @@ mod test { #[test] fn drop_after_abort_does_not_warn() { let warns = count_drop_warnings("group::Producer dropped without finish", || { - let producer = Info { sequence: 0 }.produce(); - let keep = producer.clone(); - let mut writer = producer.clone(); + let mut writer = Info { sequence: 0 }.produce(); + let keep = writer.handle(); + let producer = writer.handle(); writer .write_frame(Timestamp::ZERO, Bytes::from_static(b"data")) .unwrap(); @@ -3320,8 +3380,8 @@ mod test { #[test] fn drop_unfinished_warns() { let warns = count_drop_warnings("group::Producer dropped without finish", || { - let producer = Info { sequence: 0 }.produce(); - let mut writer = producer.clone(); + let mut writer = Info { sequence: 0 }.produce(); + let producer = writer.handle(); writer .write_frame(Timestamp::ZERO, Bytes::from_static(b"data")) .unwrap(); @@ -3381,7 +3441,7 @@ mod test { )); { - let state = producer.state.read(); + let state = producer.handle.state.read(); assert!(matches!(state.abort, Some(Error::GroupTooLarge))); assert!(state.frames.is_empty()); assert_eq!(state.offset, 0); @@ -3400,7 +3460,7 @@ mod test { } producer.finish().unwrap(); - let state = producer.state.read(); + let state = producer.handle.state.read(); assert_eq!(state.offset, 0); assert_eq!(state.frames.len(), MAX_GROUP_FRAMES); assert!(state.abort.is_none()); @@ -3416,7 +3476,7 @@ mod test { producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"x")), Err(Error::GroupTooLarge) )); - assert!(matches!(producer.state.read().abort, Some(Error::GroupTooLarge))); + assert!(matches!(producer.handle.state.read().abort, Some(Error::GroupTooLarge))); } #[test] @@ -3463,16 +3523,16 @@ mod test { let pool = cache::Pool::new(cache::Config::default().with_expiry(std::time::Duration::from_secs(1))); let (producer, consumer) = prefetched_consumer(&pool, std::time::Duration::MAX); consumer.keep_alive(); - let stamp = producer.cache_accessed(); - assert_eq!(producer.cache_accessed_tick(Some(pool.now())), Some(pool.now())); + let stamp = producer.handle.cache_accessed(); + assert_eq!(producer.handle.cache_accessed_tick(Some(pool.now())), Some(pool.now())); consumer.keep_alive(); assert_eq!( - producer.cache_accessed(), + producer.handle.cache_accessed(), stamp, "same-tick reads do not inflate eviction rank" ); assert_eq!( - producer.cache_accessed_tick(None), + producer.handle.cache_accessed_tick(None), None, "every frame resets the idle clock" ); @@ -3483,14 +3543,14 @@ mod test { fn keep_alive_keeps_the_counted_access_mean_balanced() { let pool = cache::Pool::new(cache::Config::default().with_capacity(1_000_000)); let (producer, consumer) = prefetched_consumer(&pool, std::time::Duration::MAX); - producer.cache_demote(); + producer.handle.cache_demote(); consumer.keep_alive(); - assert_eq!(pool.average(), Some(producer.cache_accessed())); - let before = producer.cache_accessed(); + assert_eq!(pool.average(), Some(producer.handle.cache_accessed())); + let before = producer.handle.cache_accessed(); pool.step(std::time::Duration::from_millis(100)); consumer.keep_alive(); - assert!(producer.cache_accessed() > before); - assert_eq!(pool.average(), Some(producer.cache_accessed())); + assert!(producer.handle.cache_accessed() > before); + assert_eq!(pool.average(), Some(producer.handle.cache_accessed())); producer.abort(Error::Cancel).unwrap(); assert_eq!( pool.average(), @@ -3505,12 +3565,12 @@ mod test { let config = cache::Config::default().with_expiry(std::time::Duration::from_secs(1)); let pool = cache::Pool::new(config); let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::MAX); - let before = producer.cache_accessed(); + let before = producer.handle.cache_accessed(); pool.step(std::time::Duration::from_millis(600)); consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); - assert!(producer.cache_accessed() > before, "the pool cadence is used"); + assert!(producer.handle.cache_accessed() > before, "the pool cadence is used"); } #[test] @@ -3519,12 +3579,15 @@ mod test { let config = cache::Config::default().with_expiry(std::time::Duration::from_secs(30)); let pool = cache::Pool::new(config); let (producer, mut consumer) = prefetched_consumer(&pool, std::time::Duration::from_secs(1)); - let before = producer.cache_accessed(); + let before = producer.handle.cache_accessed(); pool.step(std::time::Duration::from_millis(600)); consumer.read_frame().now_or_never().unwrap().unwrap().unwrap(); - assert!(producer.cache_accessed() > before, "the track cadence remains in force"); + assert!( + producer.handle.cache_accessed() > before, + "the track cadence remains in force" + ); } /// Reading more than one prefetch batch drains every frame in order across the @@ -3934,9 +3997,10 @@ mod test { fn frame_is_charged_as_written() { let pool = cache::Pool::unbounded(); let cache = cache::Track::new(pool.clone(), kio::Weak::new()); - let mut producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); + let producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); let before = pool.used(); + let observing = producer.handle(); let mut frame = producer .create_frame_owned(sized(MAX_CACHE_BYTES), &frame::Budget::default()) .unwrap(); @@ -3946,33 +4010,48 @@ mod test { assert_eq!(pool.used(), before, "charged before the write was published"); frame.notify(); assert_eq!(pool.used(), before + 100); - assert_eq!(producer.state.read().cache, 100); + assert_eq!(observing.state.read().cache, 100); // A reader skipping the group still misses the whole declared frame. - assert_eq!(producer.state.read().content().bytes, MAX_CACHE_BYTES); + assert_eq!(observing.state.read().content().bytes, MAX_CACHE_BYTES); // Aborting releases what was charged. frame.abort(Error::Cancel).unwrap(); - assert_eq!(producer.state.read().cache, 0); + assert_eq!(observing.state.read().cache, 0); assert!(pool.used() <= before); } + #[test] + fn refused_owned_frame_aborts_with_its_error() { + let producer = Info { sequence: 0 }.produce(); + let handle = producer.handle(); + assert!(matches!( + producer.create_frame_owned(sized(MAX_CACHE_BYTES + 1), &frame::Budget::default()), + Err(Error::FrameTooLarge) + )); + assert!(matches!( + handle.poll_closed(&kio::Waiter::noop()), + Poll::Ready(Error::FrameTooLarge) + )); + } + /// Completing a frame charges whatever it wrote since the last notify. #[test] fn frame_commit_charges_the_tail() { let pool = cache::Pool::unbounded(); let cache = cache::Track::new(pool.clone(), kio::Weak::new()); - let mut producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); + let producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); let before = pool.used(); + let observing = producer.handle(); let mut frame = producer .create_frame_owned(sized(300), &frame::Budget::default()) .unwrap(); frame.write(Bytes::from(vec![0u8; 100])).unwrap(); frame.notify(); frame.write(Bytes::from(vec![0u8; 200])).unwrap(); - frame.finish().unwrap(); + let _producer = frame.finish().unwrap(); assert_eq!(pool.used(), before + 300); - assert_eq!(producer.state.read().cache, 300); + assert_eq!(observing.state.read().cache, 300); } /// Frames within the session's budget allocate their declared size up front; past @@ -3981,8 +4060,8 @@ mod test { #[test] fn frame_budget_bounds_upfront_allocation() { let budget = frame::Budget::new(1024); - let mut a = Info { sequence: 0 }.produce(); - let mut b = Info { sequence: 1 }.produce(); + let a = Info { sequence: 0 }.produce(); + let b = Info { sequence: 1 }.produce(); let mut first = a.create_frame_owned(sized(1024), &budget).unwrap(); first.write(Bytes::from_static(b"x")).unwrap(); @@ -3998,10 +4077,10 @@ mod test { second.abort(Error::Cancel).unwrap(); first.write(Bytes::from(vec![0u8; 1023])).unwrap(); - first.finish().unwrap(); + let mut a = first.finish().unwrap(); a.finish().unwrap(); - let mut a = Info { sequence: 2 }.produce(); + let a = Info { sequence: 2 }.produce(); let mut third = a.create_frame_owned(sized(1024), &budget).unwrap(); third.write(Bytes::from_static(b"x")).unwrap(); assert_eq!(third.allocated(), 1024, "the finished frame did not return its share"); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index e82a3a24126..8cdb0438d2c 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -3000,7 +3000,8 @@ mod test { #[cfg(feature = "async")] fn a_group_no_route_continues_wakes_when_an_older_successor_lands() { let mut held = Held::new(&[(4, Some(4000))]); - held.group(5).write_frame(ts(4050), b"b".as_ref()).unwrap(); + let mut edge = held.group(5); + edge.write_frame(ts(4050), b"b".as_ref()).unwrap(); held.settle(); let _newer = held.group(6); assert!(!held.woken(), "a landing above the successor changes nothing"); @@ -3175,7 +3176,7 @@ mod test { let routes = Producer::new(); let logical = logical(&routes); let a = copy(); - let mut group = a.create_group(group::Info { sequence: 0 }).unwrap(); + let group = a.create_group(group::Info { sequence: 0 }).unwrap(); group .set_wire(group::Wire { sparse: false, @@ -3203,7 +3204,7 @@ mod test { ) .unwrap(); frame.write(bytes::Bytes::from_static(b"a")).unwrap(); - frame.finish().unwrap(); + let group = frame.finish().unwrap(); routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::MAX); let mut reading = recv(&mut sub); @@ -3272,8 +3273,9 @@ mod test { ) .unwrap(); frame.write(bytes::Bytes::from_static(payload)).unwrap(); - frame.finish().unwrap(); + group = frame.finish().unwrap(); } + group.finish().unwrap(); b } @@ -3542,8 +3544,8 @@ mod test { routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(10)); assert!(sub.recv_datagram().now_or_never().is_none()); + let _zero = ordered_first.then(|| a.create_group(group::Info { sequence: 0 }).unwrap()); if ordered_first { - let _zero = a.create_group(group::Info { sequence: 0 }).unwrap(); assert_eq!( kio::wait(|waiter| sub.poll_next_group(waiter)) .now_or_never() diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c91cfc6a5a8..b11c377a365 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -488,7 +488,7 @@ impl Neighbors { /// `cache::Charge`, so they share the group's lifecycle exactly: an abort from any /// handle releases the bytes and the sample together. struct Slot { - group: group::Producer, + group: group::Handle, // Incarnation stamp, echoed by this slot's arrival entry (if any). A re-served // sequence (an aborted group re-created by the publisher or re-fetched as @@ -512,7 +512,7 @@ struct Slot { // asked for. It runs to the end of the group too, so it is served in the live // group's place while it lasts; `group` stays the slot, still written by the feed, // so an abandoned fetch leaves the group servable rather than gone. Boxed: rare. - head: Option>, + head: Option>, } impl Slot { @@ -533,7 +533,7 @@ impl Slot { } /// The copy to hand readers: the fetched head while it lasts, else the live group. - fn serving(&self) -> &group::Producer { + fn serving(&self) -> &group::Handle { match &self.head { Some(head) if !head.is_aborted() => head, _ => &self.group, @@ -541,7 +541,7 @@ impl Slot { } /// Every copy this slot holds, the live group first. - fn copies(&self) -> impl Iterator { + fn copies(&self) -> impl Iterator { std::iter::once(&self.group).chain(self.head.as_deref()) } @@ -565,7 +565,7 @@ impl Slot { /// The bytes every copy holds, all freed together. fn cache_size(&self) -> u64 { - self.copies().map(group::Producer::cache_size).sum() + self.copies().map(group::Handle::cache_size).sum() } /// Whether every copy still held sat idle past the scan's expiry window. Asks @@ -591,7 +591,7 @@ impl Slot { /// The checked start of whichever copy began at frame 0. fn bound(&self) -> Option { - self.copies().find_map(group::Producer::bound) + self.copies().find_map(group::Handle::bound) } /// Abort every copy this slot holds. @@ -800,7 +800,7 @@ impl TrackState { self.feed == Feed::Live || self.sealed || self.end.is_some() || self.abort.is_some() } - fn poll_recv_group(&self, index: usize, min_sequence: u64) -> Poll>> { + fn poll_recv_group(&self, index: usize, min_sequence: u64) -> Poll>> { let start = index.saturating_sub(self.offset); let readable = self.readable(); let min_sequence = min_sequence.max(self.live_floor.unwrap_or(0)); @@ -879,7 +879,7 @@ impl TrackState { next_sequence: u64, end_sequence: Option, window: &Window, - ) -> Poll>> { + ) -> Poll>> { // Nothing more can arrive once the track was sealed (dropped with its end // declared) or aborted. Either closed the channel, so parking is not an option: // the consumer would be handed the abort, or `Dropped`, instead of how it ended. @@ -946,7 +946,7 @@ impl TrackState { /// A group cached from a frame-bounded subscription starts partway in, and serving /// it to someone who asked for the whole group would silently hand back a tail. It /// is a miss instead, so the fetch goes upstream for the frames that are missing. - fn covering_group(&self, sequence: u64, frame_start: u64) -> Option<&group::Producer> { + fn covering_group(&self, sequence: u64, frame_start: u64) -> Option<&group::Handle> { self.lookup.get(&sequence)?.copies().find(|group| { group .live_first_frame() @@ -1447,14 +1447,14 @@ impl TrackState { let open: Vec<_> = self .lookup .iter() - .filter(|(_, slot)| slot.visible && !slot.copies().any(group::Producer::is_finished)) + .filter(|(_, slot)| slot.visible && !slot.copies().any(group::Handle::is_finished)) .filter_map(|(&sequence, _)| Some(sequence..sequence.checked_add(1)?)) .collect(); for groups in open { self.drop_groups(groups); } self.lookup - .retain(|_, slot| slot.copies().any(group::Producer::is_finished)); + .retain(|_, slot| slot.copies().any(group::Handle::is_finished)); self.withheld = self.lookup.values().filter(|slot| slot.pending).count(); let lookup = &self.lookup; self.bounds @@ -1571,7 +1571,7 @@ impl TrackState { /// eviction. `visible` controls arrival-order delivery: publisher-produced /// groups reach subscribers, fetched backfill is served by sequence only. A /// `pending` group joins arrival order only once [`Self::reveal`] shows it. - fn insert_group(&mut self, group: &group::Producer, visible: bool, pending: bool) { + fn insert_group(&mut self, group: &group::Handle, visible: bool, pending: bool) { let sequence = group.sequence; self.next_stamp = self.next_stamp.wrapping_add(1); let stamp = self.next_stamp; @@ -1644,7 +1644,7 @@ impl TrackState { /// Show a [`Producer::receive_group`] group to readers, if `group` still holds its slot. #[cfg_attr(not(feature = "async"), allow(dead_code))] - fn reveal(&mut self, group: &group::Producer) { + fn reveal(&mut self, group: &group::Handle) { let sequence = group.sequence; let Some(slot) = self.lookup.get_mut(&sequence) else { return; @@ -1699,7 +1699,7 @@ impl TrackState { /// Admit a freshly-created group: settle eviction debt first (so the newcomer /// can never be a victim of the very write that created it), insert it, then /// expire idle groups. - fn commit_group(&mut self, group: &group::Producer, pending: bool) { + fn commit_group(&mut self, group: &group::Handle, pending: bool) { self.charge_debt(); self.insert_group(group, true, pending); self.evict_expired(); @@ -1885,7 +1885,7 @@ impl TrackState { } /// Cap a new group the end cuts, so it never holds a frame past the end. - fn cap(&self, group: &group::Producer) -> Result<()> { + fn cap(&self, group: &group::Handle) -> Result<()> { match self.end { Some(end) if end.frame != 0 && end.group == group.sequence => group.limit(Some(end.frame)), _ => Ok(()), @@ -2150,10 +2150,10 @@ impl TrackState { // in between would otherwise see it begin at 0 and get a reader that later skips // the head it asked for. group.start_at(frame_start)?; - self.cap(&group)?; + self.cap(&group.handle())?; // A backfill exists because someone is fetching it right now: stamp that // access so the eviction walk can't kill it before the fetch resolves. - group.cache_refresh(); + group.handle().cache_refresh(); // Settled first, like `commit_group`, which may evict the live slot itself. self.charge_debt(); @@ -2162,13 +2162,13 @@ impl TrackState { Some(slot) => { // Joins the slot's standing: demoted already unless it is the live edge. if !protected { - group.cache_demote(); + group.handle().cache_demote(); } - slot.head = Some(Box::new(group.clone())); + slot.head = Some(Box::new(group.handle())); } // Invisible to arrival-order subscribers: fetched on demand, not produced // live by the publisher. - None => self.insert_group(&group, false, false), + None => self.insert_group(&group.handle(), false, false), } self.evict_expired(); Ok(group) @@ -2364,7 +2364,7 @@ impl Producer { /// stream ended. A no-op once another incarnation took its sequence. #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/ingest.md - pub(crate) fn reveal_group(&self, group: &group::Producer) { + pub(crate) fn reveal_group(&self, group: &group::Handle) { if let Ok(mut state) = self.modify() { state.reveal(group); } @@ -2382,8 +2382,8 @@ impl Producer { state.claim_sequence(group.sequence, 0)?; let group = group::Producer::new(group, track, state.cache.clone()).with_meter(self.stats.meter()); - state.cap(&group)?; - state.commit_group(&group, pending); + state.cap(&group.handle())?; + state.commit_group(&group.handle(), pending); Ok(group) } @@ -2405,8 +2405,8 @@ impl Producer { let group = group::Producer::new(group::Info { sequence }, track, state.cache.clone()).with_meter(self.stats.meter()); - state.cap(&group)?; - state.commit_group(&group, false); + state.cap(&group.handle())?; + state.commit_group(&group.handle(), false); Ok(group) } @@ -3296,7 +3296,7 @@ impl TrackWeak { return None; } // An open group still takes frames, which could land after the linger fixed here. - let open = |group: &group::Producer| !group.is_finished() && !group.is_aborted(); + let open = |group: &group::Handle| !group.is_finished() && !group.is_aborted(); if state.lookup.values().any(|slot| slot.copies().any(open)) { return None; } @@ -3820,9 +3820,9 @@ impl Consumer { } /// Lend `head` to the cached copies of group `sequence`; see - /// [`group::Producer::adopt_head`]. + /// [`group::Handle::adopt_head`]. pub(super) fn adopt_head(&self, sequence: u64, head: &group::Head) { - let copies: Vec = self.with_state(|state| { + let copies: Vec = self.with_state(|state| { let Some(state) = state else { return Vec::new(); }; @@ -5187,7 +5187,7 @@ impl Cursor { /// The lowest cached group still owed, consuming the spans scanned below it: only one /// the walk could have read, never fetched backfill or a withheld group. The group /// itself stays owed until [`Self::advance_arrival`] takes it, so a peek keeps it. - fn next_owed(&mut self) -> Option { + fn next_owed(&mut self) -> Option { if self.filter.owed.is_empty() { return None; } @@ -6864,7 +6864,7 @@ mod test { let mut first = producer.append_group().unwrap(); first.write_frame(None, &b"a"[..]).unwrap(); first.finish().unwrap(); - let empty = producer.append_group().unwrap(); + let mut empty = producer.append_group().unwrap(); let mut reader = producer.subscribe(replay()); let Poll::Ready(Some(edge)) = reader.poll_largest(&noop) else { @@ -6947,11 +6947,8 @@ mod test { // An older report or frame does not move it back. producer.report_largest(Position { group: 7, frame: 1 }); - producer - .create_group(group::Info { sequence: 2 }) - .unwrap() - .write_frame(None, &b"a"[..]) - .unwrap(); + let mut _open = producer.create_group(group::Info { sequence: 2 }).unwrap(); + _open.write_frame(None, &b"a"[..]).unwrap(); assert!(subscriber.largest().now_or_never().is_none()); producer.report_largest(Position { group: 8, frame: 0 }); @@ -7336,6 +7333,78 @@ mod test { assert_eq!(producer.append_group().unwrap().sequence, 6); } + /// A cached observer must not keep an unfinished writer alive or serve its dead copy. + #[moq_clock::test] + async fn dropped_group_writer_aborts_and_releases_its_cached_copy() { + let pool = cache::Pool::unbounded(); + let producer = track_producer_pooled("test", pool.clone()); + let mut group = producer.create_group(group::Info { sequence: 3 }).unwrap(); + group + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"head")) + .unwrap(); + let mut reader = group.consume(); + assert!(pool.used() > 0); + drop(group); + + assert!(matches!( + reader.poll_read_frame(&kio::Waiter::noop()), + Poll::Ready(Err(Error::Dropped)) + )); + let state = producer.state.read(); + assert!(state.lookup.get(&3).unwrap().is_aborted()); + assert_eq!(state.lookup.get(&3).unwrap().cache_size(), 0); + drop(state); + assert_eq!(pool.used(), 0); + } + + #[moq_clock::test] + async fn dropped_group_writer_is_absent_and_its_sequence_can_be_recreated() { + let producer = track_producer("test", Info::timed()); + let mut group = producer.create_group(group::Info { sequence: 3 }).unwrap(); + group + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"head")) + .unwrap(); + drop(group); + + let mut reader = producer.subscribe(Subscription::default().with_groups(0..)); + assert!(reader.poll_recv_group(&kio::Waiter::noop()).is_pending()); + let mut replacement = producer + .create_group(group::Info { sequence: 3 }) + .expect("the dead copy is replaceable"); + replacement + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"head")) + .unwrap(); + replacement.finish().unwrap(); + assert!(matches!( + reader.poll_recv_group(&kio::Waiter::noop()), + Poll::Ready(Ok(Some(_))) + )); + } + + #[moq_clock::test] + async fn dropped_group_writer_preserves_the_committed_resume_position() { + let producer = track_producer("test", Info::timed()); + let consumer = producer.consume(); + let mut group = producer.create_group(group::Info { sequence: 3 }).unwrap(); + group + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"head")) + .unwrap(); + let handle = group.handle(); + let _partial = group + .create_frame_owned( + frame::Info { + size: 2, + timestamp: Some(Timestamp::ZERO), + }, + &frame::Budget::default(), + ) + .unwrap(); + assert_eq!(handle.frame_count(), 2); + drop(_partial); + assert_eq!(handle.resume_frame(), Some(1)); + assert_eq!(consumer.resume_position(), Some(Position { group: 3, frame: 1 })); + } + /// Datagram sequence advances do not move a route takeover past an open group. #[test] fn resume_position_uses_the_latest_group() { @@ -7383,8 +7452,16 @@ mod test { .unwrap(); assert_eq!(recv_datagram(&mut datagrams).sequence, 5); - producer.create_group(group::Info { sequence: 3 }).unwrap(); - producer.create_group(group::Info { sequence: 6 }).unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 6 }) + .unwrap() + .finish() + .unwrap(); let mut next = || { subscriber @@ -7557,7 +7634,7 @@ mod test { "the newest sequence" ); - producer.append_group().unwrap(); + let _open = producer.append_group().unwrap(); assert!( matches!(fetch(sequence), Some(Err(Error::NotFetchable))), "below a newer group" @@ -7684,9 +7761,9 @@ mod test { let producer = track_producer("test", Info::timed()); // Create 3 groups at time 0. - producer.append_group().unwrap(); // seq 0 - producer.append_group().unwrap(); // seq 1 - producer.append_group().unwrap(); // seq 2 + producer.append_group().unwrap().finish().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 1 + producer.append_group().unwrap().finish().unwrap(); // seq 2 { let state = producer.state.read(); @@ -7698,7 +7775,7 @@ mod test { elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Append a new group to trigger eviction. - producer.append_group().unwrap(); // seq 3 + producer.append_group().unwrap().finish().unwrap(); // seq 3 // Groups 0, 1, 2 are expired but seq 3 (the live edge) is kept. Their arrival // entries no longer resolve, so the leading ones are trimmed and the offset @@ -7873,7 +7950,7 @@ mod test { #[test] fn coalesced_frame_completion_keeps_the_group_alive() { let producer = track_producer("test", Info::timed()); - let mut straggler = producer.create_group(0u64.into()).unwrap(); + let straggler = producer.create_group(0u64.into()).unwrap(); // The live edge moves on, so the straggler is demoted and expirable. producer.create_group(1u64.into()).unwrap().finish().unwrap(); @@ -7892,7 +7969,7 @@ mod test { // and `finish` is the only write the charge sees. elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); frame.write(bytes::Bytes::from_static(b"abc")).unwrap(); - frame.finish().unwrap(); + let mut straggler = frame.finish().unwrap(); straggler.finish().unwrap(); // A new group runs the expiry scan. @@ -7942,13 +8019,13 @@ mod test { #[test] fn evict_keeps_max_sequence() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); // seq 0 + let _open = producer.append_group().unwrap(); // seq 0 // Advance time past the LRU window. elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Append another group; seq 0 is expired and evicted. - producer.append_group().unwrap(); // seq 1 + let _open = producer.append_group().unwrap(); // seq 1 { let state = producer.state.read(); @@ -7961,9 +8038,9 @@ mod test { #[test] fn no_eviction_when_fresh() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); // seq 0 - producer.append_group().unwrap(); // seq 1 - producer.append_group().unwrap(); // seq 2 + producer.append_group().unwrap().finish().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 1 + producer.append_group().unwrap().finish().unwrap(); // seq 2 { let state = producer.state.read(); @@ -7975,12 +8052,12 @@ mod test { #[test] fn consumer_skips_evicted_groups() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 0 let mut consumer = producer.subscribe(None); elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); - producer.append_group().unwrap(); // seq 1 + producer.append_group().unwrap().finish().unwrap(); // seq 1 // Group 0 was evicted. Consumer should get group 1. let group = consumer.assert_group(); @@ -8013,7 +8090,7 @@ mod test { let producer = track_producer_pooled("test", pool.clone()); let mut stalled = producer.append_group().unwrap(); // seq 0, left open stalled.write_frame(Timestamp::ZERO, b"x".as_slice()).unwrap(); - producer.append_group().unwrap(); // seq 1, the live edge + let _open = producer.append_group().unwrap(); // seq 1, the live edge elapse(&producer, Duration::from_secs(2)); pool.sweep(); @@ -8035,7 +8112,7 @@ mod test { let producer = track_producer_pooled("test", pool.clone()); let mut group = producer.append_group().unwrap(); group.write_frame(Timestamp::ZERO, b"first".as_slice()).unwrap(); - producer.append_group().unwrap(); + let _open = producer.append_group().unwrap(); // Activity written while cleanup was idle gets the new supplied time. let later = now + Duration::from_secs(60); pool.gc(later, &kio::Waiter::noop()); @@ -8051,11 +8128,11 @@ mod test { let producer = track_producer_pooled("test", pool.clone()); let now = crate::model::clock::now(); let groups: Vec<_> = (0..EVICT_SCAN * 3).map(|_| producer.append_group().unwrap()).collect(); - producer.append_group().unwrap(); + let _open = producer.append_group().unwrap(); pool.gc(now, &kio::Waiter::noop()); // Keep more than a write scan's worth of leading entries fresh. for group in &groups[..EVICT_SCAN * 2] { - group.cache_refresh(); + group.handle().cache_refresh(); } pool.gc(now + expiry * 2, &kio::Waiter::noop()); let state = producer.state.read(); @@ -8077,11 +8154,13 @@ mod test { // Comfortably more than one write-driven scan window (EVICT_SCAN). let backlog = 4 * EVICT_SCAN; + let mut _open = Vec::new(); for _ in 0..backlog { let mut group = producer.append_group().unwrap(); group.write_frame(Timestamp::ZERO, b"x".as_slice()).unwrap(); + _open.push(group); } - producer.append_group().unwrap(); // the live edge, always protected + let _open = producer.append_group().unwrap(); // the live edge, always protected elapse(&producer, Duration::from_secs(2)); pool.sweep(); @@ -8095,11 +8174,11 @@ mod test { fn pool_expiry_controls_eviction() { // A shorter LRU window on the pool evicts sooner than the default. let producer = track_producer_expiring("test", Duration::from_secs(1)); - producer.append_group().unwrap(); // seq 0 + let _open = producer.append_group().unwrap(); // seq 0 // Past the pool's window but well within cache::DEFAULT_EXPIRY. elapse(&producer, Duration::from_secs(2)); - producer.append_group().unwrap(); // seq 1 + let _open = producer.append_group().unwrap(); // seq 1 // Seq 0 is gone because the pool only keeps idle groups for 1s. let state = producer.state.read(); @@ -8360,7 +8439,7 @@ mod test { append_at(&mut producer, 0); let mut open = Vec::new(); for sequence in 1..=RUN { - let group = producer.append_group().unwrap(); + let mut group = producer.append_group().unwrap(); match sequence % 2 { 0 => group.finish().unwrap(), _ => open.push(group), @@ -8378,10 +8457,10 @@ mod test { #[test] fn disabled_pool_expiry_never_reclaims() { let producer = track_producer_expiring("test", None); - producer.append_group().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 0 elapse(&producer, Duration::from_secs(3600)); - producer.append_group().unwrap(); // seq 1 + producer.append_group().unwrap().finish().unwrap(); // seq 1 let state = producer.state.read(); assert_eq!(live_groups(&state), 2); @@ -8466,11 +8545,11 @@ mod test { Info::timed().with_max_age(Duration::from_secs(60)), Duration::from_secs(1), ); - producer.append_group().unwrap(); // seq 0 + producer.append_group().unwrap().finish().unwrap(); // seq 0 // Far past the ceiling in wall time, but inside the pool's LRU window. elapse(&producer, Duration::from_secs(2)); - producer.append_group().unwrap(); // seq 1 + producer.append_group().unwrap().finish().unwrap(); // seq 1 let state = producer.state.read(); assert_eq!(live_groups(&state), 2); @@ -8586,7 +8665,7 @@ mod test { answer .write_frame(Timestamp::from_millis(533).unwrap(), bytes::Bytes::from_static(b"")) .unwrap(); - producer.reveal_group(&answer); + producer.reveal_group(&answer.handle()); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_millis(400))); assert_eq!(drain(&mut subscriber), vec![2]); @@ -8818,7 +8897,7 @@ mod test { fn a_stamped_successor_expires_an_unstamped_group() { let mut producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(None); - producer.append_group().unwrap(); // seq 0 stalls before its first frame + let _open = producer.append_group().unwrap(); // seq 0 stalls before its first frame append_at(&mut producer, 1000); // seq 1 proves the live feed moved on @@ -8832,7 +8911,7 @@ mod test { async fn a_handed_out_group_expires_while_its_first_frame_is_stalled() { let mut producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(None); - producer.append_group().unwrap(); + let _writer_1 = producer.append_group().unwrap(); let mut stalled = subscriber.recv_group().await.unwrap().expect("stalled group"); let pending = moq_clock::sim::spawn(async move { stalled.read_frame().await }); @@ -9225,7 +9304,7 @@ mod test { "the hidden group moves no edge" ); - producer.reveal_group(&received); + producer.reveal_group(&received.handle()); assert!(woken.load(Ordering::SeqCst), "the reveal wakes the expired read"); let result = next.as_mut().poll(&mut cx); assert!( @@ -9255,7 +9334,7 @@ mod test { group .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) .unwrap(); - producer.reveal_group(group); + producer.reveal_group(&group.handle()); } assert_eq!(subscriber.assert_group().sequence, 0); assert_eq!(subscriber.assert_group().sequence, 1); @@ -9271,8 +9350,8 @@ mod test { let mut producer = track_producer("test", None); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_secs(60))); producer.finish_at(Position::group(1)).unwrap(); - let group = producer.receive_group(group::Info { sequence: 0 }).unwrap(); - let handle = group.clone(); + let mut group = producer.receive_group(group::Info { sequence: 0 }).unwrap(); + let handle = group.handle(); let first = { let mut next = std::pin::pin!(subscriber.recv_group()); @@ -9608,7 +9687,7 @@ mod test { let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_millis(500))); append_at(&mut producer, 0); // seq 0 - producer.append_group().unwrap(); // seq 1 stalls before its first frame + let _writer_1 = producer.append_group().unwrap(); // seq 1 stalls before its first frame append_at(&mut producer, 10_000); // seq 2 append_at(&mut producer, 11_000); // seq 3 @@ -9751,7 +9830,11 @@ mod test { producer .insert_datagram(5, Timestamp::from_millis(5).unwrap(), bytes::Bytes::from_static(b"x")) .unwrap(); - producer.create_group(group::Info { sequence: 3 }).unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); let datagram = sub .recv_datagram() @@ -9830,7 +9913,7 @@ mod test { fn next_group_keeps_a_group_with_no_proven_reach() { let mut producer = track_producer("test", Info::timed()); append_at(&mut producer, 0); // seq 0 - producer.append_group().unwrap(); // seq 1 stalls before its first frame + let _writer_1 = producer.append_group().unwrap(); // seq 1 stalls before its first frame append_at(&mut producer, 10_000); // seq 2 append_at(&mut producer, 11_000); // seq 3 @@ -10393,9 +10476,9 @@ mod test { let producer = track_producer("test", Info::timed()); // Arrive out of order: seq 5 first, then 3, then 4. - producer.create_group(group::Info { sequence: 5 }).unwrap(); - producer.create_group(group::Info { sequence: 3 }).unwrap(); - producer.create_group(group::Info { sequence: 4 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 5 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 3 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 4 }).unwrap(); // max_sequence = 5, which is at the front of the VecDeque. { @@ -10407,7 +10490,7 @@ mod test { elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Append seq 6 (becomes new max_sequence). - producer.append_group().unwrap(); // seq 6 + let _open = producer.append_group().unwrap(); // seq 6 // Seq 3, 4, 5 are all expired. Seq 5 was the old max_sequence but now 6 is. // All old groups are evicted. @@ -10427,12 +10510,20 @@ mod test { let producer = track_producer("test", Info::timed()); // Arrive: seq 5, then seq 3. - producer.create_group(group::Info { sequence: 5 }).unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Seq 3 arrives late; max_sequence is still 5 (at front). - producer.create_group(group::Info { sequence: 3 }).unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); // Seq 5 is max_sequence (protected). Seq 3 is not expired (just created). // Nothing should be evicted. @@ -10446,7 +10537,11 @@ mod test { elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // Seq 2 arrives late, triggering eviction. - producer.create_group(group::Info { sequence: 2 }).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); // Seq 5 is the live edge (protected) and still resolves at the front of // `arrival`, so nothing is trimmed and the offset stays. Seq 3 expired out of @@ -10472,8 +10567,8 @@ mod test { #[cfg(feature = "async")] fn abort_drops_open_groups() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); - producer.append_group().unwrap(); + let _writer_1 = producer.append_group().unwrap(); + let _writer_2 = producer.append_group().unwrap(); let mut consumer = producer.subscribe(None); assert_eq!(live_groups(&producer.state.read()), 2); @@ -10494,7 +10589,7 @@ mod test { fn drop_unfinished_clears_cached_groups() { let producer = track_producer("test", Info::timed()); let writer = producer.clone(); - writer.append_group().unwrap(); + let _open = writer.append_group().unwrap(); // A stale consumer keeps the channel (and thus the cache) alive. let mut consumer = producer.subscribe(None); @@ -10516,7 +10611,7 @@ mod test { let producer = track_producer("test", Info::timed()); let keep = producer.clone(); let writer = producer.clone(); - let group = writer.append_group().unwrap(); + let mut group = writer.append_group().unwrap(); group.finish().unwrap(); let _consumer = producer.subscribe(None); writer.abort(Error::Cancel).unwrap(); @@ -10530,7 +10625,7 @@ mod test { let warns = count_drop_warnings("track::Producer dropped without finish", || { let producer = track_producer("test", Info::timed()); let writer = producer.clone(); - writer.append_group().unwrap(); + let _open = writer.append_group().unwrap(); let _consumer = producer.subscribe(None); drop(writer); drop(producer); @@ -10542,7 +10637,7 @@ mod test { #[cfg(feature = "async")] fn drop_finished_keeps_cached_groups() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); + producer.append_group().unwrap().finish().unwrap(); producer.finish().unwrap(); let mut consumer = producer.subscribe(None); @@ -10561,7 +10656,7 @@ mod test { #[cfg(feature = "async")] fn drop_short_of_the_boundary_ends_cleanly() { let mut producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); + producer.append_group().unwrap().finish().unwrap(); producer.finish_at(Position::group(3)).unwrap(); let mut consumer = producer.subscribe(None); @@ -10585,8 +10680,16 @@ mod test { #[cfg(feature = "async")] fn ordered_ends_cleanly_when_sealed_short_of_the_boundary() { let mut producer = track_producer("test", Info::timed()); - producer.create_group(group::Info { sequence: 0 }).unwrap(); - producer.create_group(group::Info { sequence: 2 }).unwrap(); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); producer.finish_at(Position::group(4)).unwrap(); let mut ordered = producer.subscribe(replay()).ordered(); @@ -10614,7 +10717,7 @@ mod test { fn finish_after_groups() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); + let _open = producer.append_group().unwrap(); assert!(producer.finish().is_ok()); assert!(producer.finish().is_err()); assert!(producer.append_group().is_err()); @@ -10623,7 +10726,7 @@ mod test { #[test] fn finish_at_rejects_a_boundary_at_or_below_the_live_edge() { let mut producer = track_producer("test", Info::timed()); - producer.create_group(group::Info { sequence: 5 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 5 }).unwrap(); // The boundary is exclusive, so it must be strictly above the highest produced // group. 5 or below would orphan groups that already exist. @@ -10745,7 +10848,7 @@ mod test { let mut producer = track_producer("test", Info::timed()); assert_eq!(producer.end(), None); - producer.create_group(group::Info { sequence: 5 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 5 }).unwrap(); assert_eq!(producer.end(), None, "a group does not declare an end"); producer.finish_at(Position::group(9)).unwrap(); @@ -10758,7 +10861,7 @@ mod test { #[test] fn end_reports_the_live_edge_after_finish() { let producer = track_producer("test", Info::timed()); - producer.create_group(group::Info { sequence: 5 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 5 }).unwrap(); producer.finish().unwrap(); assert_eq!(producer.end(), Some(Position::group(6))); } @@ -10767,7 +10870,11 @@ mod test { #[cfg(feature = "async")] fn finish_at_declares_a_future_boundary() { let mut producer = track_producer("test", Info::timed()); - producer.create_group(group::Info { sequence: 5 }).unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); // Learn the track ends at group 6 (exclusive 7) while the live edge is still 5. producer.finish_at(Position::group(7)).unwrap(); @@ -10789,7 +10896,11 @@ mod test { ); // The trailing group arrives (below the boundary), then the track completes. - producer.create_group(group::Info { sequence: 6 }).unwrap(); + producer + .create_group(group::Info { sequence: 6 }) + .unwrap() + .finish() + .unwrap(); assert_eq!(consumer.assert_group().sequence, 6); let done = consumer .recv_group() @@ -10904,7 +11015,7 @@ mod test { let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); producer.finish_at_pending(Position::group(2)).unwrap(); - let high = producer.create_group(group::Info { sequence: 1 }).unwrap(); + let mut high = producer.create_group(group::Info { sequence: 1 }).unwrap(); high.finish().unwrap(); assert_eq!(arrival.assert_group().sequence, 1); assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); @@ -11035,8 +11146,9 @@ mod test { ); assert_eq!(producer.end(), Some(Position::group(3)), "the first end stands"); + let mut _low = Vec::new(); for sequence in [0, 1] { - let _low = producer.create_group(group::Info { sequence }).unwrap(); + _low.push(producer.create_group(group::Info { sequence }).unwrap()); assert_eq!(arrival.assert_group().sequence, sequence); } assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); @@ -11050,7 +11162,7 @@ mod test { let mut producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()); - let head = producer.create_group(group::Info { sequence: 0 }).unwrap(); + let mut head = producer.create_group(group::Info { sequence: 0 }).unwrap(); head.finish().unwrap(); let _tail = producer.create_group(group::Info { sequence: 1 }).unwrap(); producer.finish_at(Position::group(2)).unwrap(); @@ -11205,7 +11317,7 @@ mod test { let mut consumer = producer.subscribe(replay()); for sequence in 0..2 { - let group = producer.create_group(group::Info { sequence }).unwrap(); + let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.finish().unwrap(); } producer.finish_at(Position::group(2)).unwrap(); @@ -11226,7 +11338,7 @@ mod test { let mut consumer = producer.subscribe(replay()).ordered(); for sequence in 0..2 { - let group = producer.create_group(group::Info { sequence }).unwrap(); + let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.finish().unwrap(); } producer.finish_at(Position::group(2)).unwrap(); @@ -11300,7 +11412,11 @@ mod test { #[cfg(feature = "async")] fn recv_group_finishes_without_waiting_for_gaps() { let producer = track_producer("test", Info::timed()); - producer.create_group(group::Info { sequence: 1 }).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); producer.finish().unwrap(); let mut consumer = producer.subscribe(None); @@ -11321,7 +11437,11 @@ mod test { let mut consumer = producer.subscribe(None).ordered(); // Seq 5 arrives first. - producer.create_group(group::Info { sequence: 5 }).unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); let group = consumer .next_group() .now_or_never() @@ -11331,11 +11451,23 @@ mod test { assert_eq!(group.sequence, 5); // Seq 3 arrives late, skipped because 3 <= 5. - producer.create_group(group::Info { sequence: 3 }).unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); // Seq 4 arrives late and is also skipped. - producer.create_group(group::Info { sequence: 4 }).unwrap(); + producer + .create_group(group::Info { sequence: 4 }) + .unwrap() + .finish() + .unwrap(); // Seq 7 arrives and is returned. - producer.create_group(group::Info { sequence: 7 }).unwrap(); + producer + .create_group(group::Info { sequence: 7 }) + .unwrap() + .finish() + .unwrap(); let group = consumer .next_group() @@ -11359,8 +11491,16 @@ mod test { let mut consumer = producer.subscribe(replay()).ordered(); // Seq 3 arrives first, then seq 5. Both should be returned in arrival order. - producer.create_group(group::Info { sequence: 3 }).unwrap(); - producer.create_group(group::Info { sequence: 5 }).unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); let group = consumer .next_group() @@ -11516,8 +11656,16 @@ mod test { let mut arrival = producer.subscribe(replay()); // Out-of-order arrivals: seq 5 first, then seq 3. - producer.create_group(group::Info { sequence: 5 }).unwrap(); - producer.create_group(group::Info { sequence: 3 }).unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); // The ordered handle returns the smallest sequence first, regardless of // arrival order. @@ -11540,7 +11688,11 @@ mod test { let mut consumer = producer.subscribe(replay()).ordered(); for s in 0..6 { - producer.create_group(group::Info { sequence: s }).unwrap(); + producer + .create_group(group::Info { sequence: s }) + .unwrap() + .finish() + .unwrap(); } consumer.set_groups(..3); @@ -11573,7 +11725,11 @@ mod test { let mut consumer = producer.subscribe(replay()).ordered(); for s in 0..6 { - producer.create_group(group::Info { sequence: s }).unwrap(); + producer + .create_group(group::Info { sequence: s }) + .unwrap() + .finish() + .unwrap(); } consumer.set_groups(..2); @@ -11619,7 +11775,11 @@ mod test { let mut consumer = producer.subscribe(replay()).ordered(); for s in 0..3 { - producer.create_group(group::Info { sequence: s }).unwrap(); + producer + .create_group(group::Info { sequence: s }) + .unwrap() + .finish() + .unwrap(); } // Drain everything with no cap. @@ -11638,8 +11798,16 @@ mod test { // Lower the cap below the cursor. New groups beyond the cap are blocked. consumer.set_groups(..2); - producer.create_group(group::Info { sequence: 3 }).unwrap(); - producer.create_group(group::Info { sequence: 4 }).unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 4 }) + .unwrap() + .finish() + .unwrap(); assert!( consumer.next_group().now_or_never().is_none(), "cap is below cursor; nothing returnable until cap rises" @@ -11666,12 +11834,32 @@ mod test { consumer.set_groups(..6); // Out-of-order arrivals all within the cap. - producer.create_group(group::Info { sequence: 2 }).unwrap(); - producer.create_group(group::Info { sequence: 5 }).unwrap(); - producer.create_group(group::Info { sequence: 3 }).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 5 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); // One beyond the cap; should be held even though it arrived in the middle. - producer.create_group(group::Info { sequence: 8 }).unwrap(); - producer.create_group(group::Info { sequence: 4 }).unwrap(); + producer + .create_group(group::Info { sequence: 8 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 4 }) + .unwrap() + .finish() + .unwrap(); // next_group walks in sequence order through everything <= cap. assert_eq!( @@ -11711,7 +11899,11 @@ mod test { let mut consumer = producer.subscribe(replay()); for s in 0..3 { - producer.create_group(group::Info { sequence: s }).unwrap(); + producer + .create_group(group::Info { sequence: s }) + .unwrap() + .finish() + .unwrap(); } consumer.set_groups(..2); @@ -11732,7 +11924,7 @@ mod test { ); consumer.set_groups(..3); - producer.create_group(group::Info { sequence: 3 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 3 }).unwrap(); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 3"); producer.finish().unwrap(); assert!( @@ -11752,9 +11944,21 @@ mod test { consumer.set_groups(..2); // Reordered burst: the beyond-cap group arrives first. - producer.create_group(group::Info { sequence: 2 }).unwrap(); - producer.create_group(group::Info { sequence: 0 }).unwrap(); - producer.create_group(group::Info { sequence: 1 }).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, @@ -11779,15 +11983,35 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(None); consumer.set_groups(2..=2); - producer.create_group(group::Info { sequence: 2 }).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 2); consumer.set_groups(..4); - producer.create_group(group::Info { sequence: 1 }).unwrap(); - producer.create_group(group::Info { sequence: 3 }).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 3); consumer.set_groups(0..=4); - producer.create_group(group::Info { sequence: 0 }).unwrap(); - producer.create_group(group::Info { sequence: 4 }).unwrap(); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 4 }) + .unwrap() + .finish() + .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 4); } @@ -11800,7 +12024,11 @@ mod test { let mut consumer = producer.subscribe(None); consumer.set_groups(..1); - producer.create_group(group::Info { sequence: 1 }).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); assert!( consumer.recv_group().now_or_never().is_none(), "group 1 parked at the cap" @@ -11808,7 +12036,11 @@ mod test { consumer.start_at(2); consumer.set_groups(..); - producer.create_group(group::Info { sequence: 2 }).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2, @@ -11825,7 +12057,11 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(None); - producer.create_group(group::Info { sequence: 0 }).unwrap(); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -11855,8 +12091,16 @@ mod test { fn end_at_zero_is_the_empty_range() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()); - producer.create_group(group::Info { sequence: 0 }).unwrap(); - producer.create_group(group::Info { sequence: 1 }).unwrap(); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); consumer.set_groups(..0); assert!( @@ -11883,7 +12127,11 @@ mod test { empty.set_groups((Bound::Unbounded, Position::group(0).group_end())); for s in 0..3 { - producer.create_group(group::Info { sequence: s }).unwrap(); + producer + .create_group(group::Info { sequence: s }) + .unwrap() + .finish() + .unwrap(); } assert_eq!( @@ -11960,8 +12208,16 @@ mod test { let mut consumer = producer.subscribe(replay()).ordered(); consumer.set_groups(..=u64::MAX); - producer.create_group(group::Info { sequence: 0 }).unwrap(); - producer.create_group(group::Info { sequence: u64::MAX }).unwrap(); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + producer + .create_group(group::Info { sequence: u64::MAX }) + .unwrap() + .finish() + .unwrap(); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, @@ -12555,7 +12811,7 @@ mod test { live.abort(Error::Cancel).unwrap(); // The next group demotes 0 into the eviction order and runs an expiry scan. - producer.create_group(group::Info { sequence: 1 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 1 }).unwrap(); let mut group = producer.consume().peek_group(0).expect("the head still serves group 0"); assert_eq!( @@ -12570,14 +12826,14 @@ mod test { #[cfg(feature = "async")] async fn reading_the_head_keeps_the_slot_from_expiring() { let producer = track_producer("test", Info::timed()); - let (live, _head) = live_group_with_head(&producer).await; + let (mut live, _head) = live_group_with_head(&producer).await; live.finish().unwrap(); - producer.create_group(group::Info { sequence: 1 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 1 }).unwrap(); elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); // A fetch hit on the head, past the window the live copy was last written in. producer.consume().fetch_group(0, None).await.unwrap(); - producer.create_group(group::Info { sequence: 2 }).unwrap(); + let _open = producer.create_group(group::Info { sequence: 2 }).unwrap(); assert!(producer.consume().peek_group(0).is_some(), "a read head keeps its slot"); } @@ -12812,7 +13068,7 @@ mod test { // A track with no `Dynamic` can't serve old content, so a cache miss // resolves to NotFound instead of blocking forever. let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); // seq 0, but we miss on seq 5 + let _open = producer.append_group().unwrap(); // seq 0, but we miss on seq 5 let consumer = producer.consume(); assert!(matches!(consumer.fetch_group(5, None).await, Err(Error::NotFound))); } @@ -12821,7 +13077,7 @@ mod test { #[cfg(feature = "async")] async fn fetch_past_final_not_found() { let producer = track_producer("test", Info::timed()); - producer.append_group().unwrap(); // seq 0 + let _open = producer.append_group().unwrap(); // seq 0 producer.finish().unwrap(); // final_sequence = 1 // A group at or past the final sequence can never exist, even with a handler, @@ -13395,7 +13651,7 @@ mod test { fn aborted_group_leaves_no_ghost_sample() { let (producer, pool) = pooled_producer(1 << 40); let group0 = producer.append_group().unwrap(); - producer.append_group().unwrap(); // demotes seq 0 into the mean + let _open = producer.append_group().unwrap(); // demotes seq 0 into the mean assert!(pool.average().is_some(), "demoted group is sampled"); group0.abort(Error::Cancel).unwrap(); @@ -13408,7 +13664,7 @@ mod test { fn empty_groups_repay_overhead() { let (producer, pool) = pooled_producer(1_000); for _ in 0..100 { - let group = producer.append_group().unwrap(); + let mut group = producer.append_group().unwrap(); group.finish().unwrap(); } @@ -13679,7 +13935,7 @@ mod test { withheld .write_frame(Timestamp::from_millis(3).unwrap(), bytes::Bytes::from_static(b"x")) .unwrap(); - producer.reveal_group(&withheld); + producer.reveal_group(&withheld.handle()); assert_eq!(subscriber.assert_group().sequence, 3, "shown once revealed"); subscriber.assert_no_group(); @@ -13767,13 +14023,14 @@ mod test { assert!(pool.used() < used, "its bytes are released"); } - /// Append a group of a 3 byte first frame and a `delta` byte delta. + /// Append a finished group of a 3 byte first frame and a `delta` byte delta. fn refresh_group(producer: &Producer, delta: usize) { let mut group = producer.append_group().unwrap(); group.write_frame(None, &b"key"[..]).unwrap(); if delta > 0 { group.write_frame(None, vec![0u8; delta]).unwrap(); } + group.finish().unwrap(); } /// Poll `demand` for a change without waiting. @@ -13893,7 +14150,7 @@ mod test { fn a_replacement_wants_past_its_predecessor() { let broadcast = broadcast::Info::default().produce(); let first = broadcast.create_track("test", Info::default()).unwrap(); - first.create_group(group::Info { sequence: 7 }).unwrap(); + let _open = first.create_group(group::Info { sequence: 7 }).unwrap(); first.finish().unwrap(); drop(first); @@ -13902,7 +14159,7 @@ mod test { assert_eq!(wanted_changed(&mut demand), Some(None)); let _subscriber = second.subscribe(None); assert_eq!(wanted_changed(&mut demand), Some(Some(8))); - second.create_group(group::Info { sequence: 8 }).unwrap(); + let _open = second.create_group(group::Info { sequence: 8 }).unwrap(); assert_eq!(wanted_changed(&mut demand), None); } @@ -13994,7 +14251,7 @@ mod test { (true, Some(Error::Dropped)) | (false, Some(Error::NotFound)) )); drop(fetch); - if let Some(group) = group { + if let Some(mut group) = group { group.finish().unwrap(); } } @@ -14011,7 +14268,7 @@ mod test { panic!("the fetch request is ready"); }; let demand = request.demand(); - let group = request.accept(Info::timed()).unwrap(); + let mut group = request.accept(Info::timed()).unwrap(); assert!(!demand.is_used()); assert!(matches!(demand.poll_used(&waiter), Poll::Ready(Err(Error::Dropped)))); @@ -14493,7 +14750,7 @@ mod test { let refused = group.write_frame(Timestamp::from_millis(500).unwrap(), &b"x"[..]); assert!(matches!(refused, Err(Error::TimestampMismatch)), "{refused:?}"); assert_eq!(group.frame_count(), 0); - assert_eq!(group.timestamp(), None); + assert_eq!(group.handle().timestamp(), None); // An equal start is a keyframe at the previous group's start. group @@ -14516,17 +14773,17 @@ mod test { #[test] fn a_rewind_is_refused_whichever_group_lands_first() { let producer = track_producer("test", Info::timed()); - start_at_millis(&producer, 5, 1000).unwrap(); + start_at_millis(&producer, 5, 1000).unwrap().finish().unwrap(); assert!(matches!( start_at_millis(&producer, 3, 2000), Err(Error::TimestampMismatch) )); - start_at_millis(&producer, 3, 500).unwrap(); + start_at_millis(&producer, 3, 500).unwrap().finish().unwrap(); assert!(matches!( start_at_millis(&producer, 4, 400), Err(Error::TimestampMismatch) )); - start_at_millis(&producer, 4, 1000).unwrap(); + start_at_millis(&producer, 4, 1000).unwrap().finish().unwrap(); } /// The batched and streamed writes check frame 0 the same way, before writing anything. @@ -14567,8 +14824,8 @@ mod test { #[test] fn an_evicted_predecessor_still_bounds_a_delayed_stamp() { let producer = track_producer("test", Info::timed()); - start_at_millis(&producer, 0, 0).unwrap(); - start_at_millis(&producer, 1, 1000).unwrap(); + start_at_millis(&producer, 0, 0).unwrap().finish().unwrap(); + start_at_millis(&producer, 1, 1000).unwrap().finish().unwrap(); let mut delayed = producer.create_group(group::Info { sequence: 2 }).unwrap(); evict(&producer, 1); @@ -14586,7 +14843,7 @@ mod test { fn a_late_group_below_the_watermark_is_unverified() { let producer = track_producer("test", Info::timed()); for (sequence, millis) in [(0, 1000), (1, 2000), (2, 3000), (3, 4000)] { - start_at_millis(&producer, sequence, millis).unwrap(); + start_at_millis(&producer, sequence, millis).unwrap().finish().unwrap(); } evict(&producer, 1); evict(&producer, 2); @@ -14599,11 +14856,11 @@ mod test { )); } let late = start_at_millis(&producer, 1, 2900).unwrap(); - assert_eq!(late.bound(), None, "a late group bounds nothing"); - assert_eq!(late.timestamp(), None, "nor drives media-time expiry"); + assert_eq!(late.handle().bound(), None, "a late group bounds nothing"); + assert_eq!(late.handle().timestamp(), None, "nor drives media-time expiry"); // Group 2 really started before late group 1 claimed to. - start_at_millis(&producer, 2, 2500).unwrap(); + start_at_millis(&producer, 2, 2500).unwrap().finish().unwrap(); } /// Subscribers may have seen an aborted group's start, so a replacement at its sequence @@ -14616,12 +14873,12 @@ mod test { .abort(Error::Cancel) .unwrap(); let replacement = start_at_millis(&producer, 0, 500).unwrap(); - assert_eq!(replacement.bound(), None, "a late replacement bounds nothing"); + assert_eq!(replacement.handle().bound(), None, "a late replacement bounds nothing"); assert!(matches!( start_at_millis(&producer, 1, 600), Err(Error::TimestampMismatch) )); - start_at_millis(&producer, 1, 1000).unwrap(); + start_at_millis(&producer, 1, 1000).unwrap().finish().unwrap(); } /// A group received from past its first frame stamps a later frame, which may overlap @@ -14629,13 +14886,13 @@ mod test { #[test] fn a_resumed_partial_group_is_neither_checked_nor_a_bound() { let producer = track_producer("test", Info::timed()); - start_at_millis(&producer, 0, 1000).unwrap(); + start_at_millis(&producer, 0, 1000).unwrap().finish().unwrap(); let mut partial = producer.create_group(group::Info { sequence: 1 }).unwrap(); partial.start_at(3).unwrap(); partial .write_frame(Timestamp::from_millis(2100).unwrap(), &b"x"[..]) .unwrap(); - start_at_millis(&producer, 2, 2000).unwrap(); + start_at_millis(&producer, 2, 2000).unwrap().finish().unwrap(); } /// An untimed track has no timeline, so its groups land in any order. @@ -14704,7 +14961,11 @@ mod test { let _wide = producer.subscribe(replay()); let mut narrow = producer.subscribe(replay().with_groups(0..2)); for sequence in 0..1000 { - producer.create_group(group::Info { sequence }).unwrap(); + producer + .create_group(group::Info { sequence }) + .unwrap() + .finish() + .unwrap(); } assert_eq!(drain(&mut narrow), vec![0, 1]); let Inner::Plain(cursor) = &narrow.inner else { diff --git a/rs/moq-net/src/recv.rs b/rs/moq-net/src/recv.rs index 3546b4dca93..28331f4cb9b 100644 --- a/rs/moq-net/src/recv.rs +++ b/rs/moq-net/src/recv.rs @@ -5,32 +5,69 @@ use std::ops::{Deref, DerefMut}; -use crate::{Error, group}; +use crate::{Error, frame, group}; /// A received group that aborts if its handler is cancelled before finishing or handing it off. -pub(crate) struct Group(Option); +pub(crate) struct Group { + writer: Option, + pub sequence: u64, + handle: group::Handle, + armed: bool, +} impl Group { + /// Observe a group while its writer belongs to an in-flight frame. + pub fn handle(&self) -> &group::Handle { + &self.handle + } + + /// Move the writer and cancellation cleanup into its next frame. + pub fn create_frame_owned( + &mut self, + frame: impl Into, + budget: &frame::Budget, + ) -> Result { + self.writer + .take() + .expect("group writer is available between frames") + .create_frame_owned(frame, budget) + .map(frame::ProducerOwned::cancel_on_drop) + } + + /// Restore the writer returned by a completed frame. + pub fn restore(&mut self, writer: group::Producer) { + debug_assert!(self.writer.is_none()); + self.writer = Some(writer); + } + /// Own a group for the lifetime of its receive handler. pub fn new(producer: group::Producer) -> Self { - Self(Some(producer)) + Self { + sequence: producer.sequence, + handle: producer.handle(), + writer: Some(producer), + armed: true, + } } /// Hand ownership to the next receive stage without closing the group. pub fn into_inner(mut self) -> group::Producer { - self.0.take().expect("group owned until consumed") + self.armed = false; + self.writer.take().expect("group owned until consumed") } /// Finish receiving without running cancellation cleanup. pub fn finish(mut self) -> Result<(), Error> { self.deref_mut().finish()?; - self.0.take(); + self.writer.take(); + self.armed = false; Ok(()) } /// Abort with the receive error instead of cancellation. - pub fn abort(self, err: Error) -> Result<(), Error> { - self.into_inner().abort(err) + pub fn abort(mut self, err: Error) -> Result<(), Error> { + self.armed = false; + self.handle.abort(err) } } @@ -38,20 +75,68 @@ impl Deref for Group { type Target = group::Producer; fn deref(&self) -> &Self::Target { - self.0.as_ref().expect("group owned until consumed") + self.writer.as_ref().expect("group owned until consumed") } } impl DerefMut for Group { fn deref_mut(&mut self) -> &mut Self::Target { - self.0.as_mut().expect("group owned until consumed") + self.writer.as_mut().expect("group owned until consumed") } } impl Drop for Group { fn drop(&mut self) { - if let Some(producer) = self.0.take() { - let _ = producer.abort(Error::Cancel); + if self.armed { + let _ = self.handle.abort(Error::Cancel); } } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn receive_frame_cancellation_keeps_a_terminal() { + let producer = group::Info { sequence: 0 }.produce(); + let mut consumer = producer.consume(); + let mut receiving = Group::new(producer); + let frame = receiving + .create_frame_owned( + crate::frame::Info { + size: 2, + timestamp: Some(crate::Timestamp::ZERO), + }, + &crate::frame::Budget::default(), + ) + .unwrap(); + drop(frame); + drop(receiving); + assert!(matches!( + consumer.poll_read_frame(&kio::Waiter::noop()), + std::task::Poll::Ready(Err(Error::Cancel)) + )); + } + #[test] + fn receive_frame_cancellation_preserves_an_explicit_abort() { + let producer = group::Info { sequence: 0 }.produce(); + let mut consumer = producer.consume(); + let mut receiving = Group::new(producer); + let frame = receiving + .create_frame_owned( + crate::frame::Info { + size: 2, + timestamp: Some(crate::Timestamp::ZERO), + }, + &crate::frame::Budget::default(), + ) + .unwrap(); + receiving.abort(Error::App(42)).unwrap(); + drop(frame); + assert!(matches!( + consumer.poll_read_frame(&kio::Waiter::noop()), + std::task::Poll::Ready(Err(Error::App(42))) + )); + } +} diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index 6c948b0e584..5623ac5b4f6 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -100,7 +100,7 @@ fn back_to_back_groups_arrive_in_order() { let publisher = thread::spawn(move || { for _ in 0..2 { - let group = track.append_group().expect("append group"); + let mut group = track.append_group().expect("append group"); group.finish().expect("finish group"); } track.finish().expect("finish track"); @@ -555,8 +555,8 @@ fn an_aborted_parked_group_releases_a_finished_track() { model(|| { let broadcast = broadcast::Info::new().produce(); let track = broadcast.create_track("parked", timed()).unwrap(); - let group = track.append_group().unwrap(); - group.clone().finish().unwrap(); + let mut group = track.append_group().unwrap(); + group.finish().unwrap(); let mut subscriber = track.subscribe(moq_net::track::Subscription::default().with_groups(0..)); subscriber.set_groups(..0); track.finish().unwrap(); @@ -565,36 +565,3 @@ fn an_aborted_parked_group_releases_a_finished_track() { aborting.join().unwrap(); }); } - -/// A frame written on one group handle racing `finish` on another must never reopen -/// the finished largest group, or a reader at the declared end waits forever. -#[test] -fn a_frame_racing_finish_never_reopens_the_largest() { - model(|| { - let broadcast = broadcast::Info::new().produce(); - let mut track = broadcast - .create_track("largest", moq_net::track::Info::default()) - .unwrap(); - let mut group = track.append_group().unwrap(); - group.write_frame(None, Bytes::from_static(b"a")).unwrap(); - track.finish().unwrap(); - - let finishing = group.clone(); - let writer = thread::spawn(move || { - // Refused once the finish wins; either order must end the stream. - let _ = group.write_frame(None, Bytes::from_static(b"b")); - group - }); - finishing.finish().unwrap(); - let _group = writer.join().unwrap(); - - let noop = kio::Waiter::noop(); - loop { - match track.poll_largest(&noop) { - std::task::Poll::Ready(Some(_)) => continue, - std::task::Poll::Ready(None) => break, - std::task::Poll::Pending => panic!("a stale frame write reopened the finished largest group"), - } - } - }); -} diff --git a/rs/moq-relay/tests/integration/connection.rs b/rs/moq-relay/tests/integration/connection.rs index 6112e6c18ce..9dff056a5d4 100644 --- a/rs/moq-relay/tests/integration/connection.rs +++ b/rs/moq-relay/tests/integration/connection.rs @@ -80,11 +80,11 @@ fn publish( broadcast.announce(Default::default()).expect("announce"); let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); let track = broadcast.create_track("video", info).expect("create track"); - track - .append_group() - .expect("append group") + let mut group = track.append_group().expect("append group"); + group .write_frame(moq_net::Timestamp::ZERO, name.as_bytes()) .expect("write frame"); + group.finish().expect("finish group"); (origin, broadcast, track) } diff --git a/rs/moq-relay/tests/integration/smoke.rs b/rs/moq-relay/tests/integration/smoke.rs index 1a7eafd49d7..5b7be611e53 100644 --- a/rs/moq-relay/tests/integration/smoke.rs +++ b/rs/moq-relay/tests/integration/smoke.rs @@ -295,11 +295,11 @@ async fn hidden_broadcasts_need_a_lite07_opt_in() { let hidden = pub_origin.create_broadcast(".x/y").expect("create hidden"); hidden.announce(Default::default()).expect("announce hidden"); let track = hidden.create_track("video", timed()).expect("create track"); - track - .append_group() - .expect("append group") + let mut group = track.append_group().expect("append group"); + group .write_frame(moq_net::Timestamp::ZERO, b"hidden".as_ref()) .expect("write frame"); + group.finish().expect("finish group"); // The relay's announce request carries the opt-in only on lite-07, so the publisher // must speak it too for the hidden route to reach the relay. let (_pub_client, pub_connection) = tokio::time::timeout( diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index d98dd4fce38..a5f9ba10a52 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -497,7 +497,7 @@ impl Snapshot { return Err(err.into()); } if frame.keyframe { - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } self.group = Some(self.track.create_group(moq_net::group::Info { @@ -517,7 +517,7 @@ impl Snapshot { } fn finish(&mut self) -> moq_json::Result<()> { - if let Some(group) = self.group.take() { + if let Some(mut group) = self.group.take() { group.finish()?; } Ok(self.track.finish()?)