apache / apache/asyncband

Proposal: Cross-runtime correctness validation for asyncband primitives

Open
#154 6 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.