From db3748c51db976dc8728e5c7e1956210c1797b5b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 10 Oct 2026 13:58:31 -0700 Subject: [PATCH 1/4] chore(quest): claim parallel FFI runtime Co-Authored-By: GPT-6 From 51e5bb2f53a2379eb2f3c56c979201a7c3a316b3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 10 Oct 2026 14:36:19 -0700 Subject: [PATCH 2/4] feat(ffi): run native drivers on a worker pool Co-Authored-By: GPT-6 --- cpp/moq/README.md | 2 +- doc/lib/cpp/index.md | 8 +++- doc/lib/dart/index.md | 6 +++ doc/lib/go/index.md | 6 +++ doc/lib/kt/index.md | 6 +++ doc/lib/py/index.md | 6 +++ doc/lib/swift/index.md | 6 +++ quest/m1/ffi-runtime.md | 6 +++ rs/moq-ffi/src/ffi.rs | 89 ++++++++++++++++++++++++++++++----------- rs/moq-ffi/src/lib.rs | 8 ++-- 10 files changed, 114 insertions(+), 29 deletions(-) diff --git a/cpp/moq/README.md b/cpp/moq/README.md index ed5e062f83e..1f3df9149e9 100644 --- a/cpp/moq/README.md +++ b/cpp/moq/README.md @@ -31,7 +31,7 @@ Every generated type lives in `namespace moq`. Objects are `std::shared_ptr`; re - A fallible call returns `moq::expected`, which is `std::expected` on C++23 and a bundled `tl::expected` below it. The generated sources and every includer must agree on which, so `moq/moq.hpp` references a symbol named for the one it sees and `src/moq.cpp` defines the one it was built with: a mismatch fails to link. - An async call returns `moq::Future`. Block on it with `get()` or `wait_for()`, attach a continuation with `std::move(future).then(executor, callback)`, which returns a `moq::Continuation`, or `co_await` it on C++20. - `moq::Error` is a value holding a `std::variant` of its cases, and `to_string()` gives Rust's `Display` message. Nothing throws. A Rust panic aborts with a message on stderr, and so does reading an invalid future (see [Cancellation](#cancellation)). -- Futures are polled and continuations run on one process-wide executor thread unless the application installs its own with `moq::set_executor` before the first async call. `moq::shutdown()` stops the moq-ffi runtime thread (`moq_ffi_shutdown`), then the executor, before unloading the code a continuation could call into. +- Futures are polled and continuations run on one process-wide executor thread unless the application installs its own with `moq::set_executor` before the first async call. `moq::shutdown()` stops the moq-ffi runtime workers (`moq_ffi_shutdown`), then the executor, before unloading the code a continuation could call into. ## C++ standard diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index dca6016ac7e..efad8976c55 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -166,7 +166,7 @@ future completed, which is the executor thread. ## Shutdown -`moq::shutdown()` stops the `moq-ffi` runtime thread, then the executor. +`moq::shutdown()` stops the `moq-ffi` runtime workers, then the executor. Pending calls resolve `Cancelled`, and every object stays safe to drop. Call it once before a plugin or engine module unloads, from a thread that is not running a continuation, so no thread is left calling into unmapped code. A @@ -192,3 +192,9 @@ Everything else maps one to one onto the header is the reference; every method carries its doc comment. - Source: [`cpp/moq`](https://github.com/moq-dev/moq/tree/main/cpp/moq); `just cpp check` builds, installs, and tests it locally + +Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks +can arrive concurrently from different worker threads; marshal UI work onto your +host runtime. The process shutdown hook waits for workers and in-flight callbacks, +including blocking native tasks, before returning. Invoke it from a host thread, +never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 6cc48d322c5..29652b03a68 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -78,3 +78,9 @@ one to one; the API reference has the names. - API reference: [pub.dev/documentation/moq](https://pub.dev/documentation/moq/latest/) - Source: [`dart/`](https://github.com/moq-dev/moq/tree/main/dart) - Packages: [moq](https://pub.dev/packages/moq), [moq\_ffi](https://pub.dev/packages/moq_ffi) + +Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks +can arrive concurrently from different worker threads; marshal UI work onto your +host runtime. The process shutdown hook waits for workers and in-flight callbacks, +including blocking native tasks, before returning. Invoke it from a host thread, +never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 4426728b382..497d9047ca2 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -105,3 +105,9 @@ one to one; the API reference has the names. - API reference: [pkg.go.dev/moq.dev/moq](https://pkg.go.dev/moq.dev/moq) - Source: [`go/`](https://github.com/moq-dev/moq/tree/main/go); `just go check` builds and tests locally - Mirrors the vanity path resolves to: [moq-dev/moq-go](https://github.com/moq-dev/moq-go) (wrapper), [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) (raw bindings and static libraries) + +Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks +can arrive concurrently from different worker threads; marshal UI work onto your +host runtime. The process shutdown hook waits for workers and in-flight callbacks, +including blocking native tasks, before returning. Invoke it from a host thread, +never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 76ff144d80f..86dd46a7478 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -81,3 +81,9 @@ one to one; the API reference has the names. - API reference: [javadoc.io/doc/dev.moq/moq](https://javadoc.io/doc/dev.moq/moq) - Source: [`kt/`](https://github.com/moq-dev/moq/tree/main/kt); `just kt check` builds and tests locally - Artifacts: [dev.moq:moq](https://central.sonatype.com/artifact/dev.moq/moq), [dev.moq:moq-ffi](https://central.sonatype.com/artifact/dev.moq/moq-ffi) + +Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks +can arrive concurrently from different worker threads; marshal UI work onto your +host runtime. The process shutdown hook waits for workers and in-flight callbacks, +including blocking native tasks, before returning. Invoke it from a host thread, +never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 402ffc3ed01..083e7c8cc6a 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -100,3 +100,9 @@ one to one; the API reference has the names. - API reference: [moq-rs.readthedocs.io](https://moq-rs.readthedocs.io) - Source and examples: [`py/moq-rs`](https://github.com/moq-dev/moq/tree/main/py/moq-rs) - Raw bindings: [`moq-ffi`](https://pypi.org/project/moq-ffi/) on PyPI, for the unwrapped API + +Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks +can arrive concurrently from different worker threads; marshal UI work onto your +host runtime. The process shutdown hook waits for workers and in-flight callbacks, +including blocking native tasks, before returning. Invoke it from a host thread, +never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index d8c52caf79f..b497154f027 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -82,3 +82,9 @@ one to one; the API reference has the names. - API reference: [Swift Package Index (DocC)](https://swiftpackageindex.com/moq-dev/moq-swift/documentation/moq) - Source: [`swift/`](https://github.com/moq-dev/moq/tree/main/swift); `just swift check` builds and tests on a Mac - Packages SPM resolves: [moq-dev/moq-swift](https://github.com/moq-dev/moq-swift), [moq-dev/moq-swift-ffi](https://github.com/moq-dev/moq-swift-ffi) + +Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks +can arrive concurrently from different worker threads; marshal UI work onto your +host runtime. The process shutdown hook waits for workers and in-flight callbacks, +including blocking native tasks, before returning. Invoke it from a host thread, +never from a native callback. Async calls polled by the host still run in place. diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md index fb84b4c03dc..a7c49f47597 100644 --- a/quest/m1/ffi-runtime.md +++ b/quest/m1/ffi-runtime.md @@ -9,6 +9,12 @@ the parallelism their own runtimes already have. ## Plan +Draft implementation changes the runtime and joins its workers at shutdown. +Remaining evidence: controlled single-CPU/many-CPU binding publisher throughput, +and macOS/JVM/Dart binding-suite runs. Keep this quest until that evidence is +recorded; successful cross-language interop alone does not establish scaling. + + Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that added this quest): diff --git a/rs/moq-ffi/src/ffi.rs b/rs/moq-ffi/src/ffi.rs index a92cd5b7079..499269ef017 100644 --- a/rs/moq-ffi/src/ffi.rs +++ b/rs/moq-ffi/src/ffi.rs @@ -3,15 +3,14 @@ use std::sync::Arc; use crate::error::MoqError; -/// A dedicated runtime thread, which drives the I/O and timers every call registers and runs -/// the background work spawned onto it. +/// A worker runtime driving I/O, timers, and background work beside host-polled calls. /// /// wasm32 has neither threads nor a tokio driver. uniffi's `RustFuture` is polled by the /// JS event loop instead. #[cfg(not(target_arch = "wasm32"))] static RUNTIME: std::sync::OnceLock = std::sync::OnceLock::new(); -/// The runtime thread and the handle every call spawns onto. +/// The worker runtime and the owner thread that joins it on shutdown. #[cfg(not(target_arch = "wasm32"))] pub(crate) struct Runtime { handle: tokio::runtime::Handle, @@ -54,8 +53,14 @@ impl std::ops::Deref for Runtime { /// The runtime, started on first use. #[cfg(not(target_arch = "wasm32"))] pub(crate) fn runtime() -> &'static Runtime { - RUNTIME.get_or_init(|| { - let runtime = tokio::runtime::Builder::new_current_thread() + RUNTIME.get_or_init(Runtime::new) +} + +#[cfg(not(target_arch = "wasm32"))] +impl Runtime { + fn new() -> Self { + let runtime = tokio::runtime::Builder::new_multi_thread() + .thread_name("moq-ffi-worker") .enable_all() .build() .unwrap(); @@ -68,9 +73,8 @@ pub(crate) fn runtime() -> &'static Runtime { // `Err` when the sender is dropped, which the shutdown never does; either way the // runtime is torn down here, on the thread that ran its tasks. let _ = runtime.block_on(stopped); - // Not `drop`: that would wait for any blocking pool thread, and a DNS lookup - // mid-flight at process exit is not worth waiting for. - runtime.shutdown_background(); + // Join every worker and blocking task before the host can unload callbacks. + drop(runtime); }) .expect("failed to spawn runtime thread"); @@ -81,26 +85,37 @@ pub(crate) fn runtime() -> &'static Runtime { polls: Default::default(), idle: Default::default(), } - }) + } } -/// Stop the runtime thread and wait for it to finish; a no-op when it never started. +/// Stop the runtime workers and wait for them to finish; a no-op when it never started. /// /// See [`crate::moq_ffi_shutdown`] for what this is for. #[cfg(not(target_arch = "wasm32"))] pub(crate) fn shutdown() { let Some(runtime) = RUNTIME.get() else { return }; - 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(); + runtime.shutdown(); +} + +#[cfg(not(target_arch = "wasm32"))] +impl Runtime { + fn shutdown(&self) { + let runtime = self; + let mut owner = runtime.thread.lock().unwrap(); + let Some(thread) = owner.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(()); + thread.join.join().expect("runtime owner panicked"); + // Retain the owner lock until the join completes, including concurrent shutdown calls. + drop(owner); + } } /// Resolves once [`shutdown`] has run. @@ -357,8 +372,7 @@ 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, 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. + /// runtime workers, whose entered reactor unregisters the state it drops. 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 @@ -389,6 +403,35 @@ mod tests { use super::*; + #[test] + fn runtime_uses_parallel_workers() { + let runtime = Runtime::new(); + assert_eq!(runtime.runtime_flavor(), tokio::runtime::RuntimeFlavor::MultiThread); + runtime.shutdown(); + } + + #[test] + fn shutdown_joins_a_worker_callback() { + let runtime = Arc::new(Runtime::new()); + let (entered, entering) = std::sync::mpsc::channel(); + let (release, released) = std::sync::mpsc::channel(); + let (finished, finishing) = std::sync::mpsc::channel(); + runtime.spawn(async move { + entered.send(()).unwrap(); + released.recv().unwrap(); + finished.send(()).unwrap(); + }); + entering.recv().unwrap(); + let owner = runtime.clone(); + let shutdown = std::thread::spawn(move || owner.shutdown()); + release.send(()).unwrap(); + shutdown.join().unwrap(); + finishing + .try_recv() + .expect("shutdown returned with a callback in flight"); + runtime.shutdown(); + } + /// A state that reports its own drop, which is what a terminal cancel has to trigger. struct Tracked(Option>); diff --git a/rs/moq-ffi/src/lib.rs b/rs/moq-ffi/src/lib.rs index d1a44519b8b..a2b9236250f 100644 --- a/rs/moq-ffi/src/lib.rs +++ b/rs/moq-ffi/src/lib.rs @@ -38,19 +38,19 @@ pub mod video; uniffi::setup_scaffolding!("moq"); -/// Stop the runtime thread before the host runtime goes away. +/// Stop the runtime workers before the host runtime goes away. /// /// Every task is dropped, so a call parked on the runtime resolves `Cancelled` and so does any /// later one; the handles stay safe to use and drop. This is for process exit, not a reset. /// -/// It exists because the runtime thread calls back into the host to wake an awaiting future, +/// It exists because the runtime workers calls back into the host to wake an awaiting future, /// and CPython (before 3.14) terminates a foreign thread that touches the interpreter once /// finalization has begun, by `pthread_exit`, whose forced unwind cannot pass through Rust /// frames and aborts the process. The Python binding calls this from `atexit`, which runs -/// before finalization, so the thread finishes its current callback and never starts another. +/// before finalization, so every worker finishes its current callback and never starts another. /// A plain C symbol rather than a uniffi export: no other binding kills threads this way. /// -/// Call it from a host thread. A callback running on the runtime thread would wait on itself. +/// Call it from a host thread. A callback running on the runtime workers would wait on itself. #[cfg(not(target_arch = "wasm32"))] #[unsafe(no_mangle)] pub extern "C" fn moq_ffi_shutdown() { From e28c3288f44f7928cf5c58d84e4479f43b5f0d87 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 10 Oct 2026 19:40:28 -0700 Subject: [PATCH 3/4] Validate binding worker runtime and benchmark publisher fanout Co-Authored-By: GPT-6 Astra --- .github/workflows/nightly.yml | 4 + bench/README.md | 14 ++++ cpp/moq/include/moq/moq.hpp | 2 +- doc/lib/cpp/index.md | 14 ++-- doc/lib/dart/index.md | 13 +-- doc/lib/go/index.md | 13 +-- doc/lib/kt/index.md | 13 +-- doc/lib/py/index.md | 13 +-- doc/lib/swift/index.md | 13 +-- go/justfile | 5 ++ go/wrapper/runtime_bench_test.go | 138 +++++++++++++++++++++++++++++++ py/moq-ffi/moq_ffi/__init__.py | 4 +- quest/m1/README.md | 1 - quest/m1/ffi-runtime.md | 63 -------------- quest/m1/spinning-loops.md | 2 +- quest/m1/time/crate.md | 2 +- quest/m2/kt-jvm-exit.md | 4 +- rs/moq-ffi/src/ffi.rs | 2 +- rs/moq-ffi/src/lib.rs | 4 +- rs/moq-ffi/src/server.rs | 2 +- sh/go/bench.sh | 9 ++ 21 files changed, 224 insertions(+), 111 deletions(-) create mode 100644 go/wrapper/runtime_bench_test.go delete mode 100644 quest/m1/ffi-runtime.md create mode 100755 sh/go/bench.sh diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 27c99aa9cc9..55257ccb48d 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -83,6 +83,10 @@ jobs: env: NEXTEST_PROFILE: ci + - name: Go publisher runtime benchmark + if: ${{ !cancelled() }} + run: nix develop --command just go bench -benchtime=1x + - name: Audio grouping relay benchmark if: ${{ !cancelled() }} run: nix develop --command just bench-audio diff --git a/bench/README.md b/bench/README.md index 2ed1eb44aa3..f020fc8d00f 100644 --- a/bench/README.md +++ b/bench/README.md @@ -68,3 +68,17 @@ work. Benchmark output is informational and machine-specific. Crashes, zero delivery, and invalid samples still fail the command. + +Measure delivered payload through the Go bindings and a local QUIC relay: + +```bash +nix develop --command just go bench -benchtime=3s -count=3 +``` + +This independently sweeps 1/4 publishers and 1/4 subscribers per publisher, +checks every received payload, and acknowledges each batch before publishing the +next. Reported MB/s counts delivery to every subscriber. The optimized native +library, relay and clients share the process, so pin the benchmark process with +`taskset` to compare one CPU with multiple CPUs. Compare identical CPU sets and +traffic shapes across revisions; the nightly smoke runs each shape once without +a timing threshold. diff --git a/cpp/moq/include/moq/moq.hpp b/cpp/moq/include/moq/moq.hpp index 26e2103406b..92075cef5b3 100644 --- a/cpp/moq/include/moq/moq.hpp +++ b/cpp/moq/include/moq/moq.hpp @@ -180,7 +180,7 @@ inline void set_executor(Executor executor, std::function shutdown) noex ::uniffi::set_async_dispatcher(std::move(executor), std::move(shutdown)); } -// Stops the moq-ffi runtime thread, then the executor, before the process or module goes away. +// Stops the moq-ffi runtime workers, then the executor, before the process or module goes away. // Pending calls resolve Cancelled. Call it once from a thread that is not running a continuation. inline void shutdown() noexcept { moq_ffi_shutdown(); diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index efad8976c55..f74dd0ff093 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -148,6 +148,14 @@ auto continuation = std::move(reading).then(moq::inline_executor, [](moq::expect auto frame = co_await media->next(); ``` +## Runtime + +Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the +host still poll in place; independent native wake callbacks can run concurrently. +The configured executor dispatches continuations. Call `moq::shutdown()` from a +host thread before unloading the module; it joins native workers and then the +executor. Never call shutdown from a continuation. + ## Executor Futures are polled, and continuations run, on one process-wide executor @@ -192,9 +200,3 @@ Everything else maps one to one onto the header is the reference; every method carries its doc comment. - Source: [`cpp/moq`](https://github.com/moq-dev/moq/tree/main/cpp/moq); `just cpp check` builds, installs, and tests it locally - -Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks -can arrive concurrently from different worker threads; marshal UI work onto your -host runtime. The process shutdown hook waits for workers and in-flight callbacks, -including blocking native tasks, before returning. Invoke it from a host thread, -never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 29652b03a68..8c5a199f9ea 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -73,14 +73,15 @@ one to one; the API reference has the names. - **Closing.** `await moq.close()` or `session.shutdown()` gives finished tracks up to one second to deliver and fails if they did not. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Cancelling a stream subscription releases its native cursor. - **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. +## Runtime + +Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the +host still poll in place; independent native wake callbacks can run concurrently. +The generated bindings deliver native wakeups to the Dart isolate. Keep UI work +on its owning isolate. + ## Reference - API reference: [pub.dev/documentation/moq](https://pub.dev/documentation/moq/latest/) - Source: [`dart/`](https://github.com/moq-dev/moq/tree/main/dart) - Packages: [moq](https://pub.dev/packages/moq), [moq\_ffi](https://pub.dev/packages/moq_ffi) - -Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks -can arrive concurrently from different worker threads; marshal UI work onto your -host runtime. The process shutdown hook waits for workers and in-flight callbacks, -including blocking native tasks, before returning. Invoke it from a host thread, -never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 497d9047ca2..782958ac4fa 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -100,14 +100,15 @@ one to one; the API reference has the names. - **Closing.** `client.Close()` gives finished tracks up to one second to deliver and returns an error if they did not. `session.Shutdown(ctx)` does the same, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. - **Stats.** `Session().Stats()` reports `RTT`, `EstimatedSendRateBps`, `EstimatedRecvRateBps`, and the byte and packet counters (`BytesSent`, `BytesReceived`, `BytesLost`, `PacketsSent`, `PacketsReceived`, `PacketsLost`). A field is nil when the transport does not report it, which is not the same as zero. +## Runtime + +Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the +host still poll in place; independent native wake callbacks can run concurrently. +The generated bridge synchronizes wakeups before resuming the awaiting goroutine. +Application goroutines remain responsible for serializing their own shared state. + ## Reference - API reference: [pkg.go.dev/moq.dev/moq](https://pkg.go.dev/moq.dev/moq) - Source: [`go/`](https://github.com/moq-dev/moq/tree/main/go); `just go check` builds and tests locally - Mirrors the vanity path resolves to: [moq-dev/moq-go](https://github.com/moq-dev/moq-go) (wrapper), [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) (raw bindings and static libraries) - -Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks -can arrive concurrently from different worker threads; marshal UI work onto your -host runtime. The process shutdown hook waits for workers and in-flight callbacks, -including blocking native tasks, before returning. Invoke it from a host thread, -never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 86dd46a7478..79f60733cbb 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -76,14 +76,15 @@ one to one; the API reference has the names. - **Closing.** Suspending `moq.shutdown()` gives finished tracks up to one second to deliver and throws if they did not. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first. - **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. +## Runtime + +Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the +host still poll in place; independent native wake callbacks can run concurrently. +The generated bindings resume Kotlin coroutines through their dispatcher. Use +the UI dispatcher when updating UI state. + ## Reference - API reference: [javadoc.io/doc/dev.moq/moq](https://javadoc.io/doc/dev.moq/moq) - Source: [`kt/`](https://github.com/moq-dev/moq/tree/main/kt); `just kt check` builds and tests locally - Artifacts: [dev.moq:moq](https://central.sonatype.com/artifact/dev.moq/moq), [dev.moq:moq-ffi](https://central.sonatype.com/artifact/dev.moq/moq-ffi) - -Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks -can arrive concurrently from different worker threads; marshal UI work onto your -host runtime. The process shutdown hook waits for workers and in-flight callbacks, -including blocking native tasks, before returning. Invoke it from a host thread, -never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 083e7c8cc6a..993703b4cd6 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -95,14 +95,15 @@ one to one; the API reference has the names. - **Closing.** `await session.shutdown()` gives finished tracks up to one second to deliver and raises if they did not. `cancel(code)` closes at once. Finish or abort live tracks first. - **Stats.** `session.stats()` reports `rtt`, `estimated_send_rate_bps`, `estimated_recv_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). A field is `None` when the transport does not report it, which is not the same as zero. +## Runtime + +Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the +host still poll in place; independent native wake callbacks can run concurrently. +The generated bindings wake Python futures through the asyncio event loop. The +package exit hook joins native workers before interpreter finalization. + ## Reference - API reference: [moq-rs.readthedocs.io](https://moq-rs.readthedocs.io) - Source and examples: [`py/moq-rs`](https://github.com/moq-dev/moq/tree/main/py/moq-rs) - Raw bindings: [`moq-ffi`](https://pypi.org/project/moq-ffi/) on PyPI, for the unwrapped API - -Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks -can arrive concurrently from different worker threads; marshal UI work onto your -host runtime. The process shutdown hook waits for workers and in-flight callbacks, -including blocking native tasks, before returning. Invoke it from a host thread, -never from a native callback. Async calls polled by the host still run in place. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index b497154f027..23d9c6d7263 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -77,14 +77,15 @@ one to one; the API reference has the names. - **Closing.** `try await session.shutdown()` gives finished tracks up to one second to deliver and throws if they did not. `session.cancel(code:)` closes at once. Finish or abort live tracks first. - **Stats.** `session.stats()` reports `rttUs`, `estimatedSendRateBps`, `estimatedRecvRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `nil` when the transport does not report it, which is not the same as zero. +## Runtime + +Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the +host still poll in place; independent native wake callbacks can run concurrently. +The generated bindings resume Swift continuations. Use the appropriate actor +when updating UI state. + ## Reference - API reference: [Swift Package Index (DocC)](https://swiftpackageindex.com/moq-dev/moq-swift/documentation/moq) - Source: [`swift/`](https://github.com/moq-dev/moq/tree/main/swift); `just swift check` builds and tests on a Mac - Packages SPM resolves: [moq-dev/moq-swift](https://github.com/moq-dev/moq-swift), [moq-dev/moq-swift-ffi](https://github.com/moq-dev/moq-swift-ffi) - -Native I/O and background tasks run on a Tokio worker pool. UniFFI wake callbacks -can arrive concurrently from different worker threads; marshal UI work onto your -host runtime. The process shutdown hook waits for workers and in-flight callbacks, -including blocking native tasks, before returning. Invoke it from a host thread, -never from a native callback. Async calls polled by the host still run in place. diff --git a/go/justfile b/go/justfile index b4fa2d0d07c..9f12d207c21 100644 --- a/go/justfile +++ b/go/justfile @@ -48,3 +48,8 @@ publish-ffi *args: [positional-arguments] publish-wrapper *args: {{ quote(justfile_directory() / "sh/go/publish-wrapper.sh") }} "$@" + +# Measure delivered QUIC payload across independent publisher/subscriber counts. +[positional-arguments] +bench *args: + bash ../sh/go/bench.sh "$@" diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go new file mode 100644 index 00000000000..606c17343b1 --- /dev/null +++ b/go/wrapper/runtime_bench_test.go @@ -0,0 +1,138 @@ +package moq_test + +import ( + "bytes" + "context" + "fmt" + "testing" + "time" + + "moq.dev/moq" +) + +// BenchmarkPublisher measures delivered payload through real QUIC sessions and +// generated Go callbacks. Each round waits for every subscriber, so dropping +// groups or merely buffering writes cannot improve the reported throughput. +func BenchmarkPublisher(b *testing.B) { + for _, publishers := range []int{1, 4} { + for _, subscribers := range []int{1, 4} { + b.Run(fmt.Sprintf("publishers=%d/subscribers=%d", publishers, subscribers), func(b *testing.B) { + ctx, cancel := context.WithCancel(context.Background()) + server, err := moq.Listen(ctx, "127.0.0.1:0", moq.WithTLSGenerate("localhost")) + if err != nil { + cancel() + b.Fatal(err) + } + served := make(chan error, 1) + go func() { served <- server.Serve(ctx) }() + b.Cleanup(func() { cancel(); _ = server.Close(); <-served }) + url := "https://" + server.LocalAddr() + dial := func() *moq.Client { + client, err := moq.Dial(ctx, url, moq.WithTLSVerify(false)) + if err != nil { + b.Fatal(err) + } + b.Cleanup(func() { _ = client.Close() }) + return client + } + tracks := make([]*moq.TrackProducer, publishers) + consumers := make([]*moq.TrackConsumer, 0, publishers*subscribers) + for p := range tracks { + client := dial() + name := fmt.Sprintf("runtime/%d", p) + broadcast, err := client.CreateBroadcast(name) + if err != nil { + b.Fatal(err) + } + b.Cleanup(func() { _ = broadcast.Close() }) + tracks[p], err = broadcast.PublishTrack("payload", nil) + if err != nil { + b.Fatal(err) + } + if err := broadcast.Announce(moq.Route{}); err != nil { + b.Fatal(err) + } + for s := 0; s < subscribers; s++ { + subscriber := dial() + announced, err := subscriber.AnnouncedBroadcast(name) + if err != nil { + b.Fatal(err) + } + b.Cleanup(announced.Cancel) + remote, err := announced.Available(ctx) + if err != nil { + b.Fatal(err) + } + consumer, err := remote.SubscribeTrack(ctx, "payload", nil) + if err != nil { + b.Fatal(err) + } + b.Cleanup(consumer.Cancel) + consumers = append(consumers, consumer) + } + } + const frames = 64 + payload := bytes.Repeat([]byte{0x5a}, 1024) + b.SetBytes(int64(publishers * subscribers * frames * len(payload))) + b.ResetTimer() + for n := 0; n < b.N; n++ { + done := make(chan error, len(tracks)+len(consumers)) + for _, consumer := range consumers { + go func(consumer *moq.TrackConsumer) { + group, err := consumer.RecvGroup(ctx) + if err != nil { + done <- err + return + } + if group == nil { + done <- fmt.Errorf("track ended before batch") + return + } + defer group.Cancel() + for f := 0; f < frames; f++ { + frame, err := group.ReadFrame(ctx) + if err != nil { + done <- err + return + } + if frame == nil || !bytes.Equal(frame.Payload, payload) { + done <- fmt.Errorf("missing or corrupt frame") + return + } + } + done <- nil + }(consumer) + } + for _, track := range tracks { + go func(track *moq.TrackProducer) { + group, err := track.AppendGroup() + if err != nil { + done <- err + return + } + for f := 0; f < frames; f++ { + if err := group.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(time.Duration(n*frames+f) * time.Millisecond)}); err != nil { + done <- err + return + } + } + done <- group.Finish() + }(track) + } + var failure error + for range len(tracks) + len(consumers) { + if err := <-done; err != nil { + if failure == nil { + failure = err + } + cancel() + } + } + if failure != nil { + b.Fatal(failure) + } + } + }) + } + } +} diff --git a/py/moq-ffi/moq_ffi/__init__.py b/py/moq-ffi/moq_ffi/__init__.py index d8a7758115b..c4e54479d5c 100644 --- a/py/moq-ffi/moq_ffi/__init__.py +++ b/py/moq-ffi/moq_ffi/__init__.py @@ -13,11 +13,11 @@ from ._uniffi import * # noqa: F401,F403 from ._uniffi.moq import _UniffiLib -# The Rust runtime thread resumes every awaiting coroutine through a ctypes +# Rust runtime workers wake awaiting coroutines through a ctypes # callback, and CPython (before 3.14) kills a foreign thread that touches the # interpreter once finalization has begun: pthread_exit, whose unwind aborts in # Rust. atexit runs before finalization, after the program's own handlers, so -# stop the thread here. Calls after this point resolve as cancelled. +# join the workers here. Calls after this point resolve as cancelled. _UniffiLib.moq_ffi_shutdown.argtypes = () _UniffiLib.moq_ffi_shutdown.restype = None atexit.register(_UniffiLib.moq_ffi_shutdown) diff --git a/quest/m1/README.md b/quest/m1/README.md index 449a8fcf84d..a240bc3be25 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -69,7 +69,6 @@ bench all require its crate. - [IETF request headers](/quest/m1/ietf-dispatch-headers.md) - each bidi request reads its header in its own task, so a slow one never blocks the next - [END_OF_TRACK placement](/quest/m1/ietf-end-of-track-placement.md) - END_OF_TRACK rides the upstream's Location, and Rust's header stops claiming END_OF_GROUP - [moq-uring tests under load](/quest/m1/uring-tests-under-load.md) - uring tests pass while parallel checks share locked memory -- [FFI runtime](/quest/m1/ffi-runtime.md) - moq-ffi drives moq on a multi-thread runtime instead of one thread - [Audio group duration](/quest/m1/audio-group-duration.md) - audio groups span at least 20 ms by default, so small frames don't mint a group each - [Pipelined requests](/quest/m1/pipeline-requests/README.md) - SUBSCRIBE and the first FETCH go out with the track-info request at every hop, so first data arrives a round trip sooner per hop - [Lazy discovery](/quest/m1/lazy-discovery/README.md) - a `consume` session requests announcements only for prefixes the origin is watching, in JS then Rust; `follow`, `broadcasts`, and the `discovery` option go away diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md deleted file mode 100644 index a7c49f47597..00000000000 --- a/quest/m1/ffi-runtime.md +++ /dev/null @@ -1,63 +0,0 @@ -# [S] FFI apps run on more than one thread - -## Goal - -moq-ffi drives moq on a multi-thread tokio runtime instead of one -`current_thread` runtime thread, so noq's endpoint and connection drivers -run beside a busy session, and Go, Python, Swift, Kotlin, and Dart apps get -the parallelism their own runtimes already have. - -## Plan - -Draft implementation changes the runtime and joins its workers at shutdown. -Remaining evidence: controlled single-CPU/many-CPU binding publisher throughput, -and macOS/JVM/Dart binding-suite runs. Keep this quest until that evidence is -recorded; successful cross-language interop alone does not establish scaling. - - -Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that -added this quest): - -- Today `runtime()` in `rs/moq-ffi/src/ffi.rs` builds - `new_current_thread().enable_all()` on one dedicated `moq-ffi` thread. - Everything shares it: noq's - endpoint and connection drivers, the moq-tokio reconnect loop, the session - driver, and the origin driver. The pattern was copied from libmoq (#732, - #1071) with no stated reason. -- Use `new_multi_thread().enable_all()` with tokio's default worker count. - 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. -- `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 - the server's accept loop 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. - Document that in `doc/lib/` and audit binding code that assumes serialized - callbacks. -- Shutdown keeps its meaning: when `moq_ffi_shutdown` returns, - no task runs and no callback into the host is in flight, so Python's - `atexit` and JVM exit stay clean. `shutdown_background()` no longer gives - that with N workers; the shutdown must wait for them. -- Decided 2026-10-08: moq-ffi only. The - [generated C bindings](/quest/m1/c/README.md) sit on moq-ffi and inherit - it; the hand-written `rs/moq-c` stays untouched until it is - [retired](/quest/m1/c/retire.md), so effort there is wasted. -- Watch [Kotlin/JVM exit](/quest/m2/kt-jvm-exit.md), which depends on how the - runtime thread stops. -- Test: the interop go and python publishers on a pinned single CPU and on - many, and every binding's test suite. Benchmark a binding publisher's - throughput before and after. - -Public API: callbacks may fire concurrently on any runtime thread -(documented); no signature changes. Wire: none. - -## Related - -- [Kotlin/JVM exit](/quest/m2/kt-jvm-exit.md) - runtime-thread shutdown -- [Generated C bindings](/quest/m1/c/README.md) - inherits the moq-ffi runtime, so hand-written moq-c needs no change diff --git a/quest/m1/spinning-loops.md b/quest/m1/spinning-loops.md index 86fe5d96b51..14b8958486a 100644 --- a/quest/m1/spinning-loops.md +++ b/quest/m1/spinning-loops.md @@ -39,4 +39,4 @@ Decided 2026-10-09 while reworking #5088: ## Related - [Session burst hang](/quest/m1/session-burst-hang.md) - the same bench shapes that hang -- [FFI runtime](/quest/m1/ffi-runtime.md) - FFI apps run on more than one thread +- [FFI runtime](https://github.com/moq-dev/moq/pull/5265) - FFI apps run on more than one thread diff --git a/quest/m1/time/crate.md b/quest/m1/time/crate.md index 353fb70481d..42536af0480 100644 --- a/quest/m1/time/crate.md +++ b/quest/m1/time/crate.md @@ -33,7 +33,7 @@ Settle in the PR: consumer needs otherwise). - How the tokio backend reports a logical instant: an origin captured once per runtime, so paused tokio stays deterministic, and the multi-thread runtime - [FFI runtime](/quest/m1/ffi-runtime.md) moves to stays correct. + [FFI runtime](https://github.com/moq-dev/moq/pull/5265) moves to stays correct. - The browser backend reuses web-async's wasmtimer plumbing rather than a new shim. - The sim keeps everything moq-net relies on today: stall-driven advance, diff --git a/quest/m2/kt-jvm-exit.md b/quest/m2/kt-jvm-exit.md index 2ea4eb025dc..c73fb0fe8ab 100644 --- a/quest/m2/kt-jvm-exit.md +++ b/quest/m2/kt-jvm-exit.md @@ -12,7 +12,7 @@ out of scope: it kills the process rather than destroying the VM. ## Plan Decided 2026-10-08: plan for any runtime worker thread, not one runtime -thread, since [FFI runtime](/quest/m1/ffi-runtime.md) moves moq-ffi to a +thread, since [FFI runtime](https://github.com/moq-dev/moq/pull/5265) moves moq-ffi to a worker pool. - Audit first. uniffi delivers async continuations as JNA callbacks @@ -41,4 +41,4 @@ Public API: none; the hook is internal to the binding. Wire: none. ## Related -- [FFI runtime](/quest/m1/ffi-runtime.md) - moves moq-ffi to a multi-thread runtime, so callbacks fire on any worker thread +- [FFI runtime](https://github.com/moq-dev/moq/pull/5265) - moves moq-ffi to a multi-thread runtime, so callbacks fire on any worker thread diff --git a/rs/moq-ffi/src/ffi.rs b/rs/moq-ffi/src/ffi.rs index 499269ef017..fde2802d29b 100644 --- a/rs/moq-ffi/src/ffi.rs +++ b/rs/moq-ffi/src/ffi.rs @@ -71,7 +71,7 @@ impl Runtime { .name("moq-ffi".into()) .spawn(move || { // `Err` when the sender is dropped, which the shutdown never does; either way the - // runtime is torn down here, on the thread that ran its tasks. + // runtime is torn down here, joining the threads that ran its tasks. let _ = runtime.block_on(stopped); // Join every worker and blocking task before the host can unload callbacks. drop(runtime); diff --git a/rs/moq-ffi/src/lib.rs b/rs/moq-ffi/src/lib.rs index a2b9236250f..e0c2a5f12e7 100644 --- a/rs/moq-ffi/src/lib.rs +++ b/rs/moq-ffi/src/lib.rs @@ -43,14 +43,14 @@ uniffi::setup_scaffolding!("moq"); /// Every task is dropped, so a call parked on the runtime resolves `Cancelled` and so does any /// later one; the handles stay safe to use and drop. This is for process exit, not a reset. /// -/// It exists because the runtime workers calls back into the host to wake an awaiting future, +/// It exists because the runtime workers call back into the host to wake an awaiting future, /// and CPython (before 3.14) terminates a foreign thread that touches the interpreter once /// finalization has begun, by `pthread_exit`, whose forced unwind cannot pass through Rust /// frames and aborts the process. The Python binding calls this from `atexit`, which runs /// before finalization, so every worker finishes its current callback and never starts another. /// A plain C symbol rather than a uniffi export: no other binding kills threads this way. /// -/// Call it from a host thread. A callback running on the runtime workers would wait on itself. +/// Call it from a host thread. A callback running on a runtime worker would wait on itself. #[cfg(not(target_arch = "wasm32"))] #[unsafe(no_mangle)] pub extern "C" fn moq_ffi_shutdown() { diff --git a/rs/moq-ffi/src/server.rs b/rs/moq-ffi/src/server.rs index dba396f614a..eb41ba479f0 100644 --- a/rs/moq-ffi/src/server.rs +++ b/rs/moq-ffi/src/server.rs @@ -80,7 +80,7 @@ impl Listening { /// Stop the accept loop and block until the listener's sockets are released. /// /// Waits on a std channel so it works from inside another runtime, but must not run on - /// the FFI runtime thread, which the loop needs. + /// an FFI runtime worker, which the accept loop may need. fn close(self) { drop(self.stop); // Disconnects when the loop finishes, or when the runtime is gone and dropped it. diff --git a/sh/go/bench.sh b/sh/go/bench.sh new file mode 100755 index 00000000000..af274ae4292 --- /dev/null +++ b/sh/go/bench.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +set -euo pipefail +here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +root=$(cd "$here/../.." && pwd) +export MOQ_FFI_PROFILE=release +staged=$(bash "$here/stage.sh" --output "$root/dist/runtime-bench") +wrapper=$(printf '%s\n' "$staged" | sed -n 2p) +cd "$wrapper" +CGO_ENABLED=1 GOFLAGS=-mod=mod go test -run '^$' -bench '^BenchmarkPublisher$' "$@" From b0ef5deeaedad0362287bfdf16c8e7a2571fee47 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 11 Oct 2026 10:32:34 -0700 Subject: [PATCH 4/4] Address review: C++ executor docs, frame identity, concurrent shutdown test Separate C++ future polling (the configured executor) from then() continuation dispatch. Check each benchmark frame's timestamp so a duplicate cannot mask a missing frame. Hold the callback until shutdown has flagged the stop, and add a second concurrent shutdown caller that must also wait for the callback. Co-Authored-By: Claude Opus 5.5 --- cpp/moq/README.md | 2 +- doc/lib/cpp/index.md | 17 ++++++------ go/wrapper/runtime_bench_test.go | 5 ++-- rs/moq-ffi/src/ffi.rs | 45 ++++++++++++++++++++++++++------ 4 files changed, 50 insertions(+), 19 deletions(-) diff --git a/cpp/moq/README.md b/cpp/moq/README.md index 1f3df9149e9..93bade44825 100644 --- a/cpp/moq/README.md +++ b/cpp/moq/README.md @@ -31,7 +31,7 @@ Every generated type lives in `namespace moq`. Objects are `std::shared_ptr`; re - A fallible call returns `moq::expected`, which is `std::expected` on C++23 and a bundled `tl::expected` below it. The generated sources and every includer must agree on which, so `moq/moq.hpp` references a symbol named for the one it sees and `src/moq.cpp` defines the one it was built with: a mismatch fails to link. - An async call returns `moq::Future`. Block on it with `get()` or `wait_for()`, attach a continuation with `std::move(future).then(executor, callback)`, which returns a `moq::Continuation`, or `co_await` it on C++20. - `moq::Error` is a value holding a `std::variant` of its cases, and `to_string()` gives Rust's `Display` message. Nothing throws. A Rust panic aborts with a message on stderr, and so does reading an invalid future (see [Cancellation](#cancellation)). -- Futures are polled and continuations run on one process-wide executor thread unless the application installs its own with `moq::set_executor` before the first async call. `moq::shutdown()` stops the moq-ffi runtime workers (`moq_ffi_shutdown`), then the executor, before unloading the code a continuation could call into. +- Futures are polled on one process-wide executor thread unless the application installs its own with `moq::set_executor` before the first async call. The executor passed to `then()` dispatches only the continuation. `moq::shutdown()` stops the moq-ffi runtime workers (`moq_ffi_shutdown`), then the executor, before unloading the code a continuation could call into. ## C++ standard diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 6392d7331eb..773125b17bf 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -150,17 +150,18 @@ auto frame = co_await media->next(); ## Runtime -Native I/O and background tasks run on a Tokio worker pool. Calls awaited by the -host still poll in place; independent native wake callbacks can run concurrently. -The configured executor dispatches continuations. Call `moq::shutdown()` from a -host thread before unloading the module; it joins native workers and then the -executor. Never call shutdown from a continuation. +Native I/O and background tasks run on a Tokio worker pool. Futures are still +polled on the [executor](#executor), while `get()` and `wait_for()` block the +calling thread; independent native wake callbacks can run concurrently. The +executor passed to `then()` dispatches only the continuation. Call +`moq::shutdown()` from a host thread before unloading the module; it joins +native workers and then the executor. Never call shutdown from a continuation. ## Executor -Futures are polled, and continuations run, on one process-wide executor -thread unless you install your own with `moq::set_executor(executor, -shutdown)` before the first async call. An `Executor` takes a `moq::Task` and +Futures are polled on one process-wide executor thread unless you install your +own with `moq::set_executor(executor, shutdown)` before the first async call. +An `Executor` takes a `moq::Task` and returns true once it has accepted it; `shutdown` stops accepting and returns once no task can still run. A host with its own threads (a game engine) installs one that hops onto them. The executor passed to `then()` is separate: diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index 606c17343b1..26b14335940 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -95,8 +95,9 @@ func BenchmarkPublisher(b *testing.B) { done <- err return } - if frame == nil || !bytes.Equal(frame.Payload, payload) { - done <- fmt.Errorf("missing or corrupt frame") + want := time.Duration(n*frames+f) * time.Millisecond + if frame == nil || frame.Timestamp == nil || *frame.Timestamp != want || !bytes.Equal(frame.Payload, payload) { + done <- fmt.Errorf("missing, reordered, or corrupt frame %d", f) return } } diff --git a/rs/moq-ffi/src/ffi.rs b/rs/moq-ffi/src/ffi.rs index fde2802d29b..1b1a7b6c8cf 100644 --- a/rs/moq-ffi/src/ffi.rs +++ b/rs/moq-ffi/src/ffi.rs @@ -415,20 +415,49 @@ mod tests { let runtime = Arc::new(Runtime::new()); let (entered, entering) = std::sync::mpsc::channel(); let (release, released) = std::sync::mpsc::channel(); - let (finished, finishing) = std::sync::mpsc::channel(); + let finished = Arc::new(std::sync::atomic::AtomicBool::new(false)); + let callback = finished.clone(); runtime.spawn(async move { entered.send(()).unwrap(); released.recv().unwrap(); - finished.send(()).unwrap(); + callback.store(true, std::sync::atomic::Ordering::SeqCst); }); entering.recv().unwrap(); - let owner = runtime.clone(); - let shutdown = std::thread::spawn(move || owner.shutdown()); + + // Each caller reports whether the callback had finished when its shutdown returned. + let shutdown = |runtime: Arc, finished: Arc| { + move || { + runtime.shutdown(); + finished.load(std::sync::atomic::Ordering::SeqCst) + } + }; + + // Wait until the first caller has flagged the stop, so it holds the owner lock and is + // joining the workers while the callback is still held. + let mut stopped = runtime.stopped.subscribe(); + let first = std::thread::spawn(shutdown(runtime.clone(), finished.clone())); + tokio::runtime::Builder::new_current_thread() + .build() + .unwrap() + .block_on(stopped.wait_for(|&stopped| stopped)) + .unwrap(); + + let (started, starting) = std::sync::mpsc::channel(); + let second = std::thread::spawn({ + let shutdown = shutdown(runtime.clone(), finished.clone()); + move || { + started.send(()).unwrap(); + shutdown() + } + }); + starting.recv().unwrap(); + release.send(()).unwrap(); - shutdown.join().unwrap(); - finishing - .try_recv() - .expect("shutdown returned with a callback in flight"); + assert!(first.join().unwrap(), "shutdown returned with a callback in flight"); + assert!( + second.join().unwrap(), + "a concurrent shutdown returned with a callback in flight" + ); runtime.shutdown(); }