Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions quest/m1/public-model/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,7 @@ 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
Expand Down
118 changes: 118 additions & 0 deletions quest/m1/public-model/group-writer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# [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<Target = Info>`. 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.
12 changes: 12 additions & 0 deletions quest/m1/public-model/ingest.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,14 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1:
crate-internal duplicates. `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
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
that before landing it.
- Compile probe at dd95d5804: 26 `group::Producer` clone sites, 16
model-internal and 7 in the sessions (kept by the crate-private
duplicate), and 3 outside the crate (2 in
Expand Down Expand Up @@ -189,6 +197,10 @@ 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

## Related

- [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - the fetch ingest, `mirror`, and `endTrack` items split out of this quest