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
2 changes: 1 addition & 1 deletion cpp/moq/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
1 change: 0 additions & 1 deletion quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
34 changes: 0 additions & 34 deletions quest/m0/ffi-cancel-read.md

This file was deleted.

12 changes: 7 additions & 5 deletions quest/m1/ffi-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
152 changes: 125 additions & 27 deletions rs/moq-ffi/src/ffi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Runtime> = std::sync::OnceLock::new();

Expand All @@ -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<Option<Thread>>,
/// 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<bool>,
/// The [`Task::run`] polls in flight on host threads, which [`shutdown`] waits out.
polls: std::sync::Mutex<Polls>,
/// 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"))]
Expand Down Expand Up @@ -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(),
}
})
}
Expand All @@ -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<Self> {
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<Self> {
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.
Expand Down Expand Up @@ -213,12 +293,45 @@ impl<T: kio::MaybeSend + 'static> Task<T> {
}
}

/// 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.
Comment on lines +301 to +304

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update the documented native cancellation model

After Task::run starts awaiting work in place, cpp/moq/README.md:42 still tells C++ users that every native async call runs as a spawned runtime task guarded by AbortOnDrop. That is now the opposite of this implementation and gives users the wrong threading and cancellation model, particularly when choosing a custom executor or diagnosing codec work on its thread. Update the public cancellation documentation with this behavioral change.

AGENTS.md reference: AGENTS.md:L28-L28

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, fixed in 09fe2b8. cpp/moq/README.md now says most calls run in place on the polling thread, so a cancel stops the work at once, and the few spawned calls abort at their next await. I also aligned quest/m1/ffi-runtime.md, which still assumed Task::run keeps foreign threads from driving our futures.

(Written by Claude Opus 5.5)

pub async fn run<R, F, Fut>(&self, f: F) -> Result<R, MoqError>
where
F: FnOnce(Guard<T>) -> Fut,
Fut: Future<Output = Result<R, MoqError>>,
{
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,
Comment on lines +312 to +315

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Exclude active in-place polls before stopping the runtime

biased only orders these polls; it does not synchronize them with shutdown(). After stopped() returns Pending, another host thread can set the flag and finish tearing down the runtime while this same drive poll continues. MoqRequest::accept reaches Request::ok → Deadline::bound (rs/moq-tokio/src/server.rs:939–944), which polls a Tokio timeout when a legacy SETUP response is flow-control blocked. Resuming that poll after teardown can poll the shut-down timer driver and panic instead of returning Cancelled. The previous spawned closure ran on the joined runtime thread, so teardown could not overtake its poll. Coordinate teardown with active in-place polls (or keep the runtime-dependent handshake path spawned), and add a cross-thread shutdown regression that pauses an accept poll before its timeout is polled.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, fixed in b00132f. shutdown() now sets a stop flag under a mutex and waits for in-flight Task::run polls to finish before it stops the runtime thread. A poll that starts after the flag resolves Cancelled without touching the drivers. The watch still wakes parked calls, and it is sent outside the lock in case a waker polls inline.

Regression test shutdown_waits_for_an_in_place_poll holds a poll open on a host thread, starts shutdown on another, then polls a tokio timer. It failed 5/30 runs without the fix (timer panic) and passed 60/60 with it. It can't be made deterministic without the fix, since a release that waits for shutdown to finish would deadlock the fixed version.

(Written by Claude Opus 5.5)

}
});
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<R, F, Fut>(&self, f: F) -> Result<R, MoqError>
where
R: Send + 'static,
F: FnOnce(Guard<T>) -> Fut + Send + 'static,
Expand All @@ -229,11 +342,8 @@ impl<T: kio::MaybeSend + 'static> Task<T> {

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 {
Expand All @@ -243,20 +353,6 @@ impl<T: kio::MaybeSend + 'static> Task<T> {
}
}

/// 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<R, F, Fut>(&self, f: F) -> Result<R, MoqError>
where
R: 'static,
F: FnOnce(Guard<T>) -> Fut + 'static,
Fut: Future<Output = Result<R, MoqError>> + '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<R, F, Fut>(
mut cancel: tokio::sync::watch::Receiver<bool>,
Expand Down Expand Up @@ -288,8 +384,9 @@ impl<T: kio::MaybeSend + 'static> Task<T> {
///
/// 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
Expand All @@ -309,12 +406,13 @@ impl<T: kio::MaybeSend + 'static> Task<T> {
///
/// 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<F, Fut>(&self, shutdown: F)
where
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-ffi/src/server.rs
Original file line number Diff line number Diff line change
Expand Up @@ -143,15 +143,15 @@ 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<String, MoqError> {
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.
///
/// `listen()` must be called first. Dropping the returned future aborts this
/// call alone and leaves the server listening.
pub async fn accept(&self) -> Result<Option<Arc<MoqRequest>>, 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.
Expand Down
Loading
Loading