diff --git a/cpp/moq/README.md b/cpp/moq/README.md index 6035d1274f0..ed5e062f83e 100644 --- a/cpp/moq/README.md +++ b/cpp/moq/README.md @@ -39,7 +39,7 @@ The installed package compiles `moq.cpp` inside the consumer's project, at its ` ## Cancellation -Cancelling a future (`cancel()`, destroying it, destroying the `moq::Continuation` returned by `then`, or destroying a coroutine suspended on it) drops the Rust future. Native moq-ffi runs each async call as a spawned task that holds an `AbortOnDrop` on it (`rs/moq-ffi/src/ffi.rs`), so dropping the future aborts the work at its next await point instead of letting it finish unobserved. The continuation of a cancelled future never runs. +Cancelling a future (`cancel()`, destroying it, destroying the `moq::Continuation` returned by `then`, or destroying a coroutine suspended on it) drops the Rust future. Most async calls run in place, on the thread that polls the future, so cancelling stops the work at once: it never finishes unobserved or takes data the next call is waiting for. The few calls spawned onto the moq-ffi runtime are aborted at their next await point. The continuation of a cancelled future never runs. Like `std::future`, `valid()` is false once `get()`, `then()`, `cancel()`, or a move took the future's state. Reading an invalid future aborts with "it was consumed or cancelled", so check `valid()` first when a future may have been cancelled, consumed, or moved from. diff --git a/quest/m0/README.md b/quest/m0/README.md index 5aebcb5601f..6ce09ef4ea0 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -63,7 +63,6 @@ remain and no release waits on them. - [Draft-22 media on 0.17](/quest/m0/release-22/README.md) - a 0.17.x with the LOCATION_FILTER and FIRST_OBJECT fixes and moq-noq 1.3.4, before Seattle - [FFI publisher stall](/quest/m0/ffi-publisher-stall.md) - every Go, Python, and C++ publisher cell passes reliably with the serve budgets, and a cell fails when a connection idles out -- [FFI cancelled reads](/quest/m0/ffi-cancel-read.md) - cancelling a moq-ffi read in any binding leaves its data for the next read, so the C++ probe stops flaking - [web-transport releases the qmux fixes](/quest/m0/qmux-credit-upstream.md) - waiting on moq-dev/web-transport#412 and #413 to merge and ship, which qmux credit bumps to - [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines - [JS track takeover](/quest/m0/js-track-takeover.md) - JS `createTrack` answers a queued request and continues its sequences, as Rust does, so a re-announced `@moq/publish` catalog never restarts its groups diff --git a/quest/m0/ffi-cancel-read.md b/quest/m0/ffi-cancel-read.md deleted file mode 100644 index ecb849fa75a..00000000000 --- a/quest/m0/ffi-cancel-read.md +++ /dev/null @@ -1,34 +0,0 @@ -# [M] A cancelled moq-ffi read never takes data - -## Goal - -Cancelling a moq-ffi async read (`read_frame`, `next`, `next_group`, and the -other consumer reads) in any binding leaves the data it was waiting for to -the next read, as the method docs promise. Today the cancelled read can take -it, and the next read hangs: `cpp/moq/test/probe.cpp` fails at its -checks that read after a cancelled read in about 1 of 30 runs at C++17 -and 2 of 20 at C++23 locally, which flakes the `cpp.yml` check. - -## Plan - -Found while iterating on #4079. `Task::run` and `detached` in -`rs/moq-ffi/src/ffi.rs` spawn the work as a tokio task tied to the caller's -future with `AbortOnDrop`. A foreign `cancel()` reaches uniffi's -`rust_future_cancel`, which only wakes the continuation. The Rust future, -and with it the `AbortOnDrop`, drops at `rust_future_free`, which the -bindings call later from their executor. Until then the spawned closure -still holds the consumer's lock, so it takes the next frame, which goes -nowhere, while the next read waits behind it. - -Both known fixes stop the work when the cancel happens, not when the handle -is freed: - -- Abort the spawned task when the uniffi future is cancelled, not only when - it drops. -- Await reads in place instead of spawning them, so a cancelled future that - is never polled again cannot make progress. Reads that need a tokio - context keep the spawn. - -Land it with a Rust regression test in moq-ffi that cancels a pending read -without freeing it, writes a frame, and requires the next read to return -it. The C++ probe already covers it end to end. diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md index b7fe67151a2..3490c2b395e 100644 --- a/quest/m1/ffi-runtime.md +++ b/quest/m1/ffi-runtime.md @@ -22,11 +22,13 @@ added this quest): No configuration knob until an embedder needs one. Rejected: a small fixed pool, and keeping `current_thread` behind the serve budgets (`kio::coop::Budget`) alone. -- Keep the "foreign caller's thread never drives our futures" property: work - still runs via `Task::run` and `detached`. Check the exported async fns that - await in place (`subscribe_catalog`, `subscribe_track`, `fetch_group`, - `request_broadcast`, `decode_audio`, `decode_video`) and the sync methods - that enter the runtime context (`MoqAudioProducer::write`). +- `Task::run` awaits in place on the foreign thread that polls it (#5140), so + a cancelled call never makes progress; only the drivers, `detached`, and + `Task::spawn` run on the runtime. Check that in-place polls, the exported + async fns that await in place (`subscribe_catalog`, `subscribe_track`, + `fetch_group`, `request_broadcast`, `decode_audio`, `decode_video`), and + the sync methods that enter the runtime context (`MoqAudioProducer::write`) + still work against a multi-thread handle. - Callbacks change contract. Today moq-c status callbacks and uniffi callbacks fire one at a time on the single runtime thread; on workers they fire on any thread, and callbacks for different handles run at once. diff --git a/rs/moq-ffi/src/ffi.rs b/rs/moq-ffi/src/ffi.rs index 184b09b1582..4f87fb306c0 100644 --- a/rs/moq-ffi/src/ffi.rs +++ b/rs/moq-ffi/src/ffi.rs @@ -3,10 +3,11 @@ use std::sync::Arc; use crate::error::MoqError; -/// A dedicated runtime thread, so a foreign caller's thread never has to drive our futures. +/// A dedicated runtime thread, which drives the I/O and timers every call registers and runs +/// the background work spawned onto it. /// /// wasm32 has neither threads nor a tokio driver. uniffi's `RustFuture` is polled by the -/// JS event loop instead, so [`Task::run`] awaits in place there. +/// JS event loop instead. #[cfg(not(target_arch = "wasm32"))] static RUNTIME: std::sync::OnceLock = std::sync::OnceLock::new(); @@ -16,6 +17,22 @@ pub(crate) struct Runtime { handle: tokio::runtime::Handle, /// Taken by [`shutdown`], so the thread is stopped and joined once. thread: std::sync::Mutex>, + /// Set by [`shutdown`] to wake the [`Task::run`] calls parked in place, so they observe + /// [`Polls::stopped`] and resolve `Cancelled`. + stopped: tokio::sync::watch::Sender, + /// The [`Task::run`] polls in flight on host threads, which [`shutdown`] waits out. + polls: std::sync::Mutex, + /// Notified when the last in-flight poll finishes. + idle: std::sync::Condvar, +} + +#[cfg(not(target_arch = "wasm32"))] +#[derive(Default)] +struct Polls { + active: usize, + /// Set by [`shutdown`]: no poll may start once the drivers are about to stop, because a + /// tokio timer polled after its driver is gone panics rather than erroring. + stopped: bool, } #[cfg(not(target_arch = "wasm32"))] @@ -60,6 +77,9 @@ pub(crate) fn runtime() -> &'static Runtime { Runtime { handle, thread: std::sync::Mutex::new(Some(Thread { stop, join })), + stopped: tokio::sync::watch::Sender::new(false), + polls: Default::default(), + idle: Default::default(), } }) } @@ -73,10 +93,70 @@ pub(crate) fn shutdown() { let Some(thread) = runtime.thread.lock().unwrap().take() else { return; }; + // Before the thread stops, so no call awaited in place polls the runtime after it is gone. + let mut polls = runtime.polls.lock().unwrap(); + polls.stopped = true; + drop(runtime.idle.wait_while(polls, |polls| polls.active > 0).unwrap()); + // Outside the lock: a waker may poll inline, which takes it. + runtime.stopped.send_replace(true); let _ = thread.stop.send(()); let _ = thread.join.join(); } +/// Resolves once [`shutdown`] has run. +#[cfg(not(target_arch = "wasm32"))] +async fn stopped() { + let mut stopped = runtime().stopped.subscribe(); + // `Err` only when the sender is dropped, which a static never is. + let _ = stopped.wait_for(|&stopped| stopped).await; +} + +/// wasm32's runtime is the JS event loop, which never stops under us. +#[cfg(target_arch = "wasm32")] +async fn stopped() { + std::future::pending().await +} + +/// Marks a [`Task::run`] poll in flight, so [`shutdown`] waits for it to finish. +#[cfg(not(target_arch = "wasm32"))] +struct Polling; + +#[cfg(not(target_arch = "wasm32"))] +impl Polling { + /// `None` once [`shutdown`] has begun. + fn start() -> Option { + let mut polls = runtime().polls.lock().unwrap(); + if polls.stopped { + return None; + } + polls.active += 1; + Some(Self) + } +} + +#[cfg(not(target_arch = "wasm32"))] +impl Drop for Polling { + fn drop(&mut self) { + let runtime = runtime(); + let mut polls = runtime.polls.lock().unwrap(); + polls.active -= 1; + if polls.active == 0 { + runtime.idle.notify_all(); + } + } +} + +/// wasm32's runtime is the JS event loop, which never stops under us. +#[cfg(target_arch = "wasm32")] +struct Polling; + +#[cfg(target_arch = "wasm32")] +impl Polling { + fn start() -> Option { + Some(Self) + } +} + /// Enter the runtime context, so a handle built outside [`Task::run`] can still spawn. /// /// A no-op on wasm32, where the JS event loop is the only runtime. @@ -213,12 +293,45 @@ impl Task { } } - /// Spawn an async closure on the runtime. + /// Run an async closure against the state, awaiting it in place. /// /// The closure receives a [Guard] which derefs to `T`. /// If two calls are made concurrently, the second waits for the first to finish. - #[cfg(not(target_arch = "wasm32"))] + /// + /// Not spawned: a foreign cancel (uniffi's `rust_future_cancel`) only stops polling, and the + /// future is dropped later at `rust_future_free`. Spawned work would keep running until then + /// and take the very event the next call is waiting for. Each poll enters the runtime, so the + /// closure can still use tokio timers, sockets, and spawn. pub async fn run(&self, f: F) -> Result + where + F: FnOnce(Guard) -> Fut, + Fut: Future>, + { + let drive = Self::drive(self.cancel.subscribe(), self.state.clone(), f); + let mut run = std::pin::pin!(async { + tokio::select! { + biased; + _ = stopped() => Err(MoqError::Cancelled), + result = drive => result, + } + }); + std::future::poll_fn(|cx| { + let Some(_polling) = Polling::start() else { + return std::task::Poll::Ready(Err(MoqError::Cancelled)); + }; + let _runtime = enter(); + run.as_mut().poll(cx) + }) + .await + } + + /// [Self::run] on the runtime thread rather than in place. + /// + /// Only for a state shut down by [Self::cancel_and_wait], which blocks its caller until an + /// in-flight call unwinds: a call awaited in place on that same thread never would. The cost + /// is the race [Self::run] avoids, since a foreign cancel leaves this running until freed. + #[cfg(not(target_arch = "wasm32"))] + pub async fn spawn(&self, f: F) -> Result where R: Send + 'static, F: FnOnce(Guard) -> Fut + Send + 'static, @@ -229,11 +342,8 @@ impl Task { let handle = runtime().spawn(async move { Self::drive(cancel, state, f).await }); - // Dropping a JoinHandle detaches its task rather than stopping it, so a caller - // that gives up (an `asyncio.wait_for` timeout, a cancelled Swift/Kotlin task) - // would leave the closure running with the state lock held. It then consumes - // the very event the next call is waiting for, and that call blocks behind it - // meanwhile. Tie the work to the caller's future instead. + // Dropping a JoinHandle detaches its task rather than stopping it, so a caller that + // gives up would leave the closure running with the state lock held. let _abort = AbortOnDrop(handle.abort_handle()); match handle.await { @@ -243,20 +353,6 @@ impl Task { } } - /// Run an async closure, awaiting it in place. - /// - /// Unlike the native path this does not detach, so dropping the returned future - /// cancels the work rather than leaving it running on a runtime thread. - #[cfg(target_arch = "wasm32")] - pub async fn run(&self, f: F) -> Result - where - R: 'static, - F: FnOnce(Guard) -> Fut + 'static, - Fut: Future> + 'static, - { - Self::drive(self.cancel.subscribe(), self.state.clone(), f).await - } - /// Wait for the lock, then run `f`, with [Self::cancel] able to interrupt either. async fn drive( mut cancel: tokio::sync::watch::Receiver, @@ -288,8 +384,9 @@ impl Task { /// /// Terminal: there is no way back from here, and the state is gone rather than idle. /// The drop is not synchronous with this call, because an in-flight [Self::run] holds the - /// state until it observes the flag and unwinds. It also lands on the runtime thread, which - /// is where the state was built and the only place with a reactor for what it unregisters. + /// state until it observes the flag and unwinds, or its caller drops it. It also lands on the + /// runtime thread, which is where the state was built and the only place with a reactor for + /// what it unregisters. pub fn cancel(&self) { // send_replace, not send: `send` refuses to store the value while no // receiver exists, so a cancel BEFORE the first `run` would silently @@ -309,12 +406,13 @@ impl Task { /// /// A synchronous caller uses this to make the release of what the state owns /// observable: the listening socket is gone, not merely scheduled to close. - /// `shutdown` runs on the runtime thread, after any in-flight [Self::run] has + /// `shutdown` runs on the runtime thread, after any in-flight [Self::spawn] has /// unwound, and the lock is held across it so a second cancel waits too. /// /// It waits on a channel rather than [tokio::sync::Mutex::blocking_lock] so it /// works from inside another runtime, as the tests do; it must not run on the - /// runtime thread itself, which would deadlock. + /// runtime thread itself, which would deadlock. Neither may the state's calls use + /// [Self::run]: one awaited in place on the blocked thread would never unwind. #[cfg(not(target_arch = "wasm32"))] pub fn cancel_and_wait(&self, shutdown: F) where diff --git a/rs/moq-ffi/src/server.rs b/rs/moq-ffi/src/server.rs index bd32f9251da..8ba82ad8ea0 100644 --- a/rs/moq-ffi/src/server.rs +++ b/rs/moq-ffi/src/server.rs @@ -143,7 +143,7 @@ impl MoqServer { /// Bind the listening socket. Returns the bound local address as a string, /// which is useful when binding to an ephemeral port (`:0`). pub async fn listen(&self) -> Result { - self.task.run(|mut state| async move { state.listen().await }).await + self.task.spawn(|mut state| async move { state.listen().await }).await } /// Accept the next incoming session. Returns `None` when the server has closed. @@ -151,7 +151,7 @@ impl MoqServer { /// `listen()` must be called first. Dropping the returned future aborts this /// call alone and leaves the server listening. pub async fn accept(&self) -> Result>, MoqError> { - self.task.run(|mut state| async move { state.accept().await }).await + self.task.spawn(|mut state| async move { state.accept().await }).await } /// SHA-256 fingerprints of the configured TLS certificates, hex-encoded. diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 3191e8ebae1..34a0aaaca97 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -30,7 +30,7 @@ async fn ffi_caught_up() { rx.await.expect("ffi runtime dropped the catch-up task"); } -/// Spawn `fut` and wait until the FFI runtime has driven its inner `Task::run`. +/// Spawn `fut`, poll it once, and wait until the FFI runtime has caught up with what that started. async fn spawn_parked(fut: F) -> tokio::task::JoinHandle where F: Future + Send + 'static, @@ -3319,6 +3319,31 @@ async fn raw_read_frame_skips_empty_then_populated_groups() { assert_eq!(frame.timestamp_us, Some(2_000)); } +/// A foreign cancel only stops polling a read; uniffi drops it later, at `rust_future_free`. +/// Until then the cancelled read must not take the frame the next read is waiting for. +#[tokio::test] +async fn raw_read_frame_cancelled_before_free_leaves_the_frame() { + let (_broadcast, track, consumer) = raw_track(); + + // Poll once, then stop without dropping, which is all `rust_future_cancel` does. + let mut cancelled = Box::pin(consumer.read_frame()); + let first = std::future::poll_fn(|cx| std::task::Poll::Ready(cancelled.as_mut().poll(cx))).await; + assert!(first.is_pending()); + + track.write_frame(group_frame(b"next")).unwrap(); + // Give anything still driving the cancelled read the chance to take the frame. + ffi_caught_up().await; + + let next = consumer.read_frame(); + drop(cancelled); + let frame = tokio::time::timeout(TIMEOUT, next) + .await + .expect("the cancelled read took the frame") + .unwrap() + .expect("expected a frame"); + assert_eq!(frame.payload, b"next".to_vec()); +} + /// Cancelling `read_frame` after it has taken the next group must not drop that /// group: the next read still returns its first frame. #[tokio::test] @@ -4782,18 +4807,27 @@ async fn request_accept_cancelled_after_cancel() { server.cancel(); } -/// Stopping the runtime is process-wide, so the scenario runs in a child test process: this -/// test re-runs its own binary filtered to itself with the marker set, and judges the exit. +/// Stopping the runtime is process-wide, so a shutdown scenario runs in a child test process. +/// +/// Returns true in the child. In the parent, re-runs this binary filtered to `test` with a +/// marker set, judges its exit, and returns false. +fn shutdown_child(test: &str) -> bool { + const MARKER: &str = "MOQ_FFI_TEST_SHUTDOWN_CHILD"; + if std::env::var_os(MARKER).is_some() { + return true; + } + let status = std::process::Command::new(std::env::current_exe().unwrap()) + .args(["--exact", &format!("test::{test}")]) + .env(MARKER, "1") + .status() + .expect("failed to spawn the child test process"); + assert!(status.success(), "child test process failed: {status}"); + false +} + #[tokio::test] async fn shutdown_cancels_and_drops_cleanly() { - const MARKER: &str = "MOQ_FFI_TEST_SHUTDOWN_CHILD"; - if std::env::var_os(MARKER).is_none() { - let status = std::process::Command::new(std::env::current_exe().unwrap()) - .args(["--exact", "test::shutdown_cancels_and_drops_cleanly"]) - .env(MARKER, "1") - .status() - .expect("failed to spawn the child test process"); - assert!(status.success(), "child test process failed: {status}"); + if !shutdown_child("shutdown_cancels_and_drops_cleanly") { return; } @@ -4875,6 +4909,56 @@ async fn shutdown_cancels_and_drops_cleanly() { drop(server_origin); } +/// A `Task::run` polled in place on a host thread must finish its poll before shutdown stops +/// the drivers: a tokio timer polled after its driver is gone panics. +#[test] +fn shutdown_waits_for_an_in_place_poll() { + if !shutdown_child("shutdown_waits_for_an_in_place_poll") { + return; + } + + let (entered, entered_rx) = std::sync::mpsc::channel(); + let (release, release_rx) = std::sync::mpsc::channel::<()>(); + let poller = std::thread::spawn(move || { + let task = crate::ffi::Task::new(()); + let run = task.run(|_| async move { + entered.send(()).unwrap(); + // Holds this poll open while shutdown starts on another thread. + release_rx.recv().unwrap(); + tokio::time::sleep(Duration::from_millis(1)).await; + // Even if the sleep is already due, only the shutdown may finish this call. + std::future::pending::>().await + }); + tokio::runtime::Builder::new_current_thread() + .build() + .unwrap() + .block_on(run) + }); + entered_rx.recv().unwrap(); + + let shutdown = std::thread::spawn(|| crate::moq_ffi_shutdown()); + + // A fresh call resolves `Cancelled` on its first poll once shutdown has begun. + let probe = crate::ffi::Task::new(()); + loop { + let mut call = std::pin::pin!(probe.run(|_| std::future::pending::>())); + let mut cx = std::task::Context::from_waker(std::task::Waker::noop()); + match call.as_mut().poll(&mut cx) { + std::task::Poll::Ready(result) => { + assert!(matches!(result, Err(MoqError::Cancelled)), "{result:?}"); + break; + } + std::task::Poll::Pending => std::thread::yield_now(), + } + } + + // Shutdown has begun: the held poll now polls its timer. + release.send(()).unwrap(); + let result = poller.join().expect("the in-place poll panicked"); + assert!(matches!(result, Err(MoqError::Cancelled)), "{result:?}"); + shutdown.join().unwrap(); +} + /// The broadcast's current catalog, read on the publish side. fn published_catalog( broadcast: &MoqBroadcastProducer,