diff --git a/quest/m1/poll-first/async-feature.md b/quest/m1/poll-first/async-feature.md index 34da9f18275..8d7b31b3c20 100644 --- a/quest/m1/poll-first/async-feature.md +++ b/quest/m1/poll-first/async-feature.md @@ -14,12 +14,34 @@ and the bindings and JS keep their APIs. Decided with the maintainer on 2026-10-25: poll is canonical, async is the ergonomic layer, and the gating proceeds regardless of the build measurement. -- **Spike the generator first** on kio and one moq-net module, then pick one: - - a `macro_rules!` over a list of signatures (no proc-macro cost); - - a proc macro attribute on the `poll_*` method or its impl block; - - a rust2-driver lowering. - Compare compile time (clean and edit, on moq-net), error spans, and docs output. - A wrapper's docs come from its `poll_*` method. +Decided with the maintainer on 2026-11-01, from the +[generator spike](https://github.com/moq-dev/moq/blob/91b1ec62e1e35295ef74d0f7cee1afc49739bf00/bench/async-wrappers/RESULTS.md): +the generator is a method attribute in kio-macros, `#[kio::wrapper]`. The poll +stays ordinary Rust, the wrapper's name, signature, and docs are derived from it, +and a standalone kio build with `async` pays the measured proc-macro cost (about +3.5 seconds clean). + +Done in [moq-dev/moq#7506](https://github.com/moq-dev/moq/pull/7506): +`#[kio::wrapper]` with its contract in kio-macros' behavior and UI tests; kio's +default-off `async` feature, under which kio compiles no coroutines; moq-net's +`async` enabling `kio/async`; moq-net's four `broadcast` wrappers generated; and +`just rs coroutines`, in the nightly feature matrix, which scans the MIR of kio's +and moq-net's poll-only builds. Callers gate the attribute with +`#[cfg_attr(feature = "async", kio::wrapper)]`, so a poll-only build skips the +proc macro, and the scan catches a wrapper left ungated. + +What remains: + +- **moq-net's remaining wrappers:** about 47 hand-written + `kio::wait(|waiter| self.poll_x(waiter, ..)).await` wrappers become the attribute + on their polls, each poll's docs rewritten to read for both forms. A few stay + hand-written: those that take a closure by value and poll it by `&mut`, and the + `#[cfg(test)]` helpers the poll-only tests use. +- **moq-net's poll-only coroutines:** `auth::until` (behind `Grant::guard`), and + `model::origin`'s `run_front` and `serve_front`, still compile without `async`. + Gate `until` with its async callers, or make it a poll, and turn the front + driver into a hand-written poll machine (its body is one large `kio::wait`). + Then drop their `--allow`s from `just rs coroutines`. - **Logic in `async fn` bodies:** an `async fn` that does more than call one `poll_*` becomes a `poll_*` first, or moves out of the library to the edges. List each one in the PR. moq-net's straight-line ones became `#[kio::machine]`s in @@ -28,14 +50,19 @@ ergonomic layer, and the gating proceeds regardless of the build measurement. bodies with a loop or a branch around a wait (about 59 in moq-net) are converted by hand, since the macro stays straight-line only (decided 2026-10-28). +- **Sibling libraries:** the poll-based libraries with hand-written wrappers + (moq-mux, moq-hls, moq-auth, moq-stats, moq-room, moq-json, moq-sign, moq-e2ee, + qmux, and others) gain an `async` feature, generate their wrappers, and join + `just rs coroutines`. +- **Default off:** moq-net's `async` feature is still on by default. Turn it off, + and enable it at the edges: binaries, tests, tokio glue, and the bindings. - **Tests:** `#[kio::test]` and `#[tokio::test]` bodies stay async, so test targets enable the feature. - **Cargo:** feature unification means one dependent enabling `async` enables it for the whole build. Make sure library-only builds, such as `cargo check -p moq-net` and the rust2 bench's library-only build, leave it off. -- **Docs:** update `rs/AGENTS.md`'s rule ("New logic is a `poll_*` with an `async` - helper") to say the helper is generated and feature-gated. Public API: every library crate gains an `async` feature, and its async wrappers move behind it. Add an Impact migration note for the published crates whenever -a consumer must enable `async`, including with `default-features = false`. +a consumer must enable `async`, including with `default-features = false`, as +`rs/kio/MIGRATE.md` does for kio. diff --git a/rs/AGENTS.md b/rs/AGENTS.md index 4b3cd8bb03e..9d406f4cf5c 100644 --- a/rs/AGENTS.md +++ b/rs/AGENTS.md @@ -20,9 +20,9 @@ Most crates use a split-handle pattern: a `Producer` writes, any number of `Cons Two ways to drive things, both backed by `kio`: - `poll_*` functions take a `&kio::Waiter` and return `Poll<...>`, drivable from any executor or synchronously. Like `Future`, but wakers are cleaned up on drop. -- `async fn` wrappers, usually `kio::wait(|waiter| self.poll_x(waiter))`. +- `async fn` wrappers, `kio::wait(|waiter| self.poll_x(waiter))`, generated by `#[cfg_attr(feature = "async", kio::wrapper)]` on the poll (kio's `macros` feature) and compiled only with the crate's `async` feature. Write the poll's docs for both forms: what it resolves to, not how it registers. -Prefer poll. New logic is a `poll_*` with an `async` helper, not the other way around. `pin!` then polling inside `kio::wait` is a code smell, as is `tokio::spawn` / `select!` inside a library; use `kio` primitives. +Prefer poll. New logic is a `poll_*` with a generated `async` wrapper, not the other way around. A library build without `async` compiles no coroutines; `just rs coroutines` checks kio's and moq-net's. `pin!` then polling inside `kio::wait` is a code smell, as is `tokio::spawn` / `select!` inside a library; use `kio` primitives. - A `poll_*` that waits on several things in a fixed order is a `#[kio::machine]` (kio's `macros` feature): straight-line code with a `wait!` at each wait, from which it writes the state enum and its transitions. Hand-write the machine when a wait sits in a loop or branch, or when it yields more than once (a stream's `poll_next`). A conditional wait is one whose poll is ready at once. - Use `ready!(...)` instead of `Poll::Pending => return Poll::Pending`. diff --git a/rs/justfile b/rs/justfile index 571fdd318de..019382be7a0 100644 --- a/rs/justfile +++ b/rs/justfile @@ -215,6 +215,7 @@ c-tests: # Compile the full feature matrix, including isolated combinations and their tests. features: just rs net-features --all + just rs coroutines just rs quic-features --all just rs tokio-features --all just rs media-features --all @@ -226,6 +227,8 @@ features: just rs test -p moq-cli --no-default-features --features capture,pipewire,websocket -E 'test(capture_window)' bash sh/local.sh cargo check --locked -p moq-bench --no-default-features bash sh/local.sh cargo check --locked -p moq-boy --no-default-features + # Alone, since the workspace's `kio/sim` dev-dependencies would unify `kio/async` back in. + bash sh/local.sh cargo check --locked --manifest-path rs/moq-auth/Cargo.toml --lib --all-features bash sh/local.sh cargo check --locked -p moq-hls -p moq-rtmp -p moq-rtc --no-default-features --all-targets bash sh/local.sh cargo clippy --locked --workspace {{ no_fuzz }} --all-targets --all-features -- -D warnings RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked --workspace {{ no_fuzz }} --all-features --no-deps @@ -236,6 +239,13 @@ features: net-features *args: bash sh/rs/net-features.sh "$@" +# Prove the poll-only library builds compile no coroutines and document cleanly. +# moq-net allows the async fns still waiting on a poll conversion. +coroutines: + bash sh/rs/coroutines.sh kio -- --no-default-features --features macros,runtime,manual,serde + RUSTDOCFLAGS="-D warnings" bash sh/local.sh cargo doc --locked -p kio --no-deps --no-default-features --features macros,runtime,manual,serde + bash sh/rs/coroutines.sh moq-net --allow until --allow run_front --allow serve_front -- --no-default-features + # Prove moq-quic leaves kio's dev-only clock runtime to its consumers, and lints without its default features; a workspace build unifies both back in. [positional-arguments] quic-features *args: diff --git a/rs/kio/Cargo.toml b/rs/kio/Cargo.toml index 89d89fcb1b0..1b457a46767 100644 --- a/rs/kio/Cargo.toml +++ b/rs/kio/Cargo.toml @@ -13,26 +13,32 @@ keywords = ["async", "producer", "consumer", "clock", "simulation"] categories = ["asynchronous", "concurrency", "date-and-time", "development-tools::testing"] [package.metadata.docs.rs] -features = ["runtime", "manual", "sim", "serde", "macros"] +features = ["async", "runtime", "manual", "sim", "serde", "macros"] # The self dev-dependency below only enables features; no code names it. [package.metadata.cargo-shear] ignored = ["kio"] [features] -# Lean by default: without `runtime`, the clock compiles no host timer backend. +# Lean by default: without `runtime`, the clock compiles no host timer backend, and +# without `async`, no coroutines. default = [] +# The `async fn` beside each `poll_*` method, generated by `#[kio::wrapper]`, and the +# few `async` helpers with no poll of their own (`Queue::push`, the `wait` predicates, +# `clock::drive`, `Interval::tick`). Off by default: enable it where you `.await`. +async = ["macros"] # Host timers on tokio's clock. runtime = ["dep:tokio"] # The deterministic single-threaded executor, `#[kio::test]`, and per-task Ready # poll accounting. Meant for dev-dependencies, so production builds never compile it. -sim = ["dep:futures", "dep:kio-macros"] +sim = ["async", "dep:futures"] # `clock::Manual::install`: a clock that only a test moves, as one tokio runtime's # ambient clock. Meant for test builds, so production builds never compile it. manual = ["runtime"] # Numeric Unix-second JSON adapters for public wall times. serde = ["dep:serde", "dep:serde_with"] -# `#[kio::machine]`, which writes a `poll_*` state machine from straight-line code. +# `#[kio::machine]`, which writes a `poll_*` state machine from straight-line code, and +# `#[kio::wrapper]`, which writes the `async fn` that awaits one. macros = ["dep:kio-macros"] [dependencies] @@ -51,9 +57,9 @@ tokio = { workspace = true, features = ["rt", "time"], optional = true } # Bench-only: the FuturesUnordered comparison in benches/tasks.rs. criterion = { package = "bench-harness", path = "../bench-harness" } futures = "0.3" -# Enable the simulator and the installed manual clock so the clock's tests run in -# the merge gate. -kio = { path = ".", features = ["manual", "sim", "serde"] } +# Enable the async wrappers, the simulator, and the installed manual clock so the +# tests that await them run in the merge gate. +kio = { path = ".", features = ["async", "manual", "sim", "serde"] } serde_json = { workspace = true } test-env = { path = "../test-env" } tokio = { workspace = true, features = ["macros", "rt", "rt-multi-thread", "test-util", "time"] } diff --git a/rs/kio/MIGRATE.md b/rs/kio/MIGRATE.md index 2810c099b36..33830c627fc 100644 --- a/rs/kio/MIGRATE.md +++ b/rs/kio/MIGRATE.md @@ -4,6 +4,14 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `async` methods moved behind the `async` feature + +`Queue::{push, pop}`, `Producer::{wait, closed, wanted_changed}`, `Consumer::{wait, +closed}`, `Shared::wait`, `ConsumerWeak::closed`, `ProducerWeak::closed`, +`clock::drive`, and `clock::Interval::tick` now compile only with the new `async` +feature, which is off by default; `sim` enables it. Add `features = ["async"]` to +the `kio` dependency of each crate that `.await`s them. Each `poll_*` method is unchanged, and still drives the same wait without it. + ### `Pollable` merged into `Task`, and unused surface removed (#4156) `Fan`, `Hold`, `WeakLock`, `Pollable`, and the public `Lock::downgrade` are gone. diff --git a/rs/kio/macros/src/lib.rs b/rs/kio/macros/src/lib.rs index c0127347d67..b28c7e341fd 100644 --- a/rs/kio/macros/src/lib.rs +++ b/rs/kio/macros/src/lib.rs @@ -89,6 +89,68 @@ pub fn machine(args: proc_macro::TokenStream, item: proc_macro::TokenStream) -> } mod sim_test; +mod wrapper; + +/// Generate the `async fn` that waits on a `poll_*` method. +/// +/// On `poll_`, it adds `async fn ` beside it, `kio::wait`ing on the poll. +/// The wrapper takes the poll's receiver and arguments, minus the waiter, and returns +/// what the poll is ready with. It copies the poll's visibility, generics, docs, `cfg`, +/// and deprecation, then links back to the poll. The poll stays as written, so its +/// docs describe both forms: what the call is ready with, not how it registers. +/// +/// ``` +/// use std::task::Poll; +/// +/// struct Counter { +/// values: kio::Queue, +/// } +/// +/// impl Counter { +/// /// The next value at or above `min`, skipping smaller ones. +/// #[kio::wrapper] +/// fn poll_at_least(&self, waiter: &kio::Waiter, min: u64) -> Poll> { +/// loop { +/// match self.values.poll_pop(waiter) { +/// Poll::Ready(Ok(value)) if value < min => continue, +/// other => return other, +/// } +/// } +/// } +/// } +/// +/// # async fn demo(counter: Counter) -> Result { +/// // Generated: `async fn at_least(&self, min: u64) -> Result`. +/// counter.at_least(10).await +/// # } +/// ``` +/// +/// A library keeps its wrappers behind its `async` feature, and its poll-only build +/// free of this macro, with `#[cfg_attr(feature = "async", kio::wrapper)]`. +/// +/// The poll must: +/// +/// - Be a method taking `&self` or `&mut self`, not `async`, `const`, `unsafe`, or +/// `extern`. +/// - Take exactly one `&Waiter` (any path ending in `Waiter`), in any position. +/// - Bind every other argument to a plain name (`mut` is dropped). The wrapper passes +/// each one to every poll unchanged, so it must be `Copy` or a reference; rustc +/// reports the move from the closure otherwise. +/// - Return `Poll` (any path ending in `Poll`). The wrapper returns `T`. +/// +/// Other attributes, such as `#[track_caller]` or `#[inline]`, stay on the poll alone. +#[proc_macro_attribute] +pub fn wrapper(args: proc_macro::TokenStream, item: proc_macro::TokenStream) -> proc_macro::TokenStream { + let method = parse_macro_input!(item as syn::ImplItemFn); + // A rejected poll still compiles, so the error is the only one reported. + wrapper::expand(args.into(), &method) + .unwrap_or_else(|err| { + let mut out = method.to_token_stream(); + out.extend(err.into_compile_error()); + out + }) + .into() +} /// Run an `async fn` test to completion on `kio::clock::sim::run`. #[proc_macro_attribute] diff --git a/rs/kio/macros/src/wrapper.rs b/rs/kio/macros/src/wrapper.rs new file mode 100644 index 00000000000..28d13400590 --- /dev/null +++ b/rs/kio/macros/src/wrapper.rs @@ -0,0 +1,240 @@ +//! The `#[kio::wrapper]` expansion: an `async fn` beside the `poll_*` method it waits on. + +use proc_macro2::{Span, TokenStream}; +use quote::quote; +use syn::{ + Attribute, FnArg, GenericArgument, GenericParam, Ident, ImplItemFn, Pat, PathArguments, ReturnType, Type, + ext::IdentExt, punctuated::Punctuated, spanned::Spanned, +}; + +pub(crate) fn expand(args: TokenStream, method: &ImplItemFn) -> syn::Result { + if !args.is_empty() { + return Err(syn::Error::new_spanned(args, "#[kio::wrapper] takes no arguments")); + } + let sig = &method.sig; + if let Some(token) = &sig.asyncness { + return Err(syn::Error::new_spanned( + token, + "#[kio::wrapper] goes on a poll method, not an `async fn`", + )); + } + if let Some(token) = &sig.constness { + return Err(syn::Error::new_spanned( + token, + "#[kio::wrapper] cannot wrap a `const fn`", + )); + } + if let Some(token) = &sig.unsafety { + return Err(syn::Error::new_spanned( + token, + "#[kio::wrapper] cannot wrap an `unsafe fn`", + )); + } + if let Some(abi) = &sig.abi { + return Err(syn::Error::new_spanned( + abi, + "#[kio::wrapper] cannot wrap an `extern fn`", + )); + } + if let Some(variadic) = &sig.variadic { + return Err(syn::Error::new_spanned( + variadic, + "#[kio::wrapper] cannot wrap a variadic fn", + )); + } + + let poll = &sig.ident; + let name = poll.to_string(); + let Some(name) = name.strip_prefix("poll_").filter(|name| !name.is_empty()) else { + return Err(syn::Error::new_spanned( + poll, + "#[kio::wrapper] needs a `poll_` method", + )); + }; + // `poll_match` waits as `r#match`. `poll_self`, `poll__`, and `poll_1` have no + // such name: those keywords cannot be raw, and a digit cannot start one. + let name = if syn::parse_str::(name).is_ok() { + Ident::new(name, poll.span()) + } else if syn::parse::Parser::parse_str(Ident::parse_any, name).is_ok() + && !matches!(name, "_" | "self" | "Self" | "super" | "crate") + { + Ident::new_raw(name, poll.span()) + } else { + return Err(syn::Error::new_spanned( + poll, + format!("#[kio::wrapper] cannot name the wrapper `{name}`, even as a raw identifier"), + )); + }; + + let mut inputs = sig.inputs.iter(); + let receiver = match inputs.next() { + Some(FnArg::Receiver(receiver)) if receiver.reference.is_some() && receiver.colon_token.is_none() => receiver, + Some(FnArg::Receiver(receiver)) => { + return Err(syn::Error::new_spanned( + receiver, + "#[kio::wrapper] needs a borrowed receiver, `&self` or `&mut self`", + )); + } + _ => { + return Err(syn::Error::new( + sig.paren_token.span.join(), + "#[kio::wrapper] needs a borrowed receiver, `&self` or `&mut self`", + )); + } + }; + + // Every other argument is passed through to each poll; the waiter is the wrapper's own. + let waiter = Ident::new("waiter", Span::mixed_site()); + let mut params = Punctuated::::new(); + let mut call = Vec::new(); + let mut found = None; + for input in inputs { + let FnArg::Typed(input) = input else { + return Err(syn::Error::new_spanned(input, "`self` must be the first argument")); + }; + if let Some(mutable) = waiter_ref(&input.ty) { + if mutable { + return Err(syn::Error::new_spanned( + &input.ty, + "#[kio::wrapper] needs the waiter as `&Waiter`, not `&mut Waiter`", + )); + } + if let Some(first) = found.replace(input) { + let mut err = + syn::Error::new_spanned(&input.ty, "#[kio::wrapper] needs exactly one `&Waiter` argument"); + err.combine(syn::Error::new_spanned(&first.ty, "the first `&Waiter` is here")); + return Err(err); + } + call.push(quote! { #waiter }); + continue; + } + let Pat::Ident(pat) = input.pat.as_ref() else { + return Err(syn::Error::new_spanned( + &input.pat, + "#[kio::wrapper] needs each argument bound to a plain name", + )); + }; + if pat.by_ref.is_some() || pat.subpat.is_some() { + return Err(syn::Error::new_spanned( + &input.pat, + "#[kio::wrapper] needs each argument bound to a plain name", + )); + } + // `mut` only affects the poll's own binding: the wrapper never rebinds it. + let mut param = input.clone(); + param.pat = Box::new(Pat::Ident(syn::PatIdent { + mutability: None, + ..pat.clone() + })); + params.push(FnArg::Typed(param)); + let ident = &pat.ident; + call.push(quote! { #ident }); + } + if found.is_none() { + return Err(syn::Error::new( + sig.paren_token.span.join(), + "#[kio::wrapper] needs a `&Waiter` argument", + )); + } + + let output = ready_type(sig)?; + + // Type and const parameters, named so the wrapper never relies on inference to pick them. + let turbofish = sig + .generics + .params + .iter() + .filter_map(|param| match param { + GenericParam::Type(param) => Some(¶m.ident), + GenericParam::Const(param) => Some(¶m.ident), + GenericParam::Lifetime(_) => None, + }) + .collect::>(); + let turbofish = match turbofish.is_empty() { + true => quote! {}, + false => quote! { ::<#(#turbofish),*> }, + }; + + let mut wrapper = sig.clone(); + wrapper.ident = name; + wrapper.asyncness = Some(syn::Token![async](poll.span())); + wrapper.inputs = std::iter::once(FnArg::Receiver(receiver.clone())) + .chain(params) + .collect(); + wrapper.output = match output { + Type::Tuple(unit) if unit.elems.is_empty() => ReturnType::Default, + output => syn::parse_quote_spanned!(sig.output.span()=> -> #output), + }; + + let attrs = method.attrs.iter().filter(|attr| copied(attr)).collect::>(); + let link = format!("Awaits [`{poll}`](Self::{poll})."); + let link = match attrs.iter().any(|attr| attr.path().is_ident("doc")) { + true => quote! { #[doc = ""] #[doc = #link] }, + false => quote! { #[doc = #link] }, + }; + // A deprecated wrapper calls its deprecated poll without a warning of its own. + let allow = match attrs.iter().any(|attr| attr.path().is_ident("deprecated")) { + true => quote! { #[allow(deprecated, reason = "a deprecated wrapper of a deprecated poll")] }, + false => quote! {}, + }; + let vis = &method.vis; + // The receiver's own `self`, which a `self` spanned anywhere else would not resolve to. + let this = &receiver.self_token; + + Ok(quote! { + #method + + #(#attrs)* + #link + #allow + #vis #wrapper { + ::kio::wait(|#waiter| #this.#poll #turbofish(#(#call),*)).await + } + }) +} + +/// Whether `ty` is a `&mut` if it is a reference to `Waiter` (by any path ending in it). +fn waiter_ref(ty: &Type) -> Option { + let Type::Reference(reference) = ty else { return None }; + let Type::Path(path) = reference.elem.as_ref() else { + return None; + }; + let waiter = path.qself.is_none() + && path + .path + .segments + .last() + .is_some_and(|segment| segment.ident == "Waiter" && segment.arguments.is_none()); + waiter.then_some(reference.mutability.is_some()) +} + +/// `T` from `-> Poll`, by any path ending in `Poll`. +fn ready_type(sig: &syn::Signature) -> syn::Result<&Type> { + const MESSAGE: &str = "#[kio::wrapper] needs a method returning `Poll`"; + let output = &sig.output; + let error = || syn::Error::new_spanned(output, MESSAGE); + let ReturnType::Type(_, ty) = output else { + // No return type to point at: point where it would go. + return Err(syn::Error::new(sig.paren_token.span.close(), MESSAGE)); + }; + let Type::Path(path) = ty.as_ref() else { + return Err(error()); + }; + let Some(segment) = path.path.segments.last().filter(|segment| segment.ident == "Poll") else { + return Err(error()); + }; + let PathArguments::AngleBracketed(arguments) = &segment.arguments else { + return Err(error()); + }; + match arguments.args.first() { + Some(GenericArgument::Type(ty)) if arguments.args.len() == 1 => Ok(ty), + _ => Err(error()), + } +} + +/// What the wrapper inherits: docs, the conditions it compiles under, and deprecation. +fn copied(attr: &Attribute) -> bool { + ["doc", "cfg", "deprecated"] + .iter() + .any(|name| attr.path().is_ident(name)) +} diff --git a/rs/kio/macros/tests/ui/wrapper_moved_argument.rs b/rs/kio/macros/tests/ui/wrapper_moved_argument.rs new file mode 100644 index 00000000000..18572e63618 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_moved_argument.rs @@ -0,0 +1,13 @@ +// An argument that is neither `Copy` nor a reference: every poll would move it. +use std::task::Poll; + +struct S; + +impl S { + #[kio::wrapper] + fn poll_len(&self, _waiter: &kio::Waiter, name: String) -> Poll { + Poll::Ready(name.len()) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_moved_argument.stderr b/rs/kio/macros/tests/ui/wrapper_moved_argument.stderr new file mode 100644 index 00000000000..4987429988c --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_moved_argument.stderr @@ -0,0 +1,21 @@ +error[E0507]: cannot move out of value, a captured variable in an `FnMut` closure + --> tests/ui/wrapper_moved_argument.rs:8:44 + | +7 | #[kio::wrapper] + | --------------- captured by this `FnMut` closure +8 | fn poll_len(&self, _waiter: &kio::Waiter, name: String) -> Poll { + | ^^^^ + | | + | captured outer variable + | move occurs because value has type `String`, which does not implement the `Copy` trait + | value is moved here + | +help: `Fn` and `FnMut` closures require captured values to be able to be consumed multiple times, but `FnOnce` closures may consume them only once + --> $WORKSPACE/rs/kio/src/waiter.rs + | + | F: FnMut(&Waiter) -> Poll + Unpin, + | ^^^^^^^^^^^^^^^^^^^^^^^^^ +help: consider cloning the value if the performance cost is acceptable + | +8 | fn poll_len(&self, _waiter: &kio::Waiter, name.clone(): String) -> Poll { + | ++++++++ diff --git a/rs/kio/macros/tests/ui/wrapper_name.rs b/rs/kio/macros/tests/ui/wrapper_name.rs new file mode 100644 index 00000000000..7bc1e4002e2 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_name.rs @@ -0,0 +1,13 @@ +// A method without the `poll_` prefix. +use std::task::Poll; + +struct S(kio::Queue); + +impl S { + #[kio::wrapper] + fn pop(&self, waiter: &kio::Waiter) -> Poll> { + self.0.poll_pop(waiter) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_name.stderr b/rs/kio/macros/tests/ui/wrapper_name.stderr new file mode 100644 index 00000000000..ff6c34a2dfa --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_name.stderr @@ -0,0 +1,5 @@ +error: #[kio::wrapper] needs a `poll_` method + --> tests/ui/wrapper_name.rs:8:5 + | +8 | fn pop(&self, waiter: &kio::Waiter) -> Poll> { + | ^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_no_receiver.rs b/rs/kio/macros/tests/ui/wrapper_no_receiver.rs new file mode 100644 index 00000000000..3a2e40753f4 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_no_receiver.rs @@ -0,0 +1,13 @@ +// An associated function, with no receiver to borrow. +use std::task::Poll; + +struct S; + +impl S { + #[kio::wrapper] + fn poll_ready(_waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_no_receiver.stderr b/rs/kio/macros/tests/ui/wrapper_no_receiver.stderr new file mode 100644 index 00000000000..3ebc739bab9 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_no_receiver.stderr @@ -0,0 +1,5 @@ +error: #[kio::wrapper] needs a borrowed receiver, `&self` or `&mut self` + --> tests/ui/wrapper_no_receiver.rs:8:15 + | +8 | fn poll_ready(_waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_output.rs b/rs/kio/macros/tests/ui/wrapper_output.rs new file mode 100644 index 00000000000..b6f3b560503 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_output.rs @@ -0,0 +1,15 @@ +// A method that is not ready with a value: no return type, or not a `Poll`. + +struct S; + +impl S { + #[kio::wrapper] + fn poll_nothing(&self, _waiter: &kio::Waiter) {} + + #[kio::wrapper] + fn poll_option(&self, _waiter: &kio::Waiter) -> Option<()> { + None + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_output.stderr b/rs/kio/macros/tests/ui/wrapper_output.stderr new file mode 100644 index 00000000000..d8caf52258d --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_output.stderr @@ -0,0 +1,11 @@ +error: #[kio::wrapper] needs a method returning `Poll` + --> tests/ui/wrapper_output.rs:7:46 + | +7 | fn poll_nothing(&self, _waiter: &kio::Waiter) {} + | ^ + +error: #[kio::wrapper] needs a method returning `Poll` + --> tests/ui/wrapper_output.rs:10:47 + | +10 | fn poll_option(&self, _waiter: &kio::Waiter) -> Option<()> { + | ^^^^^^^^^^^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_owned_receiver.rs b/rs/kio/macros/tests/ui/wrapper_owned_receiver.rs new file mode 100644 index 00000000000..4f5a313b289 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_owned_receiver.rs @@ -0,0 +1,13 @@ +// An owned receiver, which every poll would consume. +use std::task::Poll; + +struct S(kio::Queue); + +impl S { + #[kio::wrapper] + fn poll_pop(self, waiter: &kio::Waiter) -> Poll> { + self.0.poll_pop(waiter) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_owned_receiver.stderr b/rs/kio/macros/tests/ui/wrapper_owned_receiver.stderr new file mode 100644 index 00000000000..e42d963a545 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_owned_receiver.stderr @@ -0,0 +1,5 @@ +error: #[kio::wrapper] needs a borrowed receiver, `&self` or `&mut self` + --> tests/ui/wrapper_owned_receiver.rs:8:14 + | +8 | fn poll_pop(self, waiter: &kio::Waiter) -> Poll> { + | ^^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_pattern.rs b/rs/kio/macros/tests/ui/wrapper_pattern.rs new file mode 100644 index 00000000000..ef9662dd3e2 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_pattern.rs @@ -0,0 +1,13 @@ +// An argument destructured in place: the wrapper has no name to pass it by. +use std::task::Poll; + +struct S; + +impl S { + #[kio::wrapper] + fn poll_pair(&self, _waiter: &kio::Waiter, (a, b): (u8, u8)) -> Poll { + Poll::Ready(a + b) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_pattern.stderr b/rs/kio/macros/tests/ui/wrapper_pattern.stderr new file mode 100644 index 00000000000..0f1d5497743 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_pattern.stderr @@ -0,0 +1,5 @@ +error: #[kio::wrapper] needs each argument bound to a plain name + --> tests/ui/wrapper_pattern.rs:8:45 + | +8 | fn poll_pair(&self, _waiter: &kio::Waiter, (a, b): (u8, u8)) -> Poll { + | ^^^^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_qualifiers.rs b/rs/kio/macros/tests/ui/wrapper_qualifiers.rs new file mode 100644 index 00000000000..ecfb4e0d8dd --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_qualifiers.rs @@ -0,0 +1,28 @@ +// Qualifiers an `async fn` wrapper cannot carry, and an argument to the attribute. +use std::task::Poll; + +struct S; + +impl S { + #[kio::wrapper] + async fn poll_async(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper] + const fn poll_const(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper] + unsafe fn poll_unsafe(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper(name = ready)] + fn poll_named(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_qualifiers.stderr b/rs/kio/macros/tests/ui/wrapper_qualifiers.stderr new file mode 100644 index 00000000000..83ca87975df --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_qualifiers.stderr @@ -0,0 +1,23 @@ +error: #[kio::wrapper] goes on a poll method, not an `async fn` + --> tests/ui/wrapper_qualifiers.rs:8:2 + | +8 | async fn poll_async(&self, _waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^ + +error: #[kio::wrapper] cannot wrap a `const fn` + --> tests/ui/wrapper_qualifiers.rs:13:2 + | +13 | const fn poll_const(&self, _waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^ + +error: #[kio::wrapper] cannot wrap an `unsafe fn` + --> tests/ui/wrapper_qualifiers.rs:18:2 + | +18 | unsafe fn poll_unsafe(&self, _waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^^ + +error: #[kio::wrapper] takes no arguments + --> tests/ui/wrapper_qualifiers.rs:22:17 + | +22 | #[kio::wrapper(name = ready)] + | ^^^^^^^^^^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_unnameable.rs b/rs/kio/macros/tests/ui/wrapper_unnameable.rs new file mode 100644 index 00000000000..51861f94d70 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_unnameable.rs @@ -0,0 +1,23 @@ +// A poll whose wrapper name is no identifier, even raw. +use std::task::Poll; + +struct S; + +impl S { + #[kio::wrapper] + fn poll_self(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper] + fn poll__(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper] + fn poll_1(&self, _waiter: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_unnameable.stderr b/rs/kio/macros/tests/ui/wrapper_unnameable.stderr new file mode 100644 index 00000000000..a54c02a2573 --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_unnameable.stderr @@ -0,0 +1,17 @@ +error: #[kio::wrapper] cannot name the wrapper `self`, even as a raw identifier + --> tests/ui/wrapper_unnameable.rs:8:5 + | +8 | fn poll_self(&self, _waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^^^^^ + +error: #[kio::wrapper] cannot name the wrapper `_`, even as a raw identifier + --> tests/ui/wrapper_unnameable.rs:13:5 + | +13 | fn poll__(&self, _waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^^ + +error: #[kio::wrapper] cannot name the wrapper `1`, even as a raw identifier + --> tests/ui/wrapper_unnameable.rs:18:5 + | +18 | fn poll_1(&self, _waiter: &kio::Waiter) -> Poll<()> { + | ^^^^^^ diff --git a/rs/kio/macros/tests/ui/wrapper_waiter.rs b/rs/kio/macros/tests/ui/wrapper_waiter.rs new file mode 100644 index 00000000000..7a2fe365a4c --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_waiter.rs @@ -0,0 +1,23 @@ +// No waiter, two, and a mutable one. +use std::task::Poll; + +struct S; + +impl S { + #[kio::wrapper] + fn poll_none(&self) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper] + fn poll_two(&self, _a: &kio::Waiter, _b: &kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } + + #[kio::wrapper] + fn poll_mutable(&self, _waiter: &mut kio::Waiter) -> Poll<()> { + Poll::Ready(()) + } +} + +fn main() {} diff --git a/rs/kio/macros/tests/ui/wrapper_waiter.stderr b/rs/kio/macros/tests/ui/wrapper_waiter.stderr new file mode 100644 index 00000000000..4eb1a45ac5d --- /dev/null +++ b/rs/kio/macros/tests/ui/wrapper_waiter.stderr @@ -0,0 +1,23 @@ +error: #[kio::wrapper] needs a `&Waiter` argument + --> tests/ui/wrapper_waiter.rs:8:14 + | +8 | fn poll_none(&self) -> Poll<()> { + | ^^^^^^^ + +error: #[kio::wrapper] needs exactly one `&Waiter` argument + --> tests/ui/wrapper_waiter.rs:13:43 + | +13 | fn poll_two(&self, _a: &kio::Waiter, _b: &kio::Waiter) -> Poll<()> { + | ^^^^^^^^^^^^ + +error: the first `&Waiter` is here + --> tests/ui/wrapper_waiter.rs:13:25 + | +13 | fn poll_two(&self, _a: &kio::Waiter, _b: &kio::Waiter) -> Poll<()> { + | ^^^^^^^^^^^^ + +error: #[kio::wrapper] needs the waiter as `&Waiter`, not `&mut Waiter` + --> tests/ui/wrapper_waiter.rs:18:34 + | +18 | fn poll_mutable(&self, _waiter: &mut kio::Waiter) -> Poll<()> { + | ^^^^^^^^^^^^^^^^ diff --git a/rs/kio/macros/tests/wrapper.rs b/rs/kio/macros/tests/wrapper.rs new file mode 100644 index 00000000000..f62cbd89da6 --- /dev/null +++ b/rs/kio/macros/tests/wrapper.rs @@ -0,0 +1,191 @@ +//! What `#[kio::wrapper]` generates for each poll shape it accepts. + +use std::{ + pin::pin, + task::{Context, Poll, Waker}, +}; + +/// One poll of `fut` on a waker that does nothing. +fn poll_once(fut: F) -> Poll { + pin!(fut).poll(&mut Context::from_waker(Waker::noop())) +} + +struct Values { + queue: kio::Queue, + taken: Vec, +} + +impl Values { + fn new(values: &[u64]) -> Self { + let queue = kio::Queue::new(); + for value in values { + queue.try_push(*value).unwrap(); + } + Self { + queue, + taken: Vec::new(), + } + } + + /// The next value. + #[kio::wrapper] + fn poll_next(&self, waiter: &kio::Waiter) -> Poll> { + self.queue.poll_pop(waiter) + } + + /// The next value at or above `min`, keeping the smaller ones it skips. + #[kio::wrapper] + pub fn poll_at_least(&mut self, w: &kio::Waiter, mut min: u64) -> Poll> { + min = min.max(1); + loop { + match self.queue.poll_pop(w) { + Poll::Ready(Ok(value)) if value < min => self.taken.push(value), + other => return other, + } + } + } + + /// Moves the next value into `into`, with the waiter last. + #[kio::wrapper] + fn poll_move_into(&self, into: &mut Vec, waiter: &kio::Waiter) -> Poll<()> { + if let Poll::Ready(Ok(value)) = self.queue.poll_pop(waiter) { + into.push(value); + } + Poll::Ready(()) + } + + /// The next value, converted: `T` appears only in the return type. + #[kio::wrapper] + fn poll_convert>(&self, waiter: &kio::Waiter) -> std::task::Poll> { + self.queue.poll_pop(waiter).map(|value| value.ok().map(T::from)) + } + + /// Kept for compatibility. + #[deprecated = "use `poll_next`"] + #[kio::wrapper] + fn poll_old(&self, waiter: &kio::Waiter) -> Poll> { + self.queue.poll_pop(waiter) + } + + /// The next value, under a keyword's name. + #[kio::wrapper] + fn poll_match(&self, waiter: &kio::Waiter) -> Poll> { + self.queue.poll_pop(waiter) + } + + /// Only compiled where the poll is. + #[cfg(test)] + #[kio::wrapper] + fn poll_conditional(&self, waiter: &kio::Waiter) -> Poll> { + self.queue.poll_pop(waiter) + } + + /// Never compiled: a wrapper without the poll's `cfg` would call a missing method. + #[cfg(not(test))] + #[kio::wrapper] + fn poll_missing(&self, waiter: &kio::Waiter) -> Poll> { + self.queue.poll_pop(waiter) + } +} + +#[test] +fn awaits_the_poll() { + let values = Values::new(&[1]); + assert_eq!(poll_once(values.next()), Poll::Ready(Ok(1))); + assert_eq!(poll_once(values.next()), Poll::Pending); + values.queue.close(); + assert_eq!(poll_once(values.next()), Poll::Ready(Err(kio::Closed))); +} + +#[test] +fn passes_arguments_to_every_poll() { + let mut values = Values::new(&[1, 2]); + let mut at_least = Box::pin(values.at_least(3)); + assert_eq!(poll_once(at_least.as_mut()), Poll::Pending); + drop(at_least); + assert_eq!(values.taken, [1, 2]); + + values.queue.try_push(4).unwrap(); + assert_eq!(poll_once(values.at_least(3)), Poll::Ready(Ok(4))); + + let mut into = Vec::new(); + values.queue.try_push(5).unwrap(); + assert_eq!(poll_once(values.move_into(&mut into)), Poll::Ready(())); + assert_eq!(into, [5]); +} + +#[test] +fn names_the_generic_parameters() { + let values = Values::new(&[7]); + assert_eq!(poll_once(values.convert::()), Poll::Ready(Some(7u128))); +} + +#[test] +#[allow(deprecated, reason = "awaits the deprecated wrapper")] +fn keeps_attributes() { + let values = Values::new(&[1, 2]); + assert_eq!(poll_once(values.old()), Poll::Ready(Ok(1))); + assert_eq!(poll_once(values.conditional()), Poll::Ready(Ok(2))); +} + +#[test] +fn escapes_a_keyword_name() { + let values = Values::new(&[3]); + assert_eq!(poll_once(values.r#match()), Poll::Ready(Ok(3))); +} + +/// A wrapper on a generic impl, beside a machine that waits on it. +struct Pair { + queue: kio::Queue, +} + +impl Pair { + /// The next item. + #[kio::wrapper] + fn poll_item(&self, waiter: &kio::Waiter) -> Poll> { + self.queue.poll_pop(waiter) + } +} + +struct Sum { + pair: Pair, + state: SumState, +} + +#[kio::machine(self.state: SumState)] +impl Sum { + /// Two items, added. + #[kio::wrapper] + fn poll_sum(&mut self, waiter: &kio::Waiter) -> Poll> { + let first: u64 = wait!(First => self.pair.poll_item(waiter))?; + let second = wait!(Second => self.pair.poll_item(waiter))?; + Poll::Ready(Ok(first + second)) + } +} + +#[test] +fn composes_with_a_machine() { + let mut sum = Sum { + pair: Pair { + queue: kio::Queue::new(), + }, + state: SumState::Start, + }; + sum.pair.queue.try_push(1).unwrap(); + assert_eq!(poll_once(sum.sum()), Poll::Pending); + assert_eq!(sum.state.name(), "Second"); + sum.pair.queue.try_push(2).unwrap(); + assert_eq!(poll_once(sum.sum()), Poll::Ready(Ok(3))); +} + +#[test] +fn is_send_when_its_borrows_are() { + fn send(fut: F) -> F { + fut + } + let pair = Pair { + queue: kio::Queue::new(), + }; + pair.queue.try_push(1u64).unwrap(); + assert_eq!(poll_once(send(pair.item())), Poll::Ready(Ok(1))); +} diff --git a/rs/kio/src/clock/mod.rs b/rs/kio/src/clock/mod.rs index b11693d8bf0..bd16fd7e327 100644 --- a/rs/kio/src/clock/mod.rs +++ b/rs/kio/src/clock/mod.rs @@ -8,8 +8,8 @@ //! [`Deadline`]s on a [`Deadlines`] queue, and tests step them with a //! [`Manual`] clock. //! - Async code reads the ambient clock: [`now`], [`wall`], [`sleep`], -//! [`sleep_until`], [`timeout`], [`interval`], and [`drive`] resolve to the -//! current runtime's clock. That is tokio's (paused tokio included), the +//! [`sleep_until`], [`timeout`], [`interval`], and `drive` (with the `async` +//! feature) resolve to the current runtime's clock. That is tokio's (paused tokio included), the //! simulator inside `sim::run`, and a [`Deadlines`] queue on a thread that //! [entered](Deadlines::enter) it, which is how a runtime that reads the host //! clock itself (an io_uring worker) becomes a backend. @@ -52,8 +52,10 @@ pub use installed::Installed; pub use instant::Instant; pub use manual::Manual; pub use random::{Rng, rng, seed}; +#[cfg(feature = "async")] +pub use timer::drive; pub use timer::{ - Elapsed, Interval, MissedTickBehavior, Sleep, Timeout, drive, interval, interval_at, sleep, sleep_until, timeout, + Elapsed, Interval, MissedTickBehavior, Sleep, Timeout, interval, interval_at, sleep, sleep_until, timeout, timeout_at, }; pub use wall::{OutOfRange, Wall, WallMap}; diff --git a/rs/kio/src/clock/timer.rs b/rs/kio/src/clock/timer.rs index 8cadf58ef66..c296390792f 100644 --- a/rs/kio/src/clock/timer.rs +++ b/rs/kio/src/clock/timer.rs @@ -229,6 +229,7 @@ pub fn interval_at(start: Instant, period: Duration) -> Interval { impl Interval { /// Wait for the next tick, returning the instant it was scheduled for. + #[cfg(feature = "async")] pub async fn tick(&mut self) -> Instant { std::future::poll_fn(|cx| self.poll_tick(cx)).await } @@ -275,6 +276,7 @@ impl Interval { /// /// `poll` is called with the current instant and returns when it next wants to be /// polled: `Ok(Some(at))` by `at` or on a wake, `Ok(None)` only on a wake. +#[cfg(feature = "async")] pub async fn drive(mut poll: impl FnMut(Instant, &crate::Waiter) -> Result, E> + Unpin) -> E { let mut timer: Option = None; crate::wait(move |waiter| { diff --git a/rs/kio/src/consumer.rs b/rs/kio/src/consumer.rs index 8d47ad38bec..b55b0be7ee2 100644 --- a/rs/kio/src/consumer.rs +++ b/rs/kio/src/consumer.rs @@ -3,14 +3,14 @@ use std::{ task::Poll, }; -use crate::{Closed, Counts, State, lock::*, producer::Ref, waiter::*, weak::ConsumerWeak}; +use crate::{Counts, State, lock::*, producer::Ref, waiter::*, weak::ConsumerWeak}; /// The consuming side of a shared state channel. /// /// Consumers have read-only access to the shared value and are notified when /// a producer modifies it. Cloning a consumer increments the consumer reference /// count. When the last consumer is dropped, the consumer-count waiters -/// (e.g. [`Producer::wanted_changed`](crate::Producer::wanted_changed)) are notified. +/// (e.g. [`Producer::poll_wanted_changed`](crate::Producer::poll_wanted_changed)) are notified. #[derive(Debug)] pub struct Consumer { pub(crate) state: Lock>, @@ -98,7 +98,8 @@ impl Consumer { Poll::Pending } - /// Poll for channel closure, registering the waiter if still open. + /// Resolves once the channel is closed. + #[cfg_attr(feature = "async", kio_macros::wrapper)] #[cfg_attr(feature = "sim", track_caller)] pub fn poll_closed(&self, waiter: &Waiter) -> Poll<()> { let mut state = self.state.lock(); @@ -112,22 +113,18 @@ impl Consumer { /// Wait for the closure to return [`Poll::Ready`], re-polling on each state change. /// - /// Returns `Ok(R)` when the closure returns [`Poll::Ready`], or [`Closed`] if the + /// Returns `Ok(R)` when the closure returns [`Poll::Ready`], or [`Closed`](crate::Closed) if the /// channel closes first. Unlike [`poll`](Self::poll) this hands back no [`Ref`], so /// no lock guard can be held across a later `.await`; call [`read`](Self::read) if /// you need the final state. - pub async fn wait(&self, mut f: F) -> Result + #[cfg(feature = "async")] + pub async fn wait(&self, mut f: F) -> Result where F: FnMut(&Ref<'_, T>) -> Poll + Unpin, { // The `Ref` is dropped here inside the closure, releasing the lock before the // caller ever sees the result. - crate::wait(move |waiter| self.poll(waiter, &mut f).map(|res| res.map_err(|_| Closed))).await - } - - /// Wait until the channel is closed. - pub async fn closed(&self) { - crate::wait(move |waiter| self.poll_closed(waiter)).await + crate::wait(move |waiter| self.poll(waiter, &mut f).map(|res| res.map_err(|_| crate::Closed))).await } /// Get read-only access to the shared state. diff --git a/rs/kio/src/lib.rs b/rs/kio/src/lib.rs index 734fac1f482..40cc551e23e 100644 --- a/rs/kio/src/lib.rs +++ b/rs/kio/src/lib.rs @@ -24,8 +24,12 @@ //! [`clock`] is the time those waits run on: logical instants, wall time, //! deadlines, timers, and a deterministic simulator for tests. //! +//! Every wait is a `poll_*` method first. The `async` feature adds the `async fn` that +//! awaits each one, so a build without it compiles no coroutines (`async` bodies). +//! //! With the `macros` feature, `#[kio::machine]` writes a `poll_*` state machine from -//! straight-line code with explicit waits. +//! straight-line code with explicit waits, and `#[kio::wrapper]` generates the `async +//! fn` that awaits a `poll_*` method. #![warn(missing_docs)] @@ -55,7 +59,7 @@ mod weak; mod tests; #[cfg(feature = "macros")] -pub use kio_macros::machine; +pub use kio_macros::{machine, wrapper}; pub use bridge::Bridge; pub use consumer::Consumer; @@ -72,8 +76,9 @@ pub use weak::{ConsumerWeak, ProducerWeak, Weak}; #[cfg(feature = "sim")] pub use kio_macros::test; -// So `#[kio::test]` resolves inside this crate's own tests. -#[cfg(test)] +// So `#[kio::test]` resolves inside this crate's own tests, and the wrappers +// `#[kio::wrapper]` generates here reach `::kio::wait`. +#[cfg(any(test, feature = "async"))] extern crate self as kio; /// Bytes an `Arc` allocation occupies: `T` behind two reference counts, padded to diff --git a/rs/kio/src/producer.rs b/rs/kio/src/producer.rs index 8784fd153c1..d376d33b0d3 100644 --- a/rs/kio/src/producer.rs +++ b/rs/kio/src/producer.rs @@ -176,6 +176,7 @@ impl Producer { /// [`Poll::Ready`], or [`Closed`] if the channel closes first. The `Ok` guard is the /// write access you asked for, so it's yours to hold; the `Err` case hands back no /// guard at all. Call [`read`](Self::read) if you need the final state. + #[cfg(feature = "async")] pub async fn wait(&self, mut f: F) -> Result, Closed> where F: FnMut(&Ref<'_, T>) -> Poll<()> + Unpin, @@ -185,13 +186,8 @@ impl Producer { crate::wait(move |waiter| self.poll(waiter, &mut f).map(|res| res.map_err(|_| Closed))).await } - /// Wait until the channel is closed. - pub async fn closed(&self) { - crate::wait(move |waiter| self.poll_closed(waiter)).await - } - - /// Poll for channel closure (an explicit [`Mut::close`], e.g. an abort), - /// registering the waiter if still open. + /// Resolves once the channel is closed (an explicit [`Mut::close`], e.g. an abort). + #[cfg_attr(feature = "async", kio_macros::wrapper)] #[cfg_attr(feature = "sim", track_caller)] pub fn poll_closed(&self, waiter: &Waiter) -> Poll<()> { let mut state = self.state.lock(); @@ -211,14 +207,9 @@ impl Producer { self.counts.consumers.load(Ordering::Relaxed) > 0 } - /// Wait until [`Self::wanted`] differs from `last`, returning the new value, or - /// [`Closed`] if the channel closes first. - pub async fn wanted_changed(&self, last: bool) -> Result { - crate::wait(move |waiter| self.poll_wanted_changed(waiter, last)).await - } - - /// Poll for [`Self::wanted`] to differ from `last`: `Ready(Ok)` with the new value once - /// it does, [`Closed`] if the channel closed first, else `Pending`. + /// Resolves to the new [`Self::wanted`] once it differs from `last`, or [`Closed`] if + /// the channel closes first. + #[cfg_attr(feature = "async", kio_macros::wrapper)] #[cfg_attr(feature = "sim", track_caller)] pub fn poll_wanted_changed(&self, waiter: &Waiter, last: bool) -> Poll> { // Closure is checked first, so a closed channel reports `Closed` from every handle diff --git a/rs/kio/src/queue.rs b/rs/kio/src/queue.rs index d750affbddb..e84138b797d 100644 --- a/rs/kio/src/queue.rs +++ b/rs/kio/src/queue.rs @@ -68,8 +68,8 @@ impl State { /// Role-less like [`Shared`](crate::Shared): every clone can push, pop, or close, /// and there is no liveness of its own: closure is explicit via /// [`close`](Self::close), never implied by dropping handles. Bounded queues park -/// pushes at capacity ([`poll_push_with`](Self::poll_push_with) / -/// [`push`](Self::push)) or reject them ([`try_push`](Self::try_push)); pops park +/// pushes at capacity ([`poll_push_with`](Self::poll_push_with), or `push` with the +/// `async` feature) or reject them ([`try_push`](Self::try_push)); pops park /// while empty. After close, pops drain what's queued before reporting [`Closed`]. /// /// An event wakes *every* waiter parked on the affected side (there is no @@ -153,6 +153,7 @@ impl Queue { /// /// Returns [`Closed`] if the queue closes first (or already was); the item is /// dropped in that case; use [`try_push`](Self::try_push) to get it back. + #[cfg(feature = "async")] pub async fn push(&self, item: T) -> Result<(), Closed> { let mut item = Some(item); // Capture the slot by `&mut` so the closure is `Unpin` regardless of `T`. @@ -177,10 +178,11 @@ impl Queue { Ok(Some(item)) } - /// Poll for the next item. + /// Pop, waiting for an item while the queue is empty. /// /// Queued items drain before closure is reported, so [`Closed`] means empty - /// *and* closed. Registers `waiter` while empty; a push or close re-polls it. + /// *and* closed. A push or close wakes the waiter. + #[cfg_attr(feature = "async", kio_macros::wrapper)] #[cfg_attr(feature = "sim", track_caller)] pub fn poll_pop(&self, waiter: &Waiter) -> Poll> { let (item, mut waiters) = { @@ -198,13 +200,6 @@ impl Queue { crate::coop::ready(Ok(item)) } - /// Pop, waiting for an item while the queue is empty. - /// - /// Returns [`Closed`] once the queue is both closed and drained. - pub async fn pop(&self) -> Result { - crate::wait(move |waiter| self.poll_pop(waiter)).await - } - /// Close the queue: pushes fail from here on, pops drain what's queued and then /// report [`Closed`]. Idempotent. pub fn close(&self) { diff --git a/rs/kio/src/shared.rs b/rs/kio/src/shared.rs index dfb850a4e0b..9728ff48019 100644 --- a/rs/kio/src/shared.rs +++ b/rs/kio/src/shared.rs @@ -87,6 +87,7 @@ impl Shared { /// /// The returned [`Mut`] holds the lock, so do your mutation and drop it rather than /// carrying it across another `.await`, which would block every other handle. + #[cfg(feature = "async")] pub async fn wait(&self, mut f: F) -> Mut<'_, T> where F: FnMut(&Ref<'_, T>) -> Poll<()> + Unpin, diff --git a/rs/kio/src/weak.rs b/rs/kio/src/weak.rs index 097db7bc0f3..deab9d53500 100644 --- a/rs/kio/src/weak.rs +++ b/rs/kio/src/weak.rs @@ -150,12 +150,8 @@ impl ProducerWeak { self.state.lock().closed } - /// Wait until the channel is closed. - pub async fn closed(&self) { - crate::wait(move |waiter| self.poll_closed(waiter)).await - } - - /// Poll for channel closure, registering the waiter if still open. + /// Resolves once the channel is closed. + #[cfg_attr(feature = "async", kio_macros::wrapper)] #[cfg_attr(feature = "sim", track_caller)] pub fn poll_closed(&self, waiter: &Waiter) -> Poll<()> { let mut state = self.state.lock(); @@ -242,7 +238,7 @@ impl ConsumerWeak { /// Poll the shared state with a closure, exactly as [`Consumer::poll`] does. /// /// Available here so a watcher can register for changes without joining the - /// consumer count, which is what [`Producer::wanted_changed`](crate::Producer::wanted_changed) + /// consumer count, which is what [`Producer::poll_wanted_changed`](crate::Producer::poll_wanted_changed) /// keys off. #[cfg_attr(feature = "sim", track_caller)] pub fn poll(&self, waiter: &Waiter, f: F) -> Poll>> @@ -271,12 +267,8 @@ impl ConsumerWeak { self.state.lock().closed } - /// Wait until the channel is closed. - pub async fn closed(&self) { - crate::wait(move |waiter| self.poll_closed(waiter)).await - } - - /// Poll for channel closure, registering the waiter if still open. + /// Resolves once the channel is closed. + #[cfg_attr(feature = "async", kio_macros::wrapper)] #[cfg_attr(feature = "sim", track_caller)] pub fn poll_closed(&self, waiter: &Waiter) -> Poll<()> { let mut state = self.state.lock(); diff --git a/rs/moq-auth/Cargo.toml b/rs/moq-auth/Cargo.toml index ccfe2f04a03..43eb004cf91 100644 --- a/rs/moq-auth/Cargo.toml +++ b/rs/moq-auth/Cargo.toml @@ -22,7 +22,8 @@ axum = { workspace = true, optional = true } base64 = { workspace = true } data-encoding = { workspace = true } jsonwebtoken = { workspace = true, features = ["aws_lc_rs"] } -kio = { workspace = true, features = ["serde"] } +# `async` for `Shared::wait`, until moq-auth grows an `async` feature of its own. +kio = { workspace = true, features = ["async", "serde"] } moq-pattern = { workspace = true, features = ["serde"] } p256 = "0.14.0" p384 = "0.14.0" diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index d0f3460b673..405dc55c83e 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -15,7 +15,7 @@ categories = ["multimedia", "network-programming", "web-programming"] [features] default = ["async"] # Runtime-backed helpers and Lite/IETF sessions; explicit-time model drivers stay available. -async = ["dep:futures", "kio/runtime"] +async = ["dep:futures", "kio/async", "kio/runtime"] # Exposes the wire codecs to the `fuzz/` harness and the announce, codec, path, varint, frame, and canonical storage benches, # and session views of an origin to the viewers bench, through the hidden `fuzz` module. Off by diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index 6150a5bff0d..b6a4a8e16b2 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -785,10 +785,11 @@ impl Requests { &self.info } - /// Poll for the next consumer-requested track, without blocking. + /// The next track a consumer requests, as a [`track::Request`] to serve. /// /// Returns [`Error::Closed`] once the broadcast has ended, so a serving loop /// knows to stop and release its handle. + #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_requested_track(&mut self, waiter: &kio::Waiter) -> Poll> { // A source that no longer names the instance that minted it takes no new track: // ending it refuses what is queued with `Unroutable`, while the tracks it handed @@ -817,12 +818,6 @@ impl Requests { Poll::Ready(Ok(pending.claim().with_stats(self.stats.clone()))) } - /// Block until a consumer requests a track, returning a [`track::Request`] to serve. - #[cfg(feature = "async")] - pub async fn requested_track(&mut self) -> Result { - kio::wait(|waiter| self.poll_requested_track(waiter)).await - } - /// Create a consumer that can subscribe to tracks in this broadcast. pub fn consume(&self) -> Consumer { Consumer { @@ -849,13 +844,8 @@ impl Requests { Lister::new(self.state.clone()) } - /// Block until the broadcast ends, by [`Producer::close`] or every producer dropping. - #[cfg(feature = "async")] - pub async fn closed(&self) { - kio::wait(|waiter| self.poll_closed(waiter)).await - } - - /// Poll until the producer closes. + /// Resolves once the broadcast ends, by [`Producer::close`] or every producer dropping. + #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_closed(&self, waiter: &kio::Waiter) -> Poll<()> { self.alive.token.poll_closed(waiter) } @@ -1053,12 +1043,6 @@ impl Consumer { BroadcastState::peek(&mut state, name).or_else(|| ended.filter(|_| state.closing).cloned()) } - /// Block until the broadcast ends, by [`Producer::close`] or every producer dropping. - #[cfg(feature = "async")] - pub async fn closed(&self) { - self.alive.closed().await - } - /// Returns true once the broadcast has ended. pub fn is_closed(&self) -> bool { self.alive.is_closed() @@ -1071,11 +1055,11 @@ impl Consumer { self.state.read().closing } - /// Register a [`kio::Waiter`] that fires when the broadcast closes. + /// Resolves once the broadcast ends, by [`Producer::close`] or every producer dropping. /// - /// Returns [`Poll::Ready`] if already closed, otherwise [`Poll::Pending`] after - /// arming the waiter. Useful for composing close-detection into a larger poll - /// without spawning a task per broadcast. + /// The poll composes close-detection into a larger one without spawning a task + /// per broadcast. + #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_closed(&self, waiter: &kio::Waiter) -> Poll<()> { self.alive.poll_closed(waiter) } @@ -1191,17 +1175,13 @@ impl Demand { !state.requests.is_empty() || state.tracks.iter().any(|track| track.is_wanted()) } - /// Return [`wanted`](Self::wanted) once it differs from what this handle last returned: - /// immediately on the first call, then on each change. Errors once the broadcast closes. + /// Resolves to [`wanted`](Self::wanted) once it differs from what this handle last + /// returned: immediately on the first call, then on each change. Errors once the + /// broadcast closes. /// /// So `while !demand.wanted_changed().await? {}` waits for a reader, and /// `while demand.wanted_changed().await? {}` waits for the last one to leave. - #[cfg(feature = "async")] - pub async fn wanted_changed(&mut self) -> Result { - kio::wait(|waiter| self.poll_wanted_changed(waiter)).await - } - - /// Poll for [`wanted`](Self::wanted) to differ from what this handle last returned. + #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_wanted_changed(&mut self, waiter: &kio::Waiter) -> Poll> { if self.alive.poll_closed(waiter).is_ready() { return Poll::Ready(Err(Error::Dropped)); diff --git a/rs/moq-shaper/Cargo.toml b/rs/moq-shaper/Cargo.toml index 6194b81cc0a..1cbd2e29855 100644 --- a/rs/moq-shaper/Cargo.toml +++ b/rs/moq-shaper/Cargo.toml @@ -25,7 +25,7 @@ anyhow = { workspace = true } clap = { workspace = true } humantime = { workspace = true } humantime-serde = { workspace = true } -kio = { workspace = true, features = ["runtime"] } +kio = { workspace = true, features = ["async", "runtime"] } rand = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } diff --git a/sh/rs/coroutines.sh b/sh/rs/coroutines.sh new file mode 100755 index 00000000000..d8cbc994a32 --- /dev/null +++ b/sh/rs/coroutines.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# Prove a poll-only library build compiles no coroutines: no `async fn` body, +# `async` block, or `async` closure in the crate's own MIR. A library's `async` +# feature carries its wrappers, so a build without it should have none. Each +# `--allow NAME` excuses the `async fn NAME` bodies still waiting on a poll +# conversion, and fails once none is left, so the list only shrinks. +# +# usage: coroutines.sh PACKAGE [--allow NAME]... [-- CARGO_ARGS...] +set -euo pipefail + +if [[ "${GITHUB_ACTIONS:-}" != true && "${LOCAL_SUPERVISED:-}" != 1 ]]; then + exec bash "$(dirname "$0")/../local.sh" bash "$0" "$@" +fi + +usage='usage: coroutines.sh PACKAGE [--allow NAME]... [-- CARGO_ARGS...]' +if [[ $# == 0 ]]; then + echo "$usage" >&2 + exit 2 +fi +package=$1 +shift +allowed=() +while [[ $# != 0 ]]; do + case "$1" in + --allow) + [[ $# -ge 2 && "$2" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || { + echo "$usage" >&2 + exit 2 + } + allowed+=("$2") + shift 2 + ;; + --) + shift + break + ;; + *) + echo "$usage" >&2 + exit 2 + ;; + esac +done + +cd "$(git rev-parse --show-toplevel)" +mir=$(mktemp) +trap 'rm -f "$mir"' EXIT + +# Only the final crate gets `--emit`, so its dependencies build as usual. +cargo rustc --locked -p "$package" --lib "$@" -- --emit "mir=$mir" + +# rustc names each coroutine by its body, as `{async fn body of queue::Queue::pop()}`, +# sometimes without the module path, so an allowed name matches as the last segment. +found=$(grep -oE '\{async (fn body of [^{}]*|block@[^{}]*|closure@[^{}]*)\}' "$mir" | sort -u || true) +unexpected=$found +for name in ${allowed[@]+"${allowed[@]}"}; do + pattern="^\{async fn body of ([A-Za-z0-9_<>, ]+::)*${name}[<(]" + if ! grep -qE -- "$pattern" <<<"$found"; then + echo "error: $package no longer compiles async fn $name; remove its --allow" >&2 + exit 1 + fi + unexpected=$(grep -vE -- "$pattern" <<<"$unexpected" || true) +done +if [[ -n "$unexpected" ]]; then + echo "error: $package compiles coroutines without its async feature:" >&2 + echo "$unexpected" >&2 + echo "Gate each behind the feature, or generate it from a poll with #[kio::wrapper]." >&2 + exit 1 +fi +echo "$package: no coroutines beyond ${#allowed[@]} allowed async fn names"