From ee9972c2b8412e31e548101507c34ab5aef0753b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:38:08 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m1/explicit-state/boy-pause.md Quest-Claim: eab6d0999bbb3abf From 50c564f3ce5e9d3d56ae13fa8d8e227eb9f6d81e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:40:48 -0800 Subject: [PATCH 2/6] fix(moq-boy): pause state is one demand value under the emulator's lock Video/audio demand lives in the condvar's mutex; paused is derived from it. Monitors update it under the lock before notifying, so a subscribe can no longer be lost between the emulator's check and wait. The separate pause monitor (which could pause while video was wanted again) is gone. Co-Authored-By: Claude Opus 5.5 --- quest/m1/explicit-state/README.md | 1 - quest/m1/explicit-state/boy-pause.md | 34 ----- rs/moq-boy/src/main.rs | 183 +++++++++++++++++---------- 3 files changed, 114 insertions(+), 104 deletions(-) delete mode 100644 quest/m1/explicit-state/boy-pause.md diff --git a/quest/m1/explicit-state/README.md b/quest/m1/explicit-state/README.md index 2850e41ae87..7b30d0f282c 100644 --- a/quest/m1/explicit-state/README.md +++ b/quest/m1/explicit-state/README.md @@ -69,7 +69,6 @@ which collapses that state and waits on [Drop set](/quest/m1/drop-set.md). ## Required - [Review and agent rule](/quest/m1/explicit-state/rule.md) - REVIEW.md and AGENTS.md ask for one enum per lifecycle, terminal transitions after fallible work, and one lock per value -- [moq-boy pause state](/quest/m1/explicit-state/boy-pause.md) - a new viewer always wakes a paused emulator - [Transport close](/quest/m1/explicit-state/transport-close.md) - connection status ends with its error, and every Rust QUIC backend agrees when a connection is closed - [Video codec drains](/quest/m1/explicit-state/video-drain.md) - a hardware codec whose drain fails is ready for input again or terminally failed, never left stuck - [Watch playback phases](/quest/m1/explicit-state/watch-playback.md) - watch counts a stall only while a rendition plays diff --git a/quest/m1/explicit-state/boy-pause.md b/quest/m1/explicit-state/boy-pause.md deleted file mode 100644 index dddc2fdb132..00000000000 --- a/quest/m1/explicit-state/boy-pause.md +++ /dev/null @@ -1,34 +0,0 @@ -# [XS] moq-boy pause state - -## Goal - -A viewer who subscribes to a paused moq-boy session always wakes the -emulator. No interleaving of the pause monitors and the emulator thread -leaves it asleep while a track is wanted. Pause state is one value derived -from which tracks are wanted, written only under the lock the emulator -waits on. - -## Plan - -The shared decisions are in the [epic](/quest/m1/explicit-state/README.md). - -The bug (`rs/moq-boy/src/main.rs`, `Session`): - -- `video_active`, `audio_active`, and `paused` are separate atomics beside a - `(Mutex<()>, Condvar)`. -- `run_track_monitor` and `run_pause_monitor` store `paused = false` and call - `notify_all()` without taking the mutex, while `wait_for_resume` checks - `paused` under the mutex and then waits. -- A notify that lands between that check and `cvar.wait` is lost, so the - emulator sleeps with `paused == false` until the next subscription change. -- Separately, `run_pause_monitor`'s `tokio::join!` of both "unwanted" waits - doesn't re-check a side once it resolves, so it can store `paused = true` - while video is wanted again. - -Recommended shape: the condvar's own mutex holds the demand -(`{ video: bool, audio: bool }`), and paused means neither is wanted. Each -monitor changes the demand under the lock and then notifies. That also lets -the two monitors collapse into one. - -[moq-dev/moq#8115](https://github.com/moq-dev/moq/pull/8115) (socket roles) -also edits this file. Expect a merge conflict, not an overlap. diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index 157553d1e91..ea9b169e0c0 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -13,10 +13,9 @@ //! //! Pause/resume state machine: //! ```text -//! video_active ─┐ -//! ├─ both false → paused (emulation stops, condvar blocks) -//! audio_active ─┘ -//! either true → resumed (condvar notified) +//! Demand { video, audio } under the condvar's mutex +//! both false → paused (emulation stops, condvar blocks) +//! either true → resumed (condvar notified) //! //! On resume → force video keyframe, reanchor audio //! ``` @@ -29,7 +28,6 @@ use bytes::Bytes; use kio::clock::Instant; use std::collections::HashMap; use std::path::PathBuf; -use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::{Arc, Condvar, Mutex}; use std::time::Duration; @@ -151,19 +149,64 @@ struct Session { video_track: moq_net::track::Demand, audio_track: moq_net::track::Demand, - /// Whether anyone is subscribed to the video/audio tracks. - video_active: AtomicBool, - audio_active: AtomicBool, - - /// True when no viewers are watching (both tracks unused). - paused: AtomicBool, - /// Condvar to wake the emulator thread on resume. - resume: (Mutex<()>, Condvar), + /// Which tracks viewers want, guarded by the mutex the emulator waits on. + pause: Pause, /// Location label for status reporting. location: Option, } +/// Which tracks some viewer wants. Paused means neither is. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +struct Wanted { + video: bool, + audio: bool, + /// A track's demand ended (shutdown): never block the emulator again. + closed: bool, +} + +impl Wanted { + fn paused(&self) -> bool { + !(self.video || self.audio || self.closed) + } +} + +/// The demand, guarded by the mutex the emulator waits on. +#[derive(Default)] +struct Pause { + wanted: Mutex, + cvar: Condvar, +} + +impl Pause { + /// Change the demand under the lock, then wake the emulator. + fn update(&self, f: impl FnOnce(&mut Wanted)) { + f(&mut self.wanted.lock().unwrap()); + self.cvar.notify_all(); + } + + /// Current demand, read under the lock. + fn get(&self) -> Wanted { + *self.wanted.lock().unwrap() + } + + /// Block until some track is wanted (or demand closed). + fn wait(&self) { + drop( + self.cvar + .wait_while(self.wanted.lock().unwrap(), |d| d.paused()) + .unwrap(), + ); + } +} + +/// Which track a monitor updates. +#[derive(Clone, Copy, Debug)] +enum Kind { + Video, + Audio, +} + /// Wait until some viewer wants the track, or none does. async fn until_wanted(demand: &moq_net::track::Demand, wanted: bool) -> moq_net::Result<()> { let mut demand = demand.clone(); @@ -172,54 +215,33 @@ async fn until_wanted(demand: &moq_net::track::Demand, wanted: bool) -> moq_net: } impl Session { - /// Monitor a single track's subscription state. - /// Sets the flag when a viewer subscribes, clears it when all unsubscribe. - async fn run_track_monitor(&self, name: &str, track: &moq_net::track::Demand, flag: &AtomicBool) { + /// Mirror one track's subscription state into the shared demand. + async fn run_track_monitor(&self, kind: Kind) { + let track = match kind { + Kind::Video => &self.video_track, + Kind::Audio => &self.audio_track, + }; + let set = |wanted: bool| { + self.pause.update(|d| match kind { + Kind::Video => d.video = wanted, + Kind::Audio => d.audio = wanted, + }) + }; loop { if until_wanted(track, true).await.is_err() { break; } - tracing::info!("resuming {name}: viewer subscribed"); - flag.store(true, Ordering::Release); - self.paused.store(false, Ordering::Release); - self.resume.1.notify_all(); + tracing::info!(?kind, "viewer subscribed"); + set(true); if until_wanted(track, false).await.is_err() { break; } - tracing::info!("pausing {name}: no viewers"); - flag.store(false, Ordering::Release); + tracing::info!(?kind, "no viewers"); + set(false); } - } - - /// Monitor overall pause state. - /// Pauses when BOTH tracks are unused, resumes when EITHER becomes used. - async fn run_pause_monitor(&self) { - loop { - // Wait for BOTH tracks to become unused. - let (v, a) = tokio::join!( - until_wanted(&self.video_track, false), - until_wanted(&self.audio_track, false) - ); - if v.is_err() || a.is_err() { - break; - } - tracing::info!("pausing emulation: no viewers"); - self.paused.store(true, Ordering::Release); - - // Wait for EITHER track to become used. - tokio::select! { - Err(_) = until_wanted(&self.video_track, true) => break, - Err(_) = until_wanted(&self.audio_track, true) => break, - else => {}, - } - tracing::info!("resuming emulation: viewer connected"); - self.paused.store(false, Ordering::Release); - self.resume.1.notify_all(); - } - // Ensure emulator thread isn't stuck waiting on resume. - self.paused.store(false, Ordering::Release); - self.resume.1.notify_all(); + // Ensure the emulator thread isn't stuck waiting on resume. + self.pause.update(|d| d.closed = true); } /// Block the emulator thread until viewers connect. @@ -228,11 +250,7 @@ impl Session { /// joins mid-playthrough rather than a fresh boot. fn wait_for_resume(&self) { tracing::info!("pausing encoding"); - let (lock, cvar) = &self.resume; - let mut guard = lock.lock().unwrap(); - while self.paused.load(Ordering::Acquire) { - guard = cvar.wait(guard).unwrap(); - } + self.pause.wait(); tracing::info!("resuming encoding"); } @@ -310,22 +328,16 @@ async fn run(config: &Config) -> Result<()> { video_encoder, video_track, audio_track, - video_active: AtomicBool::new(false), - audio_active: AtomicBool::new(false), - paused: AtomicBool::new(true), // Start paused until first viewer. - resume: (Mutex::new(()), Condvar::new()), + pause: Pause::default(), // Paused until the first viewer. location: config.location.clone(), }); // Monitor track subscriptions. let s = session.clone(); - tokio::spawn(async move { s.run_track_monitor("video", &s.video_track, &s.video_active).await }); + tokio::spawn(async move { s.run_track_monitor(Kind::Video).await }); let s = session.clone(); - tokio::spawn(async move { s.run_track_monitor("audio", &s.audio_track, &s.audio_active).await }); - - let s = session.clone(); - tokio::spawn(async move { s.run_pause_monitor().await }); + tokio::spawn(async move { s.run_track_monitor(Kind::Audio).await }); // Run the emulator on a blocking thread. let emulator_handle = tokio::task::spawn_blocking({ @@ -375,7 +387,7 @@ fn run_emulator( loop { // Block when no viewers are watching. See state diagram in module docs. - if session.paused.load(Ordering::Acquire) { + if session.pause.get().paused() { // Mark the break BEFORE parking, not after resuming. Our PTS is the emulator // clock, which keeps running while we sleep, so the next frame lands however // long the pause was into the future. Published as a marker group that gap @@ -472,8 +484,11 @@ fn run_emulator( let elapsed = start.elapsed(); // Accumulate stats for this frame. - let is_video = session.video_active.load(Ordering::Relaxed); - let is_audio = session.audio_active.load(Ordering::Relaxed); + let Wanted { + video: is_video, + audio: is_audio, + .. + } = session.pause.get(); game_stats.tick(is_video, is_audio); // Tick the emulator. @@ -545,6 +560,36 @@ async fn main() -> Result<()> { mod tests { use super::*; + /// A viewer subscribing while the emulator parks always wakes it: the demand + /// changes under the lock the emulator waits on, so no notify is lost between + /// its check and its wait. + #[test] + fn subscribe_always_wakes() { + for _ in 0..2_000 { + let pause = Arc::new(Pause::default()); + let waiter = std::thread::spawn({ + let pause = pause.clone(); + move || pause.wait() + }); + pause.update(|d| d.video = true); + waiter.join().unwrap(); + } + } + + /// Paused only while neither track is wanted and demand is open. + #[test] + fn paused_is_derived() { + let mut d = Wanted::default(); + assert!(d.paused()); + d.audio = true; + assert!(!d.paused()); + d = Wanted { + closed: true, + ..Wanted::default() + }; + assert!(!d.paused()); + } + /// `--connect` is the only way to reach the relay: it must parse without /// a connect flag of our own alongside it, and the URL must land where `run` /// reads it. A second required flag would leave `--connect` inert. From 6b9a2a801c67027c5808b854265afe5fcf083413 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:58:42 -0800 Subject: [PATCH 3/6] docs(moq-boy): pause diagram names Wanted and its closed flag Co-Authored-By: Claude Opus 5.5 --- rs/moq-boy/src/main.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index ea9b169e0c0..06837bcb6b0 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -13,9 +13,9 @@ //! //! Pause/resume state machine: //! ```text -//! Demand { video, audio } under the condvar's mutex -//! both false → paused (emulation stops, condvar blocks) -//! either true → resumed (condvar notified) +//! Wanted { video, audio, closed } under the condvar's mutex +//! neither wanted and not closed → paused (emulation stops, condvar blocks) +//! anything wanted or closed → resumed (condvar notified) //! //! On resume → force video keyframe, reanchor audio //! ``` From 22c4bcb35cc513e30bf27c44106aa83a0f86b487 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:37:53 -0800 Subject: [PATCH 4/6] ci(rs): a selected crate's tested targets get their required features moq-boy's only target is its binary, which requires openh264, so a moq-boy-only selection built nothing, ran none of its tests, and left no timing data. The test build now turns on the required features of every target it holds, not just benches and examples. uniffi-bindgen's bin has no tests, so it is marked test = false to keep its UniFFI fork out of the build. Co-Authored-By: Claude Opus 5.5 --- rs/uniffi-bindgen/Cargo.toml | 4 +++- sh/rs/select.sh | 13 +++++++------ sh/rs/select.test.py | 10 ++++++++-- 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/rs/uniffi-bindgen/Cargo.toml b/rs/uniffi-bindgen/Cargo.toml index fc89aee83dc..7c9d75231c2 100644 --- a/rs/uniffi-bindgen/Cargo.toml +++ b/rs/uniffi-bindgen/Cargo.toml @@ -12,8 +12,10 @@ description = "Generate the Kotlin, Swift, and Python bindings from the moq-ffi name = "uniffi-bindgen" path = "src/main.rs" # Off by default so a workspace check skips the generator fork. Maturin passes -# required features along when it runs this bin for the Python wheel. +# required features along when it runs this bin for the Python wheel. It has no +# tests, so the test build leaves it out rather than compile the fork. required-features = ["cli"] +test = false [features] cli = ["dep:uniffi"] diff --git a/sh/rs/select.sh b/sh/rs/select.sh index c2a6eb893ed..0be0b104500 100755 --- a/sh/rs/select.sh +++ b/sh/rs/select.sh @@ -208,11 +208,12 @@ case "$action" in # The relay's io_uring listener, Linux-only. A moq-uring change selects # the relay too, as its dependent. if [[ "$(uname -s)" == Linux ]] && wants moq-relay; then features+=(moq-relay/io-uring); fi - # Cargo skips a bench or example whose `required-features` are off without - # a word, and a bench-only change selects its crate alone, so no dependent - # turns them on. Turn on every one the built crates' targets name. All of - # them are additive and build wherever the gate runs; moq-uring's targets - # compile to nothing off Linux. + # Cargo skips a target whose `required-features` are off without a word, + # and a crate alone in the selection (a bench-only change, or moq-boy, + # whose one target is its binary) has no dependent to turn them on. Turn + # on every one named by a target this build holds: benches, examples, and + # every target with tests. All of them are additive and build wherever the + # gate runs; moq-uring's targets compile to nothing off Linux. required=$( set -e cargo metadata --locked --format-version 1 --no-deps | jq -r --arg names "$building" --arg all "$packages" ' @@ -221,7 +222,7 @@ case "$action" in | select(if $all == "ALL" then (.name | endswith("-fuzz") | not) else (.name as $n | $want | index($n) != null) end) | .name as $name | .targets[] - | select(.kind // [] | any(. == "bench" or . == "example")) + | select((.kind // [] | any(. == "bench" or . == "example")) or .test) | (.["required-features"] // [])[] | "\($name)/\(.)"' | sort -u | tr '\n' ' ' ) diff --git a/sh/rs/select.test.py b/sh/rs/select.test.py index 329b7cd97bb..638aadbf238 100644 --- a/sh/rs/select.test.py +++ b/sh/rs/select.test.py @@ -16,7 +16,7 @@ def target_features(): - """Every bench and example `required-features`, as `crate/feature`, for the workspace.""" + """Every `required-features` of a bench, example, or tested target, as `crate/feature`, for the workspace.""" metadata = json.loads( subprocess.run( ["cargo", "metadata", "--locked", "--format-version", "1", "--no-deps"], @@ -32,7 +32,7 @@ def target_features(): for package in metadata["packages"] if not package["name"].endswith("-fuzz") for target in package["targets"] - if {"bench", "example"} & set(target["kind"]) + if {"bench", "example"} & set(target["kind"]) or target["test"] for feature in target.get("required-features", []) } ) @@ -265,6 +265,12 @@ def test_a_bench_alone_enables_its_required_features(self): self.assertIn(" --benches --examples ", call) self.assertIn(feature, call.split(" --features ", 1)[1].split()) + def test_a_binary_alone_enables_its_required_features(self): + # moq-boy's only target is its binary, so without openh264 the build + # holds nothing and its tests never run. + (call,) = [call for call in self.selected("rs/moq-boy/src/main.rs", action="test") if call.startswith("rs test ")] + self.assertIn("moq-boy/openh264", call.split(" --features ", 1)[1].split()) + class MetadataTest(unittest.TestCase): def setUp(self): From e0fd5a7fc9b1c5483e93e176777bf8215681089e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:51:08 -0800 Subject: [PATCH 5/6] test(rs): wrap the moq-boy selection test Co-Authored-By: Claude Opus 5.5 --- sh/rs/select.test.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sh/rs/select.test.py b/sh/rs/select.test.py index 638aadbf238..bc29c3ae0a6 100644 --- a/sh/rs/select.test.py +++ b/sh/rs/select.test.py @@ -268,7 +268,8 @@ def test_a_bench_alone_enables_its_required_features(self): def test_a_binary_alone_enables_its_required_features(self): # moq-boy's only target is its binary, so without openh264 the build # holds nothing and its tests never run. - (call,) = [call for call in self.selected("rs/moq-boy/src/main.rs", action="test") if call.startswith("rs test ")] + calls = self.selected("rs/moq-boy/src/main.rs", action="test") + (call,) = [call for call in calls if call.startswith("rs test ")] self.assertIn("moq-boy/openh264", call.split(" --features ", 1)[1].split()) From f971cd220598dda766543f9f690162d6225017d3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 23:07:56 -0800 Subject: [PATCH 6/6] fix(moq-boy): a closed track counts as unwanted, so the other can still pause Co-Authored-By: Claude Opus 5.5 --- rs/moq-boy/src/main.rs | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index 06837bcb6b0..6dd67ef5303 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -13,9 +13,9 @@ //! //! Pause/resume state machine: //! ```text -//! Wanted { video, audio, closed } under the condvar's mutex -//! neither wanted and not closed → paused (emulation stops, condvar blocks) -//! anything wanted or closed → resumed (condvar notified) +//! Wanted { video, audio, video_closed, audio_closed } under the condvar's mutex +//! neither wanted and some track still open → paused (emulation stops, condvar blocks) +//! anything wanted or both closed → resumed (condvar notified) //! //! On resume → force video keyframe, reanchor audio //! ``` @@ -161,13 +161,15 @@ struct Session { struct Wanted { video: bool, audio: bool, - /// A track's demand ended (shutdown): never block the emulator again. - closed: bool, + /// The video track's demand ended: it counts as unwanted from now on. + video_closed: bool, + /// The audio track's demand ended: it counts as unwanted from now on. + audio_closed: bool, } impl Wanted { fn paused(&self) -> bool { - !(self.video || self.audio || self.closed) + !(self.video || self.audio || (self.video_closed && self.audio_closed)) } } @@ -240,8 +242,11 @@ impl Session { tracing::info!(?kind, "no viewers"); set(false); } - // Ensure the emulator thread isn't stuck waiting on resume. - self.pause.update(|d| d.closed = true); + // A closed track is unwanted; once both close, the emulator never blocks again. + self.pause.update(|d| match kind { + Kind::Video => (d.video, d.video_closed) = (false, true), + Kind::Audio => (d.audio, d.audio_closed) = (false, true), + }); } /// Block the emulator thread until viewers connect. @@ -576,17 +581,22 @@ mod tests { } } - /// Paused only while neither track is wanted and demand is open. + /// Paused only while neither track is wanted and some track's demand is open. #[test] fn paused_is_derived() { let mut d = Wanted::default(); assert!(d.paused()); d.audio = true; assert!(!d.paused()); - d = Wanted { - closed: true, - ..Wanted::default() - }; + + // Video's encoder exits while audio plays: audio leaving must still pause. + d.video_closed = true; + assert!(!d.paused()); + d.audio = false; + assert!(d.paused()); + + // Both closed: never block again. + d.audio_closed = true; assert!(!d.paused()); }