Proposal: Cross-runtime correctness validation for asyncband primitives
- Dominant language
- Rust
- Stars
- 269
- Forks
- 38
- Avg merge
- 16h 44m
- Merged PRs (30d)
- 102
Description
## Motivation
Asyncband advertises itself as runtime-agnostic, but our test suite is effectively Tokio-only: all tests run under `#[tokio::test]` (mostly the single-threaded current-thread runtime), and benchmarks poll futures directly without a real executor. This leaves waker registration, cancellation, and wake-up races under real multi-threaded scheduling unverified, which undermines the core promise of the crate.
This proposal adds a cross-runtime correctness validation suite that exercises the library's primitives under the commonly used Rust async runtimes and gates it in CI.
## Target runtimes
Primary matrix (all platforms, active maintenance):
- **tokio** – de facto standard; multi-threaded work-stealing runtime. Required baseline.
- **async-std** – still one of the mainstream runtimes listed in the official async book.
- **smol** – the lightweight, composable runtime; representative of the async-executor/async-lock ecosystem.
- **compio** - one thread per core async runtime
Secondary matrix (Linux-only):
- **glommio** – io_uring-based thread-per-core runtime (no Mutex, tasks are `!Send`).
- **monoio** – io_uring-based thread-per-core runtime (limited sync primitives).
## Scope
- Build a small runtime-agnostic test harness (spawn / join / yield / timeout adapters) and run a shared semantic test suite for each primitive on every runtime in the primary matrix.
- Validate guaranteed properties only (no lost wakeups, correct cancellation, close/disconnect semantics, single-flight/once dedup, no deadlock on single-threaded executors) — not implementation-specific fairness guarantees.
- CI: run the primary matrix on Ubuntu, macOS, and Windows (stable toolchain only); run the secondary matrix on Ubuntu as a Linux-only job.
- Keep the existing Tokio test suite and microbenchmarks unchanged.
## Open questions
- Should the secondary matrix (glommio, monoio) be required or informational in CI?
- Do we want **benchmark comparisons** against runtime-native primitives(e.g. `tokio::sync::Mutex`) in this proposal, or a follow-up?
- Where should the harness live: a separate non-workspace test crate to keep heavy runtime dependencies out of regular `cargo test`?
- Is there any project that we can leverage? e.g. [loom](https://github.com/tokio-rs/loom)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the existing #[tokio::test] suite and microbenchmarks, then map the primitives and semantics that need shared coverage. Define a runtime-agnostic harness for the listed primary runtimes and determine how secondary runtimes and CI jobs fit. Done means the guaranteed properties are validated across the stated matrix while existing Tokio tests and benchmarks remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend, ci-cd, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100