From e6e58de35eee952875b35bbda5a7ca8bbae17409 Mon Sep 17 00:00:00 2001 From: Zac Shenker Date: Wed, 21 Oct 2026 15:28:24 -0600 Subject: [PATCH 1/3] quest(m2): add leak-free poll forms for the QUIC driver's waits Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 1 + quest/m2/driver-poll.md | 92 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 quest/m2/driver-poll.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 7f161f908cd..174dbe9ca64 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -116,6 +116,7 @@ ranked just below deterministic TS legs, which it requires. - [Per-stream deadlines](/quest/m2/quic-deadline.md) - hopeless retransmits become resets, and a tail loss probe fires early while there is still time - [Drop web-transport-trait](/quest/m2/drop-web-transport-trait.md) - every backend implements moq-net's `transport::poll` traits, and the generic `web_transport_trait` adapters are deleted +- [QUIC driver poll waits](/quest/m2/driver-poll.md) - every `moq_tokio::quic::driver` wait gets a leak-free `poll_*` form, named like moq-uring's driver - [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - a written verdict on marking versus dropping, and whether Linode and OVH keep marks - [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - the diff --git a/quest/m2/driver-poll.md b/quest/m2/driver-poll.md new file mode 100644 index 00000000000..eb878c62a52 --- /dev/null +++ b/quest/m2/driver-poll.md @@ -0,0 +1,92 @@ +# [M] The QUIC driver's waits poll without leaking + +## Goal + +Every wait in `moq_tokio::quic::driver` has a `poll_*` form that leaks +nothing: `Connection::poll_open_uni`, `poll_open_bi`, `poll_accept_uni`, +`poll_accept_bi`, `poll_recv_datagram` and `poll_closed`, +`SendStream::poll_closed` (today's `stopped`), and `Endpoint::poll_accept`. +`SendStream::poll_acked`, which [poll_acked](/quest/m2/quic-ack-hook.md) +adds, uses the same mechanism. The names follow moq-uring's driver, which +already follows moq-net's `transport::poll` traits; return types stay the +driver's own. A waiter that polls once and is dropped leaves nothing alive: +no live registration and no task. + +## Plan + +The driver's waits are futures over `tokio::sync::Notify`: the connection's +`Shared` fields, the per-stream `stopped` map, and the endpoint's `incoming`. +`Notify` cannot hold a bare waker, so a poll-based caller has to keep the +future, and moq-tokio's `transport::Session` adapter boxes one per pending +operation. [Drop web-transport-trait](/quest/m2/drop-web-transport-trait.md) +wants a native `poll::Session` on the QUIC backend, and +[poll_acked](/quest/m2/quic-ack-hook.md) wants a real poll method. Both need +these. + +The trap is a stateless `&self` poll that pushes the caller's waker into a +shared list. Nothing removes the entry when its caller gives up, so it lives, +holding its task, until the next signal; for `poll_closed` that is the end of +the connection. A trial of that shape kept all 1000 abandoned `poll_closed` +waiters. Leak-free needs per-caller state that dies with the caller, as +tokio's `Notified` has, and as kio's `Park` and `WaiterList` give through +`Weak` entries. + +Options: + +- **A (recommended): `&mut self, cx`, with a `kio::Park` in each handle.** A + clone gets an empty park, so a registration belongs to the handle that made + it and dies with it. This is moq-uring's driver shape and moq-net's + `poll::Session` shape, so a native impl forwards in one line, and kio stays + private. + + ```rust + impl Connection { + pub fn poll_accept_uni(&mut self, cx: &mut Context<'_>) -> Poll>; + pub fn poll_open_uni(&mut self, cx: &mut Context<'_>, options: SendOptions<'_>) -> Poll>; + pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll; + } + impl SendStream { + pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll, StoppedError>>; + } + ``` + +- **B: `&self, &kio::Waiter`**, the convention in `rs/AGENTS.md`. Leak-free, + since the caller owns the waiter, and the handles stay `&self`. But kio + enters the driver's public signatures, so a kio break is a driver break, + and every `cx`-based caller (moq-net's traits) holds a `Park` anyway. +- **C: a caller-owned `Wait` token** (`poll_closed(&self, cx, &mut Wait)`), + slab-backed, generation-checked, and released on drop. Leak-free and + `&self`, but a second waiter primitive beside kio's, with its own slab and + tests to carry. +- **D: a stateless shared list.** Rejected: the leak above. + +Recommended mechanism: swap the `Notify`s, and the `stopped` map's entries, +for `kio::WaiterList`s woken where the `Notify`s are signalled today, under +the connection lock, and make the existing async forms thin wrappers. They can +keep `&self` by owning their waiter (`kio::wait`), so no caller changes. Keep +the existing guarantees, such as draining accepted streams and datagrams +from a closed connection before its error. The other `Notify` waits +(`handshake_confirmed`, `Endpoint::wait_idle`) may move to the same lists, +but get no poll form until a caller needs one. + +Maintainer question: A and B add kio as a direct dependency of the `driver` +feature. kio is already in the driver-only tree through `moq-quic`'s +moq-clock, which #6132 accepted (its decision 4), so no crate is added; B +also makes it public API. Recommended: A. + +Lands after #6196, which rewrites the `stopped` waiter map. It blocks the +driver half of [poll_acked](/quest/m2/quic-ack-hook.md). + +The acceptance test is the measured leak: 1000 waiters that poll once and are +dropped unresolved leave no live registration behind, checked before the +condition is ever signalled, so release on drop is what passes it, not the +next wake. Also, on paused time: two handles waiting on each condition both +wake; one handle polled 100 times holds one live registration; a clone's poll +leaves the original's registration in place. Report the public API: new poll +methods on `Connection`, `SendStream` and `Endpoint`, with the async forms +unchanged. + +## Related + +- [Drop web-transport-trait](/quest/m2/drop-web-transport-trait.md) - its native QUIC `poll::Session` calls these +- [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - adds `SendStream::poll_acked` in this shape From 2bb0b575fbf2cd98468946f8442643a346ad2845 Mon Sep 17 00:00:00 2001 From: Zac Shenker Date: Thu, 22 Oct 2026 09:54:37 -0600 Subject: [PATCH 2/3] quest(m2): driver-poll builds on the merged stopped waiter map Co-Authored-By: Claude Opus 5.5 --- quest/m2/driver-poll.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/m2/driver-poll.md b/quest/m2/driver-poll.md index eb878c62a52..52f08fed002 100644 --- a/quest/m2/driver-poll.md +++ b/quest/m2/driver-poll.md @@ -74,8 +74,8 @@ feature. kio is already in the driver-only tree through `moq-quic`'s moq-clock, which #6132 accepted (its decision 4), so no crate is added; B also makes it public API. Recommended: A. -Lands after #6196, which rewrites the `stopped` waiter map. It blocks the -driver half of [poll_acked](/quest/m2/quic-ack-hook.md). +Builds on the `stopped` waiter map as #6196 left it, which already records a +local reset. It blocks the driver half of [poll_acked](/quest/m2/quic-ack-hook.md). The acceptance test is the measured leak: 1000 waiters that poll once and are dropped unresolved leave no live registration behind, checked before the From 6978f183d32dc3b9bf4e537774e5353edb5023c6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 14:29:58 -0700 Subject: [PATCH 3/3] quest(m2): settle driver-poll's shape and narrow its index entry Poll forms take &mut self, cx with a kio::Park per handle, and kio becomes a direct driver dependency. The README entry excludes handshake_confirmed and Endpoint::wait_idle, which stay async. Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 2 +- quest/m2/driver-poll.md | 68 ++++++++++++++++++++--------------------- 2 files changed, 35 insertions(+), 35 deletions(-) diff --git a/quest/m2/README.md b/quest/m2/README.md index 1c813f229e1..32ce998f70c 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -145,7 +145,7 @@ ranked just below deterministic TS legs, which it requires. - [Per-stream deadlines](/quest/m2/quic-deadline.md) - hopeless retransmits become resets, and a tail loss probe fires early while there is still time - [Drop web-transport-trait](/quest/m2/drop-web-transport-trait.md) - every backend implements moq-net's `transport::poll` traits, and the generic `web_transport_trait` adapters are deleted -- [QUIC driver poll waits](/quest/m2/driver-poll.md) - every `moq_tokio::quic::driver` wait gets a leak-free `poll_*` form, named like moq-uring's driver +- [QUIC driver poll waits](/quest/m2/driver-poll.md) - the `moq_tokio::quic::driver` stream, datagram, close, and accept waits get leak-free `poll_*` forms, named like moq-uring's driver; `handshake_confirmed` and `Endpoint::wait_idle` stay async - [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - a written verdict on marking versus dropping, and whether Linode and OVH keep marks - [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - the diff --git a/quest/m2/driver-poll.md b/quest/m2/driver-poll.md index 52f08fed002..5619737d17c 100644 --- a/quest/m2/driver-poll.md +++ b/quest/m2/driver-poll.md @@ -2,8 +2,8 @@ ## Goal -Every wait in `moq_tokio::quic::driver` has a `poll_*` form that leaks -nothing: `Connection::poll_open_uni`, `poll_open_bi`, `poll_accept_uni`, +The stream, datagram, close, and accept waits in `moq_tokio::quic::driver` +have `poll_*` forms that leak nothing: `Connection::poll_open_uni`, `poll_open_bi`, `poll_accept_uni`, `poll_accept_bi`, `poll_recv_datagram` and `poll_closed`, `SendStream::poll_closed` (today's `stopped`), and `Endpoint::poll_accept`. `SendStream::poll_acked`, which [poll_acked](/quest/m2/quic-ack-hook.md) @@ -31,36 +31,37 @@ waiters. Leak-free needs per-caller state that dies with the caller, as tokio's `Notified` has, and as kio's `Park` and `WaiterList` give through `Weak` entries. -Options: +Shape: poll forms take `&mut self, cx`, with a `kio::Park` in each handle. A +clone gets an empty park, so a registration belongs to the handle that made +it and dies with it. A handle that stops polling but stays alive keeps at most +its one registration until its next poll or the signal; that is the standard +poll contract, and it is bounded per handle. This is moq-uring's driver shape +and moq-net's `poll::Session` shape, so a native impl forwards in one line, +and kio stays private. -- **A (recommended): `&mut self, cx`, with a `kio::Park` in each handle.** A - clone gets an empty park, so a registration belongs to the handle that made - it and dies with it. This is moq-uring's driver shape and moq-net's - `poll::Session` shape, so a native impl forwards in one line, and kio stays - private. +```rust +impl Connection { + pub fn poll_accept_uni(&mut self, cx: &mut Context<'_>) -> Poll>; + pub fn poll_open_uni(&mut self, cx: &mut Context<'_>, options: SendOptions<'_>) -> Poll>; + pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll; +} +impl SendStream { + pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll, StoppedError>>; +} +``` - ```rust - impl Connection { - pub fn poll_accept_uni(&mut self, cx: &mut Context<'_>) -> Poll>; - pub fn poll_open_uni(&mut self, cx: &mut Context<'_>, options: SendOptions<'_>) -> Poll>; - pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll; - } - impl SendStream { - pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll, StoppedError>>; - } - ``` +Rejected shapes: -- **B: `&self, &kio::Waiter`**, the convention in `rs/AGENTS.md`. Leak-free, - since the caller owns the waiter, and the handles stay `&self`. But kio - enters the driver's public signatures, so a kio break is a driver break, - and every `cx`-based caller (moq-net's traits) holds a `Park` anyway. -- **C: a caller-owned `Wait` token** (`poll_closed(&self, cx, &mut Wait)`), - slab-backed, generation-checked, and released on drop. Leak-free and - `&self`, but a second waiter primitive beside kio's, with its own slab and - tests to carry. -- **D: a stateless shared list.** Rejected: the leak above. +- **`&self, &kio::Waiter`**, the convention in `rs/AGENTS.md`. Leak-free, + since the caller owns the waiter, but kio enters the driver's public + signatures, so a kio break is a driver break, and every `cx`-based caller + (moq-net's traits) holds a `Park` anyway. +- **A caller-owned `Wait` token** (`poll_closed(&self, cx, &mut Wait)`), + slab-backed and released on drop: a second waiter primitive beside kio's, + with its own slab and tests to carry. +- **A stateless shared list**: the leak above. -Recommended mechanism: swap the `Notify`s, and the `stopped` map's entries, +Mechanism: swap the `Notify`s, and the `stopped` map's entries, for `kio::WaiterList`s woken where the `Notify`s are signalled today, under the connection lock, and make the existing async forms thin wrappers. They can keep `&self` by owning their waiter (`kio::wait`), so no caller changes. Keep @@ -69,16 +70,15 @@ from a closed connection before its error. The other `Notify` waits (`handshake_confirmed`, `Endpoint::wait_idle`) may move to the same lists, but get no poll form until a caller needs one. -Maintainer question: A and B add kio as a direct dependency of the `driver` -feature. kio is already in the driver-only tree through `moq-quic`'s -moq-clock, which #6132 accepted (its decision 4), so no crate is added; B -also makes it public API. Recommended: A. +kio becomes a direct dependency of the `driver` feature. It is already in the +driver-only tree through `moq-quic`'s moq-clock, which #6132 accepted (its +decision 4), so no crate is added, and it stays out of the public API. Builds on the `stopped` waiter map as #6196 left it, which already records a local reset. It blocks the driver half of [poll_acked](/quest/m2/quic-ack-hook.md). -The acceptance test is the measured leak: 1000 waiters that poll once and are -dropped unresolved leave no live registration behind, checked before the +The acceptance test is the measured leak: 1000 cloned handles that each poll +once and are dropped unresolved leave no live registration behind, checked before the condition is ever signalled, so release on drop is what passes it, not the next wake. Also, on paused time: two handles waiting on each condition both wake; one handle polled 100 times holds one live registration; a clone's poll