diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index a2276a34b68..a98a76d8594 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 a804dfae69b..17db78c1b7b 100644 --- a/bench/README.md +++ b/bench/README.md @@ -96,3 +96,17 @@ Generator CPU is reported beside relay CPU because sharing a loopback host can hide a relay improvement behind generator saturation. CPU efficiency remains withheld until offered load and delivery/loss are comparable. Zero-baseline metrics retain absolute deltas when their percentage ratio is undefined. + +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 frame's payload and timestamp, 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/README.md b/cpp/moq/README.md index ed5e062f83e..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 thread (`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/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 a1fc620b0d4..dab6e5dad41 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -148,11 +148,20 @@ 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. 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: @@ -174,7 +183,7 @@ Obtain a dynamic track request’s `demand()` before accepting it to watch subsc ## 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 diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index f233f0e8939..c1c175edac3 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -75,6 +75,13 @@ one to one; the API reference has the names. - **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. +## 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/) diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index efab8a6c664..450561c11b0 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -102,6 +102,13 @@ one to one; the API reference has the names. - **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder. - **Track demand.** Obtain a dynamic track request’s `Demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. +## 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) diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index fb951be0049..3f96289481e 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -78,6 +78,13 @@ one to one; the API reference has the names. - **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. +## 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) diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 95ebed5e561..b6b68d6e04f 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -97,6 +97,13 @@ one to one; the API reference has the names. - **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. +## 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) diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index f70bf73e053..2de69fe6b05 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -79,6 +79,13 @@ one to one; the API reference has the names. - **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. +## 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) 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..26b14335940 --- /dev/null +++ b/go/wrapper/runtime_bench_test.go @@ -0,0 +1,139 @@ +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 + } + 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 + } + } + 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 e213823fff0..ec23cbf7165 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -70,7 +70,6 @@ session outcomes, and embedder refusals inside session outcomes. - [Test TypeScript check](/quest/m1/test-ts-check.md) - `just check` type-checks the TypeScript harnesses under test/ - [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 - [Plan: a public model](/quest/m1/model-public-surface.md) - every crate-private model item is made public or unnecessary, so a custom publisher or subscriber builds from the public model alone -- [FFI runtime](/quest/m1/ffi-runtime.md) - moq-ffi drives moq on a multi-thread runtime instead of one thread - [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 - [A spinning loop fails a sim test](/quest/m1/spinning-loops.md) - a sim test names any loop that holds a task poll too long, and each one yields through a budget diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md deleted file mode 100644 index fb84b4c03dc..00000000000 --- a/quest/m1/ffi-runtime.md +++ /dev/null @@ -1,57 +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 - -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 9a0797e668d..9b031e909e1 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](https://github.com/moq-dev/moq/pull/5238) - 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 a92cd5b7079..1b1a7b6c8cf 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(); @@ -66,11 +71,10 @@ pub(crate) fn runtime() -> &'static 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); - // 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,64 @@ 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 = Arc::new(std::sync::atomic::AtomicBool::new(false)); + let callback = finished.clone(); + runtime.spawn(async move { + entered.send(()).unwrap(); + released.recv().unwrap(); + callback.store(true, std::sync::atomic::Ordering::SeqCst); + }); + entering.recv().unwrap(); + + // 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(); + 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(); + } + /// 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..e0c2a5f12e7 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 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 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 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$' "$@"