Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion quest/m1/poll-first/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,4 +75,4 @@ and their alternatives:
## Required

- [Generated async wrappers behind a feature](/quest/m1/poll-first/async-feature.md) - each library's `async fn` wrappers are generated from its `poll_*` signatures and compile only with its `async` feature
- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - moq-ffi, moq-stats, and moq-relay's cluster and auth run as polled `kio::Tasks` children instead of spawned tasks
- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) - moq-ffi, moq-stats, and moq-relay's cluster and auth run as polled `kio::Tasks` children instead of spawned tasks
39 changes: 0 additions & 39 deletions quest/m1/poll-first/no-spawn.md

This file was deleted.

61 changes: 61 additions & 0 deletions quest/m1/poll-first/no-spawn/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Libraries spawn nothing

## Goal

moq-ffi, moq-stats, and moq-relay's cluster and auth decider spawn no tasks:
their background work runs as `kio::Tasks` children that the owner polls,
returned as a handle whose poll drives it. Only the edges spawn a root task:
binaries and the bindings' runtime. moq-relay's in-memory integration tests
(`rs/moq-relay/tests/integration/connection.rs`) run on kio's simulator
instead of paused tokio.

## Plan

Decided with the maintainer on 2026-10-25, replacing the m2 runtime trait
(spawn and time for tokio, browser, io_uring, and sim):

- **Poll everywhere, no spawn.** A spawn trait keeps `'static` detached tasks
in the library, which poll-first rejects; `kio::Tasks` already gives a
library structured children with no runtime. Time is
`kio::clock`, so nothing is left for a runtime trait.
`rs/AGENTS.md` already treats `tokio::spawn` in a library as a smell.
- **No I/O seam.** I/O stays at moq-net's `transport::poll` traits and
moq-sock: tokio's readiness model and io_uring's completion model (the
kernel owns the buffer) can't share a zero-cost API.
- **Blocking work is out of scope.** OS threads for blocking capture, encode,
or file I/O are not async tasks and stay.

✅ **Split into four children** (maintainer, 2026-11-01, D1 on
[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)), landed in the
order of Required below. One PR could not hold them all, and two open PRs
already changed part of the scope:
[moq-dev/moq#7360](https://github.com/moq-dev/moq/pull/7360) (merged
2026-11-01) removed the auth decider loop and returns moq-stats' publisher from
`Producer::new`, and
[moq-dev/moq#7497](https://github.com/moq-dev/moq/pull/7497) rewrites moq-ffi's
`Task` and `Background` plumbing. Each child records its own decisions.

Every child lists any spawn that has to stay, with why, in its PR. Public API:
constructors that spawned return a handle to poll or await instead. Each PR's
Impact section describes migration for the published crates whose API changes.
Wire: none.

These spawns stay and belong to [the spawn audit](/quest/m2/spawn-audit.md):
`Critical`'s ACME renewal (`rs/moq-relay/src/relay.rs`) and web certificate
reload (`rs/moq-relay/src/web.rs`), the io_uring handoff in
`rs/moq-relay/src/connection.rs`, and moq-relay's web, shutdown, and uring
spawns. Each UniFFI call's task on the bindings' runtime stays too: that is the
binding boundary.

## Required

- [Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) - `Cluster::new` returns a `Driver` the relay polls, and the dial loop runs as `kio::Tasks` children
- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - HTTP admissions run inside their waiter, and the stats publisher runs in the cluster's driver
- [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children
- [The relay's in-memory tests run on kio's simulator](/quest/m1/poll-first/no-spawn/sim-tests.md) - `rs/moq-relay/tests/integration/connection.rs` runs on the simulator instead of paused tokio

## Related

- [The remaining spawns](/quest/m2/spawn-audit.md) - the same rule for every other library crate
- [Generated async wrappers](/quest/m1/poll-first/async-feature.md) - the poll-first sibling that gates the async layer
- [Poll-native async in moq-ffi](/quest/m2/ffi-poll-migrate.md) - its PR reworks the moq-ffi task plumbing this epic touches
41 changes: 41 additions & 0 deletions quest/m1/poll-first/no-spawn/admissions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# [S] Admissions and stats are polled

## Goal

moq-relay spawns no task per HTTP admission, and `Cluster::with_stats` spawns
no stats publisher. The `Server` decider's request runs inside the caller that
waits on its answer, and the publisher runs as a child of the cluster's
`Driver`.

## Plan

Spawns in scope on `main` (2026-11-01):

- `rs/moq-relay/src/auth.rs`, `Decider::Server`: one
`tokio::spawn(moq_tokio::panic::isolate(..))` per admission HTTP request.
[moq-dev/moq#7360](https://github.com/moq-dev/moq/pull/7360) (merged
2026-11-01) already removed the decider loop around it.
- `rs/moq-relay/src/cluster.rs`, `Cluster::with_stats`: the stats publisher,
through `Critical`. Since #7360, `moq_stats::Producer::new` returns
`(Producer, Publisher)`, so moq-stats itself spawns nothing.

✅ **The waiter polls the admission** (maintainer, 2026-11-01, D3 on
[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): the caller
waiting on `Answer` polls the `moq_auth::Client` request inline, and dropping
the wait cancels the request, which replaces the `reply.closed()` select. A
panic then ends the session being admitted, the same scope the per-admission
`isolate` gives today. Rejected: one long-lived `kio::Tasks` of admissions
polled by `Relay::run`, which brings back the long-lived decider task that
#7360 removed.

The publisher joins `Driver`, the type
[Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md)
introduces, so a publisher panic still ends the relay. `Publisher::run` is an
`async fn`; giving `Publisher` a `poll` is optional and only worth it if
`Driver` needs it.

Public API: `Cluster::with_stats` no longer needs a tokio runtime. Wire: none.

## Required

- [Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) - provides the `Driver` the publisher joins
52 changes: 52 additions & 0 deletions quest/m1/poll-first/no-spawn/cluster.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# [L] Cluster polls its own work

## Goal

moq-relay's `Cluster` spawns no tasks. `Cluster::new` returns the origin
driver and cache governor as work its owner polls, and `Started::run` drives
every dial, the `api.url` reconciler, and mDNS discovery as `kio::Tasks`
children instead of a tokio `JoinSet` and detached tasks. The relay still exits
with the panic message when a task it cannot serve without panics.

## Plan

Spawns in scope on `main` (2026-11-01), all in `rs/moq-relay/src/cluster.rs`:

- `Cluster::new`: the cache governor and the origin driver, through `Critical`.
- `run_work`: the dial `JoinSet`, the `api.url` reconciler, and mDNS.
- `run_mdns` and `apply_peer_list`: one detached task per peer, tracked by an
`AbortHandle` in `DialMap`. These become a queue into the `run` loop's
`Tasks`, so `DialMap` holds `TaskKey`s.
- `Held::drop`: the close of a LAN dial's client. `Dialers` polls its existing
close set instead.

✅ **`Cluster::new` returns a driver** (maintainer, 2026-11-01, D2 on
[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)):
`Cluster::new(options) -> anyhow::Result<(Cluster, Driver)>`, the same shape as
`origin::Producer::new`. `Relay::run` polls `Driver` next to `Started::run`.
`Driver` catches each child's panic and turns it into an error, so the relay
still exits with "origin driver panicked: ..." the way `Critical` does now.
Tests spawn the driver, because they are edges. Rejected: keeping the signature
and moving the driver into `Started::run`, which breaks `Cluster::new`'s
documented promise that the origin serves sessions whether or not `start` is
ever called. There are about 68 `Cluster::new(` call sites across moq-relay,
moq-cli, the benches, and moq-net's `mesh_withdraw` test.

✅ **Peer dials stop running in parallel** (maintainer, 2026-11-01, D5 on
[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): as `kio::Tasks`
children, every peer dial supervisor runs on the task that polls
`Started::run` instead of its own tokio task. The heavy session I/O is still
spawned inside moq-tokio, which the spawn audit owns, so the cost is probably
small. Measure it once in this PR and report the result.

`Critical` stays for ACME renewal and the web certificate reload, which belong
to the spawn audit; `Cluster::with_stats` keeps spawning the publisher until
[the admissions child](/quest/m1/poll-first/no-spawn/admissions.md) moves it
into `Driver`.

Public API: `Cluster::new` returns `(Cluster, Driver)`; the PR's Impact section
describes the migration. Wire: none.

## Related

- [The remaining spawns](/quest/m2/spawn-audit.md) - owns moq-tokio's session spawns and `Critical`'s remaining tasks
35 changes: 35 additions & 0 deletions quest/m1/poll-first/no-spawn/ffi.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# [M] moq-ffi spawns only its root

## Goal

moq-ffi spawns one task outside its UniFFI calls: a runtime-owned driver that
polls every `Background` as a `kio::Tasks` child. Origin drivers, the server
accept loop, cleanups, and demand waits no longer spawn tasks of their own.

## Plan

Spawns in scope on `main` (2026-11-01), all in `rs/moq-ffi/src/`:

- `ffi.rs`, `ffi::spawn` and `Background::driver`: origin drivers
(`origin.rs`), the server accept loop (`server.rs`), and cleanups.
- `ffi.rs`, `detached`: demand waits (`demand.rs`, `producer.rs`).
- `ffi.rs`, each UniFFI call's task on the bindings' runtime. This stays: each
call's own future is the binding boundary.

✅ **One root driver** (maintainer, 2026-11-01, D4 on
[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): moq-ffi's root
is one runtime-owned driver task that holds every `Background` as `kio::Tasks`
children. Rejected: having each handle's calls poll its `Background`, which
fails for an origin with no reader, since nobody would poll its driver.

[moq-dev/moq#7497](https://github.com/moq-dev/moq/pull/7497) replaces
`ffi::Task` with `ffi::Polled` and changes `Background` and shutdown in
`ffi.rs`, keeping demand waits `detached` for now. Build on it: converting
before it lands would conflict on almost every line. Recount the sites above
once it merges.

Public API: no binding signature changes. Wire: none.

## Required

- [Poll-native async in moq-ffi](/quest/m2/ffi-poll-migrate.md) - its PR rewrites the `Task` and `Background` plumbing this changes
23 changes: 23 additions & 0 deletions quest/m1/poll-first/no-spawn/sim-tests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# [M] The relay's in-memory tests run on kio's simulator

## Goal

moq-relay's in-memory integration tests
(`rs/moq-relay/tests/integration/connection.rs`) run on kio's simulator
instead of paused tokio.

## Plan

This needs the cluster's and the admissions' work to be polled, which the
children it requires deliver. It also needs `moq_tokio::origin::spawn` and the
memory connect helper the tests use to run without tokio. moq-tokio belongs to
[the spawn audit](/quest/m2/spawn-audit.md) (m2), so this quest may move to
m2, or require the part of the spawn audit that converts those two helpers.
Decide that when it starts.

Public API: none. Wire: none.

## Required

- [Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) - the cluster's driver and dials stop spawning on tokio
- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - admissions stop spawning on tokio
2 changes: 1 addition & 1 deletion quest/m2/ffi-poll-migrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,4 @@ get items in call order; sequence and arrival order are unchanged. Wire: none.
## Related

- [Foreign poll for hot reads](https://github.com/moq-dev/rust2/blob/main/quest/m1/ffi-poll-protocol.md) - the generated protocol that follows this, once the fork exists
- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - moq-ffi spawns only its root at the binding boundary
- [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children
2 changes: 1 addition & 1 deletion quest/m2/net-wrap/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Compression is not a wrapper: it moves into moq-net as a track flag
moq-flate, so moq-flate is out of scope.

Non-goals:
- A runtime seam: libraries poll and spawn nothing ([Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md)).
- A runtime seam: libraries poll and spawn nothing ([Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md)).
- The transport seam: custom transports implement moq-net's `transport::poll` traits ([native WebTransport](/quest/m1/quic-api/native-web.md) moves the last backend onto them).

## Plan
Expand Down
4 changes: 2 additions & 2 deletions quest/m2/spawn-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Goal

Every async task spawn left in a library crate after
[Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) is either converted
[Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) is either converted
to a `kio::Tasks` child its owner polls or listed with the reason it must stay.
Blocking OS threads are out of scope.

Expand All @@ -26,4 +26,4 @@ migration note per published crate. Wire: none.

## Required

- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - the rule and the pattern this applies
- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) - the rule and the pattern this applies
2 changes: 1 addition & 1 deletion quest/m3/studio/web/video-web.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,4 @@ target; confirm the web studio still wants it before starting.

## Required

- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - library work polled by its owner, with no runtime to spawn on
- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) - library work polled by its owner, with no runtime to spawn on