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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/release-gate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,7 @@ jobs:
# Exactly the workspace crates run.sh builds; sh/gh/ts-paths.py fails Check on drift.
- "rs/hang/**"
- "rs/kio/**"
- "rs/kio/macros/**"
- "rs/moq-archive/**"
- "rs/moq-auth/**"
- "rs/moq-cli/**"
Expand Down
34 changes: 34 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
[workspace]
# Keep source-only members discoverable in Maturin's dependency-pruned archive,
# including the separately packaged UniFFI generator.
members = ["demo/carla/bridge", "rs/*", "rs/moq-clock/macros", "rs/moq-net/fuzz", "rs/moq-quic/fuzz"]
members = ["demo/carla/bridge", "rs/*", "rs/kio/macros", "rs/moq-clock/macros", "rs/moq-net/fuzz", "rs/moq-quic/fuzz"]
default-members = [
"rs/bench-harness",
"rs/kio",
"rs/kio/macros",
"rs/hang",
# "rs/moq-c", # requires C toolchain
"rs/moq-clock",
Expand Down Expand Up @@ -126,6 +127,7 @@ indexmap = "2.14.2"
io-uring = "0.7.15"
jsonwebtoken = "11"
kio = { version = "0.6.2", path = "rs/kio" }
kio-macros = { version = "0.1.0", path = "rs/kio/macros" }
libc = "0.2"
libloading = "0.9"
linux-raw-sys = { version = "0.12.1", features = ["ioctl"] }
Expand Down
2 changes: 1 addition & 1 deletion doc/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ replaces it.

- **Binaries:** [moq-relay](https://github.com/moq-dev/moq/blob/main/rs/moq-relay/MIGRATE.md), [moq-cli (`moq`)](https://github.com/moq-dev/moq/blob/main/rs/moq-cli/MIGRATE.md), [moq-gst](https://github.com/moq-dev/moq/blob/main/rs/moq-gst/MIGRATE.md), [obs-moq](https://github.com/moq-dev/moq/blob/main/cpp/obs/MIGRATE.md)
- **Bindings:** [moq-ffi (UniFFI)](https://github.com/moq-dev/moq/blob/main/rs/moq-ffi/MIGRATE.md), [moq-c (C)](https://github.com/moq-dev/moq/blob/main/rs/moq-c/MIGRATE.md), [Python](https://github.com/moq-dev/moq/blob/main/py/moq-rs/MIGRATE.md), [Go](https://github.com/moq-dev/moq/blob/main/go/wrapper/MIGRATE.md), [Swift](https://github.com/moq-dev/moq/blob/main/swift/MIGRATE.md), [Kotlin](https://github.com/moq-dev/moq/blob/main/kt/moq/MIGRATE.md), [Dart](https://github.com/moq-dev/moq/blob/main/dart/moq/MIGRATE.md), [C++](https://github.com/moq-dev/moq/blob/main/cpp/moq/MIGRATE.md)
- **Rust:** [hang](https://github.com/moq-dev/moq/blob/main/rs/hang/MIGRATE.md), [kio](https://github.com/moq-dev/moq/blob/main/rs/kio/MIGRATE.md), [moq-archive](https://github.com/moq-dev/moq/blob/main/rs/moq-archive/MIGRATE.md), [moq-audio](https://github.com/moq-dev/moq/blob/main/rs/moq-audio/MIGRATE.md), [moq-auth](https://github.com/moq-dev/moq/blob/main/rs/moq-auth/MIGRATE.md), [moq-boy](https://github.com/moq-dev/moq/blob/main/rs/moq-boy/MIGRATE.md), [moq-clock](https://github.com/moq-dev/moq/blob/main/rs/moq-clock/MIGRATE.md), [moq-clock-macros](https://github.com/moq-dev/moq/blob/main/rs/moq-clock/macros/MIGRATE.md), [moq-e2ee](https://github.com/moq-dev/moq/blob/main/rs/moq-e2ee/MIGRATE.md), [moq-hls](https://github.com/moq-dev/moq/blob/main/rs/moq-hls/MIGRATE.md), [moq-ice](https://github.com/moq-dev/moq/blob/main/rs/moq-ice/MIGRATE.md), [moq-json](https://github.com/moq-dev/moq/blob/main/rs/moq-json/MIGRATE.md), [moq-loc](https://github.com/moq-dev/moq/blob/main/rs/moq-loc/MIGRATE.md), [moq-msf](https://github.com/moq-dev/moq/blob/main/rs/moq-msf/MIGRATE.md), [moq-mux](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/MIGRATE.md), [moq-net](https://github.com/moq-dev/moq/blob/main/rs/moq-net/MIGRATE.md), [moq-nvenc](https://github.com/moq-dev/moq/blob/main/rs/moq-nvenc/MIGRATE.md), [moq-pattern](https://github.com/moq-dev/moq/blob/main/rs/moq-pattern/MIGRATE.md), [moq-quic](https://github.com/moq-dev/moq/blob/main/rs/moq-quic/MIGRATE.md), [moq-room](https://github.com/moq-dev/moq/blob/main/rs/moq-room/MIGRATE.md), [moq-rtc](https://github.com/moq-dev/moq/blob/main/rs/moq-rtc/MIGRATE.md), [moq-rtmp](https://github.com/moq-dev/moq/blob/main/rs/moq-rtmp/MIGRATE.md), [moq-sock](https://github.com/moq-dev/moq/blob/main/rs/moq-sock/MIGRATE.md), [moq-srt](https://github.com/moq-dev/moq/blob/main/rs/moq-srt/MIGRATE.md), [moq-stats](https://github.com/moq-dev/moq/blob/main/rs/moq-stats/MIGRATE.md), [moq-tokio](https://github.com/moq-dev/moq/blob/main/rs/moq-tokio/MIGRATE.md), [moq-transcode](https://github.com/moq-dev/moq/blob/main/rs/moq-transcode/MIGRATE.md), [moq-uring](https://github.com/moq-dev/moq/blob/main/rs/moq-uring/MIGRATE.md), [moq-v4l](https://github.com/moq-dev/moq/blob/main/rs/moq-v4l/MIGRATE.md), [moq-video](https://github.com/moq-dev/moq/blob/main/rs/moq-video/MIGRATE.md), [qmux](https://github.com/moq-dev/moq/blob/main/rs/qmux/MIGRATE.md)
- **Rust:** [hang](https://github.com/moq-dev/moq/blob/main/rs/hang/MIGRATE.md), [kio](https://github.com/moq-dev/moq/blob/main/rs/kio/MIGRATE.md), [kio-macros](https://github.com/moq-dev/moq/blob/main/rs/kio/macros/MIGRATE.md), [moq-archive](https://github.com/moq-dev/moq/blob/main/rs/moq-archive/MIGRATE.md), [moq-audio](https://github.com/moq-dev/moq/blob/main/rs/moq-audio/MIGRATE.md), [moq-auth](https://github.com/moq-dev/moq/blob/main/rs/moq-auth/MIGRATE.md), [moq-boy](https://github.com/moq-dev/moq/blob/main/rs/moq-boy/MIGRATE.md), [moq-clock](https://github.com/moq-dev/moq/blob/main/rs/moq-clock/MIGRATE.md), [moq-clock-macros](https://github.com/moq-dev/moq/blob/main/rs/moq-clock/macros/MIGRATE.md), [moq-e2ee](https://github.com/moq-dev/moq/blob/main/rs/moq-e2ee/MIGRATE.md), [moq-hls](https://github.com/moq-dev/moq/blob/main/rs/moq-hls/MIGRATE.md), [moq-ice](https://github.com/moq-dev/moq/blob/main/rs/moq-ice/MIGRATE.md), [moq-json](https://github.com/moq-dev/moq/blob/main/rs/moq-json/MIGRATE.md), [moq-loc](https://github.com/moq-dev/moq/blob/main/rs/moq-loc/MIGRATE.md), [moq-msf](https://github.com/moq-dev/moq/blob/main/rs/moq-msf/MIGRATE.md), [moq-mux](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/MIGRATE.md), [moq-net](https://github.com/moq-dev/moq/blob/main/rs/moq-net/MIGRATE.md), [moq-nvenc](https://github.com/moq-dev/moq/blob/main/rs/moq-nvenc/MIGRATE.md), [moq-pattern](https://github.com/moq-dev/moq/blob/main/rs/moq-pattern/MIGRATE.md), [moq-quic](https://github.com/moq-dev/moq/blob/main/rs/moq-quic/MIGRATE.md), [moq-room](https://github.com/moq-dev/moq/blob/main/rs/moq-room/MIGRATE.md), [moq-rtc](https://github.com/moq-dev/moq/blob/main/rs/moq-rtc/MIGRATE.md), [moq-rtmp](https://github.com/moq-dev/moq/blob/main/rs/moq-rtmp/MIGRATE.md), [moq-sock](https://github.com/moq-dev/moq/blob/main/rs/moq-sock/MIGRATE.md), [moq-srt](https://github.com/moq-dev/moq/blob/main/rs/moq-srt/MIGRATE.md), [moq-stats](https://github.com/moq-dev/moq/blob/main/rs/moq-stats/MIGRATE.md), [moq-tokio](https://github.com/moq-dev/moq/blob/main/rs/moq-tokio/MIGRATE.md), [moq-transcode](https://github.com/moq-dev/moq/blob/main/rs/moq-transcode/MIGRATE.md), [moq-uring](https://github.com/moq-dev/moq/blob/main/rs/moq-uring/MIGRATE.md), [moq-v4l](https://github.com/moq-dev/moq/blob/main/rs/moq-v4l/MIGRATE.md), [moq-video](https://github.com/moq-dev/moq/blob/main/rs/moq-video/MIGRATE.md), [qmux](https://github.com/moq-dev/moq/blob/main/rs/qmux/MIGRATE.md)
- **JavaScript:** [`@moq/auth`](https://github.com/moq-dev/moq/blob/main/js/auth/MIGRATE.md), [`@moq/boy`](https://github.com/moq-dev/moq/blob/main/js/moq-boy/MIGRATE.md), [`@moq/clock`](https://github.com/moq-dev/moq/blob/main/js/clock/MIGRATE.md), [`@moq/hang`](https://github.com/moq-dev/moq/blob/main/js/hang/MIGRATE.md), [`@moq/json`](https://github.com/moq-dev/moq/blob/main/js/json/MIGRATE.md), [`@moq/loc`](https://github.com/moq-dev/moq/blob/main/js/loc/MIGRATE.md), [`@moq/msf`](https://github.com/moq-dev/moq/blob/main/js/msf/MIGRATE.md), [`@moq/net`](https://github.com/moq-dev/moq/blob/main/js/net/MIGRATE.md), [`@moq/p2p`](https://github.com/moq-dev/moq/blob/main/js/p2p/MIGRATE.md), [`@moq/pattern`](https://github.com/moq-dev/moq/blob/main/js/pattern/MIGRATE.md), [`@moq/publish`](https://github.com/moq-dev/moq/blob/main/js/publish/MIGRATE.md), [`@moq/qmux`](https://github.com/moq-dev/moq/blob/main/js/qmux/MIGRATE.md), [`@moq/room`](https://github.com/moq-dev/moq/blob/main/js/room/MIGRATE.md), [`@moq/signals`](https://github.com/moq-dev/moq/blob/main/js/signals/MIGRATE.md), [`@moq/ui`](https://github.com/moq-dev/moq/blob/main/js/ui/MIGRATE.md), [`@moq/video`](https://github.com/moq-dev/moq/blob/main/js/video/MIGRATE.md), [`@moq/watch`](https://github.com/moq-dev/moq/blob/main/js/watch/MIGRATE.md)

## Unreleased
Expand Down
6 changes: 3 additions & 3 deletions quest/m1/poll-first/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,13 @@ and their alternatives:
type-check and borrow-check cost matches hand-written code; it adds about 1.5 ms
of expansion per machine plus a one-time 1.3 s build of `kio-macros`, below what
async costs. The cost is a dialect: stored locals need type annotations and are
`&mut` inside a wait's poll, and a `!Send` error doesn't name the wait. Its users
are moq-net's 23 straight-line multi-await `async fn` bodies and 12 straight-line
`&mut` inside a wait's poll, and a `!Send` error names the type and the wait but
not the local: the generated state keeps Rust's automatic `Send`, with no
`unsafe impl` (decided 2026-10-28). Its users are moq-net's 23 straight-line multi-await `async fn` bodies and 12 straight-line
hand-written machines; 59 bodies await in loops or selects.

## Required

- [kio::machine](/quest/m1/poll-first/machine.md) - kio's `macros` feature writes straight-line `poll_*` bodies, landing with the hand-written machines it replaces
- [Straight-line bodies become machines](/quest/m1/poll-first/machine-bodies.md) - moq-net's straight-line `async fn` bodies become `#[kio::machine]` polls
- [Generated async wrappers behind a feature](/quest/m1/poll-first/async-feature.md) - each library's `async fn` wrappers are generated from its `poll_*` signatures and compile only with its `async` feature
- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - web-async goes, and moq-ffi, moq-stats, moq-wasm and moq-relay's cluster and auth run as polled `kio::Tasks` children instead of spawned tasks
15 changes: 8 additions & 7 deletions quest/m1/poll-first/machine-bodies.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,10 @@ generate wrappers for them. Behavior and public signatures are unchanged.

## Plan

Decided with the maintainer on 2026-10-28: split from
[kio::machine](/quest/m1/poll-first/machine.md) so the macro lands with its
hand-written machines first, and these conversions follow as their own PR.
Decided with the maintainer on 2026-10-28: split from the kio::machine quest,
which landed the macro with its hand-written machines in
[moq-dev/moq#7148](https://github.com/moq-dev/moq/pull/7148), so these
conversions follow as their own PR.
Bodies with a loop or a branch around a wait stay with async-feature, which
converts them by hand.

Expand All @@ -21,9 +22,9 @@ converts them by hand.
- The existing tests are the proof; add one only where a conversion changes
cancellation (a value that used to drop at an `.await` now lives in a named
variant).
- The macro has only the `impl` form: an `async fn`'s parameters become the
struct's fields. A conditional wait is one whose poll is ready at once, and a
wait that ends the body is `Poll::Ready(wait!(..))`; see `kio::machine`'s docs
for the rest of the dialect.

Public API: none. Wire: none.

## Required

- [kio::machine](/quest/m1/poll-first/machine.md) - the macro these conversions use
46 changes: 0 additions & 46 deletions quest/m1/poll-first/machine.md

This file was deleted.

1 change: 1 addition & 0 deletions rs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Two ways to drive things, both backed by `kio`:

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. Don't color APIs with `Send` bounds that native needs and wasm can't satisfy.

- 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`.
- `Poll<Result<T, E>>` supports `?`: `ready!(poll())?` or `match poll()?`.
- Prefer `Ok(x?)` over `.map_err(Into::into)`.
Expand Down
3 changes: 3 additions & 0 deletions rs/kio/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,15 @@ keywords = ["async", "producer", "consumer", "state", "sync"]
categories = ["asynchronous", "concurrency"]

[features]
# `#[kio::machine]`, which writes a `poll_*` state machine from straight-line code.
macros = ["dep:kio-macros"]
# Per-task Ready poll accounting for deterministic simulators, never production.
_sim = []

[dependencies]
# Frees a log's evicted segments once no read that could reach them is running.
crossbeam-epoch = "0.9.21"
kio-macros = { workspace = true, optional = true }
smallvec = { version = "1.15", features = ["union"] }

# Loom swaps in its own Arc/Mutex/atomics so it can permute every interleaving.
Expand Down
2 changes: 2 additions & 0 deletions rs/kio/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ waiter-based polls when implementing `Future` or `poll_*` on top of kio channels
work ready still yields to the rest of its runtime. `log::Writer` is an append-only
log whose `log::Reader`s read committed entries by index without a lock, paired with
a channel that parks them; evicted entries are freed by epoch-based reclamation.
With the `macros` feature, `#[kio::machine]` writes a `poll_*` state machine from
straight-line code with explicit waits.

It's used internally by [moq-net](https://github.com/moq-dev/moq/tree/main/rs/moq-net) and friends, but is generic enough to be useful on its own.

Expand Down
35 changes: 35 additions & 0 deletions rs/kio/macros/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# The `#[kio::machine]` attribute. A separate crate only because a proc macro
# must be; `kio` re-exports it behind its `macros` feature.
[package]
name = "kio-macros"
description = "The #[kio::machine] attribute; use it through kio's macros feature."
authors = ["Luke Curley"]
repository = "https://github.com/moq-dev/moq"
license = "MIT OR Apache-2.0"

version = "0.1.0"
edition = "2024"
rust-version.workspace = true

keywords = ["async", "poll", "state-machine"]
categories = ["asynchronous"]

[lib]
proc-macro = true

[dependencies]
proc-macro2 = "1"
quote = "1"
# syn 2, not 3: moq-net's graph already builds syn 2 with `full` and `visit-mut`
# (thiserror, tracing), so the macro adds no syn build of its own there.
syn = { version = "2", features = ["full", "visit-mut"] }

[dev-dependencies]
kio = { path = "..", features = ["macros"] }
# Runs the UI cases outside clippy, which would print their types with full paths.
test-env = { path = "../../test-env" }
# Compiles each mistake in `tests/ui/` and checks the diagnostic it reports.
trybuild = "1"

[lints]
workspace = true
5 changes: 5 additions & 0 deletions rs/kio/macros/MIGRATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Migrating kio-macros

How to update your code for each breaking change, newest first.

## Unreleased
Loading
Loading