feat(kio): add WaiterCell and Queue

[kixelated]

Summary

• WaiterCell: retains a strong Waiter across Context-based polls, bridging poll_* trait methods to kio's waiter-based polls. hold(cx) reuses the retained waiter after a wakeup (same task, no live registrations) to skip the per-poll Arc allocation, and replaces it otherwise so WaiterList GC can reclaim retired slots. wait() and Pending use it internally, picking up the same reuse.
• Waiter is now Clone, sharing identity: a clone wakes the same task and its registrations count as the original's, staying live until every clone drops. This is the escape hatch for a poll method that needs &mut self of the type holding the cell: clone the waiter to end the cell borrow.
• Queue: a poll-native FIFO queue in the Shared style. Role-less clone-able handles, bounded or unbounded, split push/pop waiter lists so a push never wakes parked pushers, explicit close() with drain-before-Closed pops. poll_push_with takes a closure so a pending push builds nothing and hands nothing back.
• moq-net's Driver now retains its waiter with WaiterCell instead of hand-rolling the same dance (and cloning the waker every poll).

Motivation: qmux (moq-dev/web-transport) is being converted to a poll-first state machine implementing the new web-transport-trait sans-I/O poll traits, built on kio. These are the two pieces kio was missing for Context-based poll surfaces; Queue should also be reusable in moq-net (e.g. rebuilding TaskSet's submission channel without futures::channel::mpsc).

Public API changes

All additive, in kio:

• pub struct WaiterCell with new(), hold(&mut self, &mut Context) -> &Waiter; Clone yields an idle cell.
• impl Clone for Waiter (shared identity, see above).
• pub struct Queue<T> with new(), bounded(usize), try_push, poll_push_with, push, try_pop, poll_pop, pop, close, is_closed, len, is_empty, capacity, same_channel.
• pub enum PushError<T> (Full/Closed, #[non_exhaustive]) with into_inner().

Test plan

• cargo nextest run -p kio -p moq-net (648 tests, including WaiterCell replace/reuse/clone-identity and Queue unit tests).
• just loom: all 17 models (12 kio including 3 Queue wakeup/close races, 5 moq-net).
• cargo clippy --all-targets, cargo fmt, RUSTDOCFLAGS="-D warnings" cargo doc -p kio all clean.

(written by Fable 5)

[sourcery-ai]

Sorry @kixelated, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Walkthrough

The PR introduces a poll-native FIFO Queue with bounded and unbounded operations, closure handling, waiter wakeups, accessors, cloning, and tests. It updates kio documentation, module wiring, and public exports from Deque to Queue. WaiterCell now retains and conditionally reuses waiters across polls, with Pending, WaiterFn, and Driver updated accordingly. Loom tests cover queue push, pop, and close wakeups.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately highlights the main additions: WaiterCell and Queue.
Description check	✅ Passed	The description clearly matches the changes and explains the new APIs, behavior, and test plan.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/kio-waiter-cell-deque

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

rs/kio/src/deque.rs (2)

262-263: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Name the inline test module tests.

Other kio modules use mod tests; this one is mod test.

♻️ Proposed change

 #[cfg(all(test, not(loom)))]
-mod test {
+mod tests {

As per coding guidelines: "Keep Rust tests inline as #[cfg(test)] mod tests".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rs/kio/src/deque.rs` around lines 262 - 263, Rename the inline test module in
deque.rs from test to tests, preserving its existing test configuration and
contents. Ensure it follows the project convention of #[cfg(test)] mod tests.

Source: Coding guidelines

---

150-159: 🗄️ Data Integrity & Integration | 🔵 Trivial | 🏗️ Heavy lift

push silently drops the item on close.

Documented, but a push that loses data on a race with close is easy to misuse; consider returning PushError<T> (or a Closed-with-item variant) so the caller can recover the item, matching try_push.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rs/kio/src/deque.rs` around lines 150 - 159, Update the `push` method to
return a recoverable error such as `PushError<T>` when the queue closes before
accepting the item, preserving the item for callers just as `try_push` does.
Adjust the `crate::wait` closure and method documentation to propagate the item
on closure rather than silently dropping it, while retaining the existing
successful push behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@rs/kio/src/deque.rs`:
- Around line 65-72: Replace all em dashes in the affected documentation and
comments: in rs/kio/src/deque.rs lines 65-72, change the Deque type
documentation dash to a semicolon; in rs/kio/src/deque.rs lines 124-130, change
the poll_push_with documentation dash to a comma clause; in rs/kio/src/waiter.rs
lines 168-176, replace both WaiterCell::register documentation dashes with
parentheses or commas; and in rs/kio/src/pollable.rs lines 40-42, change the
waiter field comment dash to a semicolon.
- Around line 9-15: Mark the public PushError enum as #[non_exhaustive] so
future variants can be added without breaking downstream exhaustive matches.
Leave its existing variants and documentation unchanged.

---

Nitpick comments:
In `@rs/kio/src/deque.rs`:
- Around line 262-263: Rename the inline test module in deque.rs from test to
tests, preserving its existing test configuration and contents. Ensure it
follows the project convention of #[cfg(test)] mod tests.
- Around line 150-159: Update the `push` method to return a recoverable error
such as `PushError<T>` when the queue closes before accepting the item,
preserving the item for callers just as `try_push` does. Adjust the
`crate::wait` closure and method documentation to propagate the item on closure
rather than silently dropping it, while retaining the existing successful push
behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9b4d19d6-3997-4e46-8d72-ab40515b8045

📥 Commits

Reviewing files that changed from the base of the PR and between 9edd2b2 and c844ed2.

📒 Files selected for processing (6)

• rs/kio/README.md
• rs/kio/src/deque.rs
• rs/kio/src/lib.rs
• rs/kio/src/loom.rs
• rs/kio/src/pollable.rs
• rs/kio/src/waiter.rs

[coderabbitai]

🧹 Nitpick comments (1)

rs/kio/src/queue.rs (1)

264-264: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Rename mod test to mod tests for consistency.

waiter.rs uses mod tests (plural). As per coding guidelines: "Tests should be inline as #[cfg(test)] mod tests in the source file."

♻️ Proposed rename

-mod test {
+mod tests {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rs/kio/src/queue.rs` at line 264, Rename the inline test module declaration
from mod test to mod tests in queue.rs, keeping its #[cfg(test)] annotation and
test contents unchanged.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@rs/kio/src/queue.rs`:
- Line 264: Rename the inline test module declaration from mod test to mod tests
in queue.rs, keeping its #[cfg(test)] annotation and test contents unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ba1ae851-59ad-44e0-bded-121f1072b57b

📥 Commits

Reviewing files that changed from the base of the PR and between 077b383 and fd78d8e.

📒 Files selected for processing (7)

• rs/kio/README.md
• rs/kio/src/lib.rs
• rs/kio/src/loom.rs
• rs/kio/src/pollable.rs
• rs/kio/src/queue.rs
• rs/kio/src/waiter.rs
• rs/moq-net/src/session.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• rs/kio/src/pollable.rs

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

rs/kio/src/queue.rs (1)

133-144: 🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift

Do not invoke make while holding the queue mutex.

Line 143 executes caller-controlled code while state is locked. A closure can capture this queue and call another queue method, causing a deadlock; slow construction also blocks every queue operation. Preserve lazy construction by reserving capacity before unlocking and committing afterward, or redesign the API so user code does not run under the lock. Add a regression test for a reentrant factory with a timeout.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rs/kio/src/queue.rs` around lines 133 - 144, The poll_push_with method
currently invokes the caller-provided make closure while holding the queue state
mutex, allowing reentrant deadlocks and blocking other operations. Reserve queue
capacity and record the pending push under the lock, release it before calling
make, then reacquire the lock to commit the item while preserving closed-state
handling and capacity correctness; add a timeout-based regression test using a
reentrant factory.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@rs/kio/src/queue.rs`:
- Around line 133-144: The poll_push_with method currently invokes the
caller-provided make closure while holding the queue state mutex, allowing
reentrant deadlocks and blocking other operations. Reserve queue capacity and
record the pending push under the lock, release it before calling make, then
reacquire the lock to commit the item while preserving closed-state handling and
capacity correctness; add a timeout-based regression test using a reentrant
factory.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 917240d0-810b-4dc5-b404-943a76f56022

📥 Commits

Reviewing files that changed from the base of the PR and between fd78d8e and d4de299.

📒 Files selected for processing (4)

• rs/kio/src/pollable.rs
• rs/kio/src/queue.rs
• rs/kio/src/waiter.rs
• rs/moq-net/src/session.rs