Async Rust has an unusual property: the language gives you async and await, but nothing that runs them. A future does nothing until something polls it. That something is the runtime, and for most projects it is Tokio, added with one line and one #[tokio::main] attribute. It works so well that the questions stay unasked. What is a Waker? Who calls poll a second time, and how does it know when? How does a socket that would block turn into a task that sleeps?
async-runtime is my attempt to answer them by building the thing. It is a small async runtime for Rust written from scratch: a single-threaded executor, a multi-threaded work-stealing executor, wakers, an epoll reactor (through mio), async TCP, timers, spawn and join. It is about 1 100 lines including comments, with no unsafe. It is a learning project; the README says to use Tokio for real work.
What I built
The reactor (reactor.rs). One mio::Poll plus a BTreeMap<(Instant, id), Waker> of timers. Each registered socket gets a ScheduledIo: a read/write readiness flag and a waker slot. turn() waits for I/O events, the next timer or a mio::Waker notification, then fires the wakers.
Async TCP (net.rs). poll_io is the core loop: clear the readiness flag, try the system call, and on WouldBlock store the waker and re-check the flag, because an event may have landed in between. Otherwise return Pending. TcpListener::accept and TcpStream::{connect, read, write, write_all, read_exact} are built on it. Methods take &self, so a stream can be shared.
The single-threaded executor (local.rs), LocalRuntime. Tasks, which may be !Send, live in a thread-local slab. The run queue is a Mutex<VecDeque<usize>> of task ids. When the queue is empty, the executor thread sets a parked flag, re-checks the queue and blocks in reactor.turn(). Wakers from other threads write to the eventfd only when parked is set.
The work-stealing executor (multi.rs), Runtime. Tasks are Arc<Task> with a scheduled flag, so many wakes enqueue the task once. A wake on a worker thread pushes to that worker's own deque; a wake from anywhere else goes to a global injector. An idle worker pops from its local deque, then takes a batch from the injector, then steals from siblings, then registers as a sleeper, re-checks, and parks with a timeout. A dedicated thread runs the reactor. block_on parks the calling thread between polls.
Tasks, timers and combinators. task.rs has JoinHandle<T>, which resolves to Result<T, JoinError>; a panic inside a task is caught with catch_unwind, so workers survive. time.rs has sleep, sleep_until and timeout, and a dropped Sleep removes its timer. join.rs has join(a, b) and join_all(iter).
How to use it
Clone the repository and run the tests and examples:
git clone https://github.com/AbdeldjalilChougui/async-runtime
cd async-runtime
cargo test
cargo run --release --example echo -- 7000 # nc 127.0.0.1 7000
cargo run --release --example http -- 8080 # curl 127.0.0.1:8080
cargo run --release --example http -- --local 8080 # same, on the single-threaded runtime
cargo run --release --example bench # compare with Tokio
To try it in your own code, add it as a git dependency with cargo add --git https://github.com/AbdeldjalilChougui/async-runtime. An echo server with four workers looks like this:
use async_runtime::{net::TcpListener, spawn, time::sleep, Runtime};
let rt = Runtime::new(4)?;
rt.block_on(async {
let l = TcpListener::bind("127.0.0.1:7000")?;
loop {
let (s, _) = l.accept().await?;
spawn(async move {
let mut buf = [0; 1024];
while let Ok(n @ 1..) = s.read(&mut buf).await {
sleep(std::time::Duration::from_millis(1)).await;
if s.write_all(&buf[..n]).await.is_err() { break }
}
});
}
})
If you know Tokio, the shape is familiar on purpose.
What it teaches
A waker is a small thing. Here it is an Arc implementing std::task::Wake that pushes a task id or a task pointer onto a run queue. That is all "waking a task" means: put it back in line to be polled. It also explains why wakers must be Send even on a single-threaded runtime: the standard library's contract lets a waker be called from any thread, for example from the reactor or a timer.
Edge-triggered I/O has one rule you cannot skip. With edge-triggered readiness, the OS tells you once that a socket became readable. If you get WouldBlock, store your waker and go to sleep, an event that arrived between the system call and the store is lost, and the task sleeps forever. The fix is the re-check in poll_io. This is how WouldBlock turns into Poll::Pending without losing events.
The reactor is also the timer. There is no timer thread. The timeout passed to epoll_wait is the time until the next deadline. When it returns, either a socket is ready or a timer is due.
Lost wake-ups are the main enemy. The same pattern shows up three times: in poll_io, when the local executor parks, and when a worker goes to sleep. Announce that you are about to sleep, check again, then sleep. Skip the second check and you have a bug that appears once in a million runs.
Work stealing is a queue discipline. With crossbeam-deque, each worker has a local LIFO deque, there is a global injector, and idle workers steal from the others. The interesting part is parking idle workers without missing work.
The benchmark shows what Tokio's optimizations buy. cargo run --release --example bench, with 4 workers each on an 8-thread laptop and client threads on the same machine, so the README says to treat it as rough:
- Spawn and yield once, 200 000 tasks: 916 ms for async-runtime, 332 ms for Tokio 1.x.
- HTTP keep-alive, 1 connection: 8 633 req/s against 12 855 req/s.
- HTTP keep-alive, 32 connections: 30 540 req/s against 38 199 req/s.
Tokio wins, as expected, and the README explains why. The reactor here runs on its own thread, so every I/O wake-up is a cross-thread hand-off through the global injector, while Tokio drives the reactor from a worker and keeps the woken task local, with a LIFO slot. Every schedule takes the sleepers mutex. And task allocation is a Box plus an Arc plus a Mutex per task.
Things to know
The limits from the README:
- Linux and macOS through mio, tested on Linux only. TCP only: no UDP, no Unix sockets, no files.
- No
AsyncRead/AsyncWritetrait implementations, so it does not plug into the futures or hyper ecosystem. - No cooperative budgeting: a task that never yields hogs its worker.
-
block_ononRuntimepolls the main future on the caller thread, and nestedblock_onis not detected. - Tasks that never finish are leaked at shutdown instead of being cancelled cleanly.
- Timers are a
BTreeMap, not a hierarchical wheel. That is fine for thousands of timers, not millions.
What was tested. cargo test runs 17 tests in tests/runtime.rs: cross-thread wake-ups on both runtimes, 100 wakes before a poll running the task at most a couple of times, yield_now interleaving order, timers firing in deadline order, sleep accuracy, timeout, cancelled timers not keeping the runtime alive, join concurrency, panics becoming JoinError, work actually being stolen, 10 000 spawned tasks, 100 concurrent async echo clients on the multi-threaded runtime and 50 on the local one, blocking std clients, connection refused, and EOF after shutdown(Write).
Why I built it
I wanted to know what sits between async fn and the operating system. The pieces have names everyone has heard (executor, reactor, waker), and their definitions are easy to repeat without understanding how they connect. Building all three, small, is the way to see the connections: the waker is the link from the reactor back to the executor, and almost every hard bug is a missed wake-up somewhere on that link.
Keeping it to about a thousand lines with no unsafe was a deliberate constraint. It costs performance, as the benchmark shows, and it keeps the code readable from top to bottom.
Get the code
The source, the examples and the benchmark are on GitHub: https://github.com/AbdeldjalilChougui/async-runtime. It's MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.
Top comments (0)