From 14ae11fe3057994c74711d6cbfc4d61680063b5d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 19:54:15 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m1/precut-fixes/moq-c-rate-thread.md Quest-Claim: e1c18df230a016fa From 310fc57e5bdd06239a49484ba35d0691e00ad5b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 21:24:08 -0800 Subject: [PATCH 2/3] fix(libmoq): the video rate follower runs on its own thread A follower retuning an encoder blocks on the codec and on the encoder lock a caller holds for a whole encode. On the shared current-thread runtime that stalled every session's I/O, timers, and callbacks. Co-Authored-By: Claude Opus 5.5 --- quest/m1/precut-fixes/moq-c-rate-thread.md | 29 ------------ rs/libmoq/src/ffi.rs | 22 ++++++++++ rs/libmoq/src/test.rs | 51 ++++++++++++++++++++++ rs/libmoq/src/video.rs | 5 ++- 4 files changed, 76 insertions(+), 31 deletions(-) delete mode 100644 quest/m1/precut-fixes/moq-c-rate-thread.md diff --git a/quest/m1/precut-fixes/moq-c-rate-thread.md b/quest/m1/precut-fixes/moq-c-rate-thread.md deleted file mode 100644 index 3b06f103fc4..00000000000 --- a/quest/m1/precut-fixes/moq-c-rate-thread.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] moq-c's video rate follower runs off the session runtime - -## Goal - -A moq-c video encoder that follows a bandwidth allocator never blocks the -`moq-c` runtime thread, which drives every session's I/O, timers, and C -callbacks: a bitrate change, a rung flush, or a hardware encoder reopen -stalls only the encoder. - -## Plan - -Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. -`follow_reservation` in `rs/moq-c/src/video.rs` runs through -`ffi::Background` on the single current-thread `RUNTIME` -(`rs/moq-c/src/ffi.rs`) and waits there on the encoder lock (held by a C -thread for a whole encode) and on codec round trips. moq-ffi already runs -the same loop on its own thread (`spawn_follow` in `rs/moq-ffi/src/video.rs`) -for exactly this reason. `release` blocked on bitrate changes only; the -flush and reopen came with #6781. - -Recommended: copy moq-ffi's dedicated-thread follower. Measure before and -after: step the bandwidth across a rung threshold and record another -subscription's frame delivery gaps. - -Public API: none. Wire: none. - -Caused by, for the fix PR's `## Caused by`: - -- [moq-dev/moq#6781](https://github.com/moq-dev/moq/pull/6781) - added rung flush and encoder reopen to the follower on the shared runtime diff --git a/rs/libmoq/src/ffi.rs b/rs/libmoq/src/ffi.rs index 29e1f9f2fe3..b958269d65c 100644 --- a/rs/libmoq/src/ffi.rs +++ b/rs/libmoq/src/ffi.rs @@ -94,6 +94,28 @@ impl Background { Self { result: Some(receiver) } } + /// Spawn an owned operation on a thread of its own, for one that blocks, such as on a + /// codec, which would stall every session sharing the runtime thread. + pub fn thread( + name: &str, + future: impl std::future::Future> + Send + 'static, + ) -> Self { + let result = kio::Producer::new(None); + let receiver = result.consume(); + std::thread::Builder::new() + .name(name.into()) + .spawn(move || { + // The runtime's context without running on it, for anything the operation spawns. + let _guard = RUNTIME.enter(); + let completed = pollster::block_on(run(future)); + *result + .write() + .unwrap_or_else(|_| unreachable!("only the background thread closes its completion")) = Some(completed); + }) + .expect("failed to spawn background thread"); + Self { result: Some(receiver) } + } + /// Own a model driver until its completion has been reported. pub fn driver(mut driver: impl moq_net::time::Driver + Send + 'static) -> Self { let result = kio::Producer::new(None); diff --git a/rs/libmoq/src/test.rs b/rs/libmoq/src/test.rs index efc93bc8954..68345b13cb3 100644 --- a/rs/libmoq/src/test.rs +++ b/rs/libmoq/src/test.rs @@ -8406,6 +8406,57 @@ fn encode_video_ceiling_wakes_a_rung_above() { assert_eq!(moq_origin_close(origin), 0); } +/// A rate follower waiting on its encoder, as it does while a caller encodes, leaves the +/// runtime every session shares free to run. +#[test] +fn encode_video_follower_never_stalls_the_runtime() { + let (bandwidth, estimate) = test_allocator(); + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"rate"); + let input = moq_video_encoder_input { + format: moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_RGBA as u32, + width: 320, + height: 240, + framerate: moq_video_frame_rate { + numerator: 30, + denominator: 1, + }, + }; + let output = moq_video_encoder_output { + codec: moq_video_codec::MOQ_VIDEO_CODEC_H264 as u32, + bitrate: 2_000_000, + join_us: 0, + kind: moq_video_encoder_kind::MOQ_VIDEO_ENCODER_KIND_SOFTWARE as u32, + encoder: std::ptr::null(), + encoder_len: 0, + }; + let options = moq_video_encode_options { bandwidth, lower: 0 }; + let video = id(unsafe { moq_encode_video(broadcast, &input, &output, &options) }); + let shared = State::lock().video.producer(Id::try_from(video).unwrap()).unwrap(); + + let (done, probed) = mpsc::channel(); + { + // Held as a caller's encode holds it, while the grant moves and wakes the follower. + let guard = shared.lock(); + estimate.set(Some(moq_net::bandwidth::Rate::from_kbps(500))).unwrap(); + crate::ffi::RUNTIME.spawn(async move { + // Yield long enough for the woken follower to run ahead of this task. + for _ in 0..1000 { + tokio::task::yield_now().await; + } + done.send(()).unwrap(); + }); + let probed = probed.recv_timeout(TIMEOUT); + drop(guard); + probed.expect("the runtime stalled behind the rate follower"); + } + + assert_eq!(moq_encode_video_finish(video), 0); + assert_eq!(moq_allocator_close(bandwidth), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + /// Listen on an ephemeral loopback port with a generated certificate. fn listen(cb: &Callback) -> (u32, String, String) { let bind = "127.0.0.1:0"; diff --git a/rs/libmoq/src/video.rs b/rs/libmoq/src/video.rs index aab5a88f9ad..6173357c2fd 100644 --- a/rs/libmoq/src/video.rs +++ b/rs/libmoq/src/video.rs @@ -569,7 +569,8 @@ impl VideoEncoder { let ceiling = *self.ceiling.read(); let reservation = Arc::new(allocator.reserve(&self.producer.demand(), ceiling)); let (stop, stopped) = oneshot::channel(); - let follower = crate::ffi::Background::new({ + // Its own thread: retuning blocks on the codec, and on this lock while a caller encodes. + let follower = crate::ffi::Background::thread("libmoq-rate", { let shared = shared.clone(); let lower = self.lower.clone(); let consumer = reservation.consume(); @@ -1705,7 +1706,7 @@ mod tests { let mut config = moq_video::encode::Config::new(320, 240, moq_video::FrameRate::new(30, 1).unwrap()); config.kind = moq_video::encode::Kind::Software; let encoder = moq_video::encode::Sink::open(&config).await.unwrap(); - let follower = crate::ffi::Background::new(async { panic!("injected rate follower panic") }); + let follower = crate::ffi::Background::thread("libmoq-rate", async { panic!("injected rate follower panic") }); assert!(matches!(follower.finished().await, Err(Error::Panic))); let estimate = moq_net::bandwidth::Producer::new(); let allocator = moq_net::bandwidth::Allocator::new(estimate.consume()); From 827fc19d3d8ebd44f60cc5a802e98a27c0d41438 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 23:31:16 -0800 Subject: [PATCH 3/3] style(libmoq): fmt Co-Authored-By: Claude Opus 5.5 --- rs/libmoq/src/ffi.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/rs/libmoq/src/ffi.rs b/rs/libmoq/src/ffi.rs index b958269d65c..ea40aa50802 100644 --- a/rs/libmoq/src/ffi.rs +++ b/rs/libmoq/src/ffi.rs @@ -96,10 +96,7 @@ impl Background { /// Spawn an owned operation on a thread of its own, for one that blocks, such as on a /// codec, which would stall every session sharing the runtime thread. - pub fn thread( - name: &str, - future: impl std::future::Future> + Send + 'static, - ) -> Self { + pub fn thread(name: &str, future: impl std::future::Future> + Send + 'static) -> Self { let result = kio::Producer::new(None); let receiver = result.consume(); std::thread::Builder::new()