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
4 changes: 4 additions & 0 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 14 additions & 0 deletions bench/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion cpp/moq/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Every generated type lives in `namespace moq`. Objects are `std::shared_ptr`; re
- A fallible call returns `moq::expected<T>`, 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<T>`. 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

Expand Down
2 changes: 1 addition & 1 deletion cpp/moq/include/moq/moq.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ inline void set_executor(Executor executor, std::function<void()> 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();
Expand Down
17 changes: 13 additions & 4 deletions doc/lib/cpp/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand Down
7 changes: 7 additions & 0 deletions doc/lib/go/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions doc/lib/kt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions doc/lib/py/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions doc/lib/swift/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
5 changes: 5 additions & 0 deletions go/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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 "$@"
139 changes: 139 additions & 0 deletions go/wrapper/runtime_bench_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
})
}
}
}
4 changes: 2 additions & 2 deletions py/moq-ffi/moq_ffi/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
57 changes: 0 additions & 57 deletions quest/m1/ffi-runtime.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m1/spinning-loops.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion quest/m1/time/crate.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading
Loading