From bf69a4198a9e126691558a4d470f0b72b91761ca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 09:16:50 -0700 Subject: [PATCH 1/4] quest: plan a per-task serve budget, a multi-thread FFI runtime, and 20 ms audio groups A serve loop that always has another group ready never yields. That starved moq-ffi's single runtime thread until the relay timed the go interop publisher out (found landing #4225). Three quests: a kio-native per-task budget (m0), a multi-thread runtime for moq-ffi and moq-c (m1), and a 20 ms default audio group duration (m1). Co-Authored-By: Claude Opus 5.5 --- quest/m0/README.md | 6 +++ quest/m0/serve-budget.md | 74 ++++++++++++++++++++++++++++ quest/m1/README.md | 2 + quest/m1/audio-group-duration.md | 35 +++++++++++++ quest/m1/ffi-runtime.md | 42 ++++++++++++++++ quest/m1/interop-browser-timeouts.md | 4 ++ quest/m1/perf/uring-quiescence.md | 4 ++ 7 files changed, 167 insertions(+) create mode 100644 quest/m0/serve-budget.md create mode 100644 quest/m1/audio-group-duration.md create mode 100644 quest/m1/ffi-runtime.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 3c92f5b917c..bd4c736b21b 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -43,6 +43,11 @@ gates the next release (decided 2026-10-03: viewers). #4741 can merge to main, but no release ships until first-party publishers mint epochs. +Liveness: a serve loop with work always ready never yields, which starved +an FFI publisher's QUIC driver and fails hosted Interop's go lanes (found +2026-10-08 landing #4225). The [serve budget](/quest/m0/serve-budget.md) +bounds every kio task's loop. + Audio playout: the jitter target replaces the round-trip guess. The browser audio quality harness in `test/audio-quality/` has landed; it grades playout nightly and records the traces it replays. Its native lane is a standalone m1 @@ -52,6 +57,7 @@ a published `@moq/watch` break. ## Required +- [Serve budget](/quest/m0/serve-budget.md) - a kio task that always has work ready yields after a budget, so a fast publisher can't starve its own QUIC driver - [Held group wakes](/quest/m0/held-group-wakes.md) - a group held across a route switch is woken when its successor's first timestamp or abort makes it stale, not at the next unrelated append - [Draft-22 LOCATION_FILTER](/quest/m0/ietf-location-filter-22.md) - moqt-22 LOCATION_FILTER carries its type instead of a Length in Rust and JS, so a draft-22 peer reads our Next Object correctly - [End of Track Location](/quest/m0/ietf-end-of-track-location.md) - a relay forwards END_OF_TRACK at its upstream's Location, on the last group's stream, instead of re-sending it at the next group's object 0 diff --git a/quest/m0/serve-budget.md b/quest/m0/serve-budget.md new file mode 100644 index 00000000000..1a6338063e8 --- /dev/null +++ b/quest/m0/serve-budget.md @@ -0,0 +1,74 @@ +# [M] A busy task yields within a budget + +## Goal + +No kio task can hold its thread with an unbounded loop while work keeps +arriving. A serve loop that always has another group ready yields after a +fixed budget of progress and resumes on its next poll, so the QUIC driver, +timers, and the session's other tasks run in between, on every runtime +(tokio multi-thread and current-thread, wasm, and the io_uring worker). + +Found while landing #4225 (2026-10-08): the go interop publisher writes +2.5 ms Opus frames, one group each (about 400 groups/s). When a relay +subscribes, `RequestServe::poll_serve` (`rs/moq-net/src/lite/publisher.rs`) +keeps returning `Continue` and one poll ran over 4,096 iterations. moq-ffi's +current-thread runtime then starves noq's connection driver until the relay +times the publisher out after 10 s. Hosted Interop's `go -> *` lanes fail on +#4225 and stall for about 10 s on `main`. When this lands, those lanes pass +without the stall, and #4225 can land. + +Not here: moq-net spawning tasks (it stays poll-only by design, #2302, +#2736, #3825), the FFI runtime flavor, or the audio grouping default; those +are separate quests below. + +## Plan + +Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that +added this quest): + +- The bound is generic, modeled on tokio's cooperative budget, and lives in + kio, which stays dependency-free. Tokio's budget cannot see this loop, + because the work goes through kio primitives, never a tokio resource. + Rejected: per-loop budgets in the two serve loops (not generic), and + bridging kio to `tokio::task::coop` (leaves wasm and io_uring unbounded). +- Mechanics: + - a per-thread budget in kio. An async kio readiness poll that makes + progress spends one unit, and refunds it if the operation ends `Pending` + anyway; + - an exhausted budget wakes the current task (`cx.waker().wake_by_ref()`) + and returns `Pending`. Callers already handle `Pending`, so no new + states; + - synchronous `try_*` and peek APIs spend nothing, since their callers read + "nothing now" as empty, not as "come back". +- The budget is per kio task: `Tasks::poll` refills it for each child it + polls, and `moq_net::time::run` refills it around each `driver.poll(now)` + for the driver's own code. A child that runs out lands in the next pass by + `Tasks`' one-snapshot rule (`a_self_waking_task_yields_to_the_owner`), and + the owner returns to its runtime after the pass. Work per turn scales with + the children that were ready, so a busy fan-out session is not throttled. + Rejected: one budget shared by the whole runtime task (tokio's model), + which caps a session with many subscriptions at one budget per turn. +- Refill mirrors tokio: `kio::coop::budget(f)` sets a fresh budget and + restores the previous value on exit, so nesting refills. Public, documented + as called only where a driver hands a task its turn. Code outside any + `budget` call is unconstrained, as today. The moq-uring worker's pass calls + it too if it polls anything outside `Tasks`. +- The size starts at 128 (tokio's) and is a constant, not configurable. A + bench picks it: sweep unbounded, 32, 128, and 512 against `main` and keep + the smallest whose throughput matches unbounded. +- Tests, with mocked time: a producer appends 10,000 groups during a serve + and the serve poll returns `Pending` within the budget while a sibling task + and the transport make progress (fails on `main`); kio unit tests for + spend, refund, exhaustion, and nested refill. +- Bench: extend the serve benchmark swept over groups/s and subscriptions per + session, and kio's `channel` and `tasks` benches for the per-operation cost + of the thread-local. + +Public API: `kio::coop::budget` (new). Wire: none. + +## Related + +- [FFI runtime](/quest/m1/ffi-runtime.md) - FFI apps run on more than one thread +- [Audio group duration](/quest/m1/audio-group-duration.md) - small audio frames stop minting a group each +- [Browser interop cells](/quest/m1/interop-browser-timeouts.md) - the `go -> js` and `python -> js` timeouts, likely the same stall +- [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - its pass count bounds passes per turn; this budget bounds one task's loop, so they compose diff --git a/quest/m1/README.md b/quest/m1/README.md index 47d2deef5b3..17712d09c40 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -68,6 +68,8 @@ blocks. The quests that gated m0 lines moved under them. - [Dropped uring session closes](/quest/m1/uring-drop-close.md) - a moq-uring session dropped without close() closes its connection - [Media audio-tone check](/quest/m1/media-audio-tone.md) - the media lane's audio-tone check passes under load, fixed at its cause - [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs +- [FFI runtime](/quest/m1/ffi-runtime.md) - moq-ffi and moq-c drive 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 - [Browser interop cells](/quest/m1/interop-browser-timeouts.md) - `go -> js` and `python -> js` pass, fixed at the cause rather than by a longer timeout - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives diff --git a/quest/m1/audio-group-duration.md b/quest/m1/audio-group-duration.md new file mode 100644 index 00000000000..51685a6e489 --- /dev/null +++ b/quest/m1/audio-group-duration.md @@ -0,0 +1,35 @@ +# [S] Audio groups span at least 20 ms by default + +## Goal + +An audio publisher that never sets a group duration emits at most about 50 +groups per second, whatever its codec frame size. Today every producer +defaults `group_duration` to zero, a group per packet, so the go interop +client's 2.5 ms Opus frames mint about 400 groups/s, each a QUIC stream and a +serve. + +## Plan + +Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that +added this quest): + +- `moq_audio::encode::Options::group_duration` defaults to 20 ms + (`rs/moq-audio/src/encode/producer.rs`, documented today as "Defaults to + zero, a group per packet"). 20 ms frames behave as today; smaller frames + share a group up to 20 ms. +- Every producer follows it: moq-ffi `encode_audio`, moq-c, moq-boy, and the + CLI through `Options::default()`; JS publish's `groupDuration` + (`js/publish/src/audio/encoder.ts`); and the GStreamer sink, which today + cuts after every audio packet (`rs/moq-gst/src/sink/pad.rs`). Rejected: + only the FFI sets it, and keeping zero. +- Docs: `doc/lib/rs/moq-audio.md` and the JS publish docs drop "a group per + packet" as the default. +- Test: a 2.5 ms Opus encode yields groups of at least 20 ms in Rust and JS, + and the gst sink's grouping test. + +Public API: a changed default in moq-audio and `@moq/publish`. Wire: none. + +## Related + +- [Serve budget](/quest/m0/serve-budget.md) - bounds the serve loop whatever the group rate +- [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) - the FFI encoder's frame size default, a separate knob diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md new file mode 100644 index 00000000000..55499ec8206 --- /dev/null +++ b/quest/m1/ffi-runtime.md @@ -0,0 +1,42 @@ +# [S] FFI apps run on more than one thread + +## Goal + +moq-ffi and moq-c drive 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, and + `rs/moq-c/src/ffi.rs` does the same (`moq-c`). 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 budget](/quest/m0/serve-budget.md) alone. +- Keep the "foreign caller's thread never drives our futures" property: work + still runs via `Task::run` and `detached`. Check the exported async fns that + await in place (`subscribe_catalog`, `subscribe_track`, `fetch_group`, + `request_broadcast`, `decode_audio`, `decode_video`) and the sync methods + that enter the runtime context (`MoqAudioProducer::write`), and keep + `moq_ffi_shutdown` and Python's `atexit` clean. +- Watch [Kotlin/JVM exit](/quest/m1/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: none (threading only). Wire: none. + +## Related + +- [Serve budget](/quest/m0/serve-budget.md) - the root fix for a task hogging its thread +- [Kotlin/JVM exit](/quest/m1/kt-jvm-exit.md) - runtime-thread shutdown diff --git a/quest/m1/interop-browser-timeouts.md b/quest/m1/interop-browser-timeouts.md index 1dd84434af7..56939ef569b 100644 --- a/quest/m1/interop-browser-timeouts.md +++ b/quest/m1/interop-browser-timeouts.md @@ -21,9 +21,13 @@ FFI publisher's 2 s audio max age parked hundreds of group serves. - Find which step stalls and why, from the player trace and the publisher side. Check whether #5005 alone fixed it before changing anything else. - Never raise the timeout or add a retry. +- Found 2026-10-08 while landing #4225: an FFI publisher's serve loop can + starve moq-ffi's single runtime thread until the relay times it out. + Re-check these cells once [Serve budget](/quest/m0/serve-budget.md) lands. Public API: none expected. Wire: none. ## Related +- [Serve budget](/quest/m0/serve-budget.md) - likely the same stall - [CI runner stalls](/quest/m1/ci-runner-stalls.md) - shorter freezes of both interop tracks on CI runners diff --git a/quest/m1/perf/uring-quiescence.md b/quest/m1/perf/uring-quiescence.md index 42254f0849b..ee9c09ce2c1 100644 --- a/quest/m1/perf/uring-quiescence.md +++ b/quest/m1/perf/uring-quiescence.md @@ -52,3 +52,7 @@ meaning with a budget of 1 and gains a sibling proving the budget bound. - [Hard fork](/quest/m1/quic/fork/README.md) - the noq driver this edits moves onto `moq-quic` (decided in the 2026-10-05 audit) - [One enter per turn](/quest/m1/perf/uring-one-enter.md) - the metrics and the submit placement this sweep is measured with + +## Related + +- [Serve budget](/quest/m0/serve-budget.md) - a per-task budget bounds one task's loop; this quest's pass count bounds passes per turn, and the sweep runs with both in place From 97e33163c3bd12e776108ef29645b32f578a245e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 09:26:31 -0700 Subject: [PATCH 2/4] quest: bound a multi-pass turn in serve-budget Co-Authored-By: Claude Opus 5.5 --- quest/m0/serve-budget.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/quest/m0/serve-budget.md b/quest/m0/serve-budget.md index 1a6338063e8..951256a4674 100644 --- a/quest/m0/serve-budget.md +++ b/quest/m0/serve-budget.md @@ -46,6 +46,10 @@ added this quest): `Tasks`' one-snapshot rule (`a_self_waking_task_yields_to_the_owner`), and the owner returns to its runtime after the pass. Work per turn scales with the children that were ready, so a busy fan-out session is not throttled. + If [Run to quiescence](/quest/m1/perf/uring-quiescence.md) lets a turn run + several passes, each pass refills every child it polls, so a turn is + bounded by passes times ready children times the budget, and the owner + returns only after the last pass. Rejected: one budget shared by the whole runtime task (tokio's model), which caps a session with many subscriptions at one budget per turn. - Refill mirrors tokio: `kio::coop::budget(f)` sets a fresh budget and From e354e088c0b39f356f2bf0a4e1c659486ca98cdb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 09:33:03 -0700 Subject: [PATCH 3/4] quest: fold review corrections into the serve-budget, FFI runtime, and audio plans Budget Pending must only postpone: list the sites that read Pending as a value or commit state first. Refill time::run once per wait poll, state the nested bound, gate on the mocked test, and keep FFI shutdown's guarantee with N workers. Co-Authored-By: Claude Opus 5.5 --- quest/m0/serve-budget.md | 50 ++++++++++++++++++++++---------- quest/m1/audio-group-duration.md | 3 +- quest/m1/ffi-runtime.md | 15 ++++++++-- 3 files changed, 48 insertions(+), 20 deletions(-) diff --git a/quest/m0/serve-budget.md b/quest/m0/serve-budget.md index 951256a4674..c084bd511a7 100644 --- a/quest/m0/serve-budget.md +++ b/quest/m0/serve-budget.md @@ -14,8 +14,11 @@ subscribes, `RequestServe::poll_serve` (`rs/moq-net/src/lite/publisher.rs`) keeps returning `Continue` and one poll ran over 4,096 iterations. moq-ffi's current-thread runtime then starves noq's connection driver until the relay times the publisher out after 10 s. Hosted Interop's `go -> *` lanes fail on -#4225 and stall for about 10 s on `main`. When this lands, those lanes pass -without the stall, and #4225 can land. +#4225 and stall for about 10 s on `main`. The gate is the mocked serve test +below, not those lanes: the m1 quests each hide the stall on their own, and +the #4225 root-cause comment saw a 64-iteration yield still time the +publisher out, so a yield alone may not be the whole fix. Re-check the lanes +and #4225 when this lands. Not here: moq-net spawning tasks (it stays poll-only by design, #2302, #2736, #3825), the FFI runtime flavor, or the audio grouping default; those @@ -27,7 +30,7 @@ Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that added this quest): - The bound is generic, modeled on tokio's cooperative budget, and lives in - kio, which stays dependency-free. Tokio's budget cannot see this loop, + kio, which takes no runtime dependency. Tokio's budget cannot see this loop, because the work goes through kio primitives, never a tokio resource. Rejected: per-loop budgets in the two serve loops (not generic), and bridging kio to `tokio::task::coop` (leaves wasm and io_uring unbounded). @@ -35,21 +38,35 @@ added this quest): - a per-thread budget in kio. An async kio readiness poll that makes progress spends one unit, and refunds it if the operation ends `Pending` anyway; - - an exhausted budget wakes the current task (`cx.waker().wake_by_ref()`) - and returns `Pending`. Callers already handle `Pending`, so no new - states; - - synchronous `try_*` and peek APIs spend nothing, since their callers read - "nothing now" as empty, not as "come back". + - an exhausted budget wakes the current task + (`waiter.waker().wake_by_ref()`) and returns `Pending`; + - synchronous `try_*` and peek APIs, and any poll with + `kio::Waiter::noop()`, spend nothing, since their callers read "nothing + now" as empty, not as "come back". +- A budget `Pending` must only postpone, never change a decision or lose + state. Spend only at state-safe boundaries, and audit every caller that + reads `Pending` as a value or commits state before a later poll. Known + sites: `TrackRun::start` reads Largest for SUBSCRIBE_START with + `Pending => None`; `poll_recv_next` probes `poll_finished` after + `poll_recv_group` ends, and a `Pending` there skips SUBSCRIBE_END; + `GroupServe` reads `poll_expired` as a bool; and `Cursor::poll_recv_group` + advances `index` or takes a parked group before `poll_stale`, so a + `Pending` there drops the group. Tests drive each site to exhaustion and + check every eligible group is delivered exactly once, fresh and parked. - The budget is per kio task: `Tasks::poll` refills it for each child it - polls, and `moq_net::time::run` refills it around each `driver.poll(now)` - for the driver's own code. A child that runs out lands in the next pass by + polls, and `moq_net::time::run` refills it once per `kio::wait` poll, + outside its loop, so an always-ready timer can't refill per iteration. A child that runs out lands in the next pass by `Tasks`' one-snapshot rule (`a_self_waking_task_yields_to_the_owner`), and the owner returns to its runtime after the pass. Work per turn scales with the children that were ready, so a busy fan-out session is not throttled. If [Run to quiescence](/quest/m1/perf/uring-quiescence.md) lets a turn run several passes, each pass refills every child it polls, so a turn is bounded by passes times ready children times the budget, and the owner - returns only after the last pass. + returns only after the last pass. Owners that poll their `Tasks` more than + once per poll (`Publisher::poll`, `SubscribeServe::poll_step` inside + `RequestServe::poll_serve`'s loop) compound the same way: a nested serve + can spend about the budget squared in one runtime poll. That is bounded, + and the bench decides whether it matters. Rejected: one budget shared by the whole runtime task (tokio's model), which caps a session with many subscriptions at one budget per turn. - Refill mirrors tokio: `kio::coop::budget(f)` sets a fresh budget and @@ -61,11 +78,12 @@ added this quest): bench picks it: sweep unbounded, 32, 128, and 512 against `main` and keep the smallest whose throughput matches unbounded. - Tests, with mocked time: a producer appends 10,000 groups during a serve - and the serve poll returns `Pending` within the budget while a sibling task - and the transport make progress (fails on `main`); kio unit tests for - spend, refund, exhaustion, and nested refill. -- Bench: extend the serve benchmark swept over groups/s and subscriptions per - session, and kio's `channel` and `tasks` benches for the per-operation cost + with many groups in flight, the serve poll returns `Pending` while a + sibling task and the transport make progress (fails on `main`), and the + units spent per runtime poll are counted against the bound; kio unit tests + for spend, refund, exhaustion, and nested refill. +- Bench: extend `rs/moq-net/benches/session.rs` swept over groups/s and + subscriptions per session, and kio's `channel` and `tasks` benches for the per-operation cost of the thread-local. Public API: `kio::coop::budget` (new). Wire: none. diff --git a/quest/m1/audio-group-duration.md b/quest/m1/audio-group-duration.md index ad2309c826a..2cb9203a659 100644 --- a/quest/m1/audio-group-duration.md +++ b/quest/m1/audio-group-duration.md @@ -16,7 +16,8 @@ added this quest): - `moq_audio::encode::Options::group_duration` defaults to 20 ms (`rs/moq-audio/src/encode/producer.rs`, documented today as "Defaults to zero, a group per packet"). 20 ms frames behave as today; smaller frames - share a group up to 20 ms. + share a group up to 20 ms, so the 10 ms low-latency Opus preset now pairs + packets. - Every producer follows it: moq-ffi `encode_audio`, moq-c, moq-boy, and the CLI through `Options::default()`; JS publish's `groupDuration` (`js/publish/src/audio/encoder.ts`); and the GStreamer sink, which today diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md index 5699220512e..8b9f99da994 100644 --- a/quest/m1/ffi-runtime.md +++ b/quest/m1/ffi-runtime.md @@ -26,15 +26,24 @@ added this quest): still runs via `Task::run` and `detached`. Check the exported async fns that await in place (`subscribe_catalog`, `subscribe_track`, `fetch_group`, `request_broadcast`, `decode_audio`, `decode_video`) and the sync methods - that enter the runtime context (`MoqAudioProducer::write`), and keep - `moq_ffi_shutdown` and Python's `atexit` clean. + that enter the runtime context (`MoqAudioProducer::write`). +- 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` (and moq-c's) 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. - 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: none (threading only). Wire: none. +Public API: callbacks may fire concurrently on any runtime thread +(documented); no signature changes. Wire: none. ## Related From 9bf3fb27fc03ca0fd8af8d59f3ac7ec584dc787f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 09:41:09 -0700 Subject: [PATCH 4/4] quest: scope the serve budget to budgeted polls, detect noop waiters, drop moq-c shutdown Co-Authored-By: Claude Opus 5.5 --- quest/m0/serve-budget.md | 8 +++++--- quest/m1/ffi-runtime.md | 5 +++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/quest/m0/serve-budget.md b/quest/m0/serve-budget.md index c084bd511a7..97365a7c1b3 100644 --- a/quest/m0/serve-budget.md +++ b/quest/m0/serve-budget.md @@ -2,8 +2,9 @@ ## Goal -No kio task can hold its thread with an unbounded loop while work keeps -arriving. A serve loop that always has another group ready yields after a +No kio task can hold its thread with an unbounded loop of async kio +readiness polls while work keeps arriving. Synchronous `try_*` and peek +loops, and code outside a `kio::coop::budget`, stay unbounded, as today. A serve loop that always has another group ready yields after a fixed budget of progress and resumes on its next poll, so the QUIC driver, timers, and the session's other tasks run in between, on every runtime (tokio multi-thread and current-thread, wasm, and the io_uring worker). @@ -42,7 +43,8 @@ added this quest): (`waiter.waker().wake_by_ref()`) and returns `Pending`; - synchronous `try_*` and peek APIs, and any poll with `kio::Waiter::noop()`, spend nothing, since their callers read "nothing - now" as empty, not as "come back". + now" as empty, not as "come back". `Waiter` carries an explicit noop + flag for this, since comparing wakers is not reliable. - A budget `Pending` must only postpone, never change a decision or lose state. Spend only at state-safe boundaries, and audit every caller that reads `Pending` as a value or commits state before a later poll. Known diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md index 8b9f99da994..368e49b467b 100644 --- a/quest/m1/ffi-runtime.md +++ b/quest/m1/ffi-runtime.md @@ -32,10 +32,11 @@ added this quest): 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` (and moq-c's) returns, +- 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. + that with N workers; the shutdown must wait for them. moq-c exports no + shutdown and is being [retired](/quest/m1/c/retire.md), so it gets none. - 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