Norn is a Rust workspace for composing single-threaded asynchronous runtimes.
It separates local task scheduling, executor control flow, timers, cross-thread
message delivery, and Linux io_uring I/O into independent crates.
The project is experimental, and its APIs are still evolving. Norn targets custom runtimes built around thread-affine tasks and task wakers: they must be polled, schedu 821E led, and woken on the runtime thread that owns them.
| Crate | Role |
|---|---|
norn-task |
Local task allocation, scheduling, cancellation, and join handles. |
norn-executor |
A local executor and the Park/Unpark interfaces used to compose runtime drivers. |
norn-timer |
A timer-wheel Park layer with system and simulated clocks. |
norn-uring |
A Linux-only io_uring driver with filesystem, TCP, UDP, registered-buffer, and device-command APIs. |
norn-channel |
Bounded cross-thread channels that keep receive-side waking on the destination runtime thread. |
norn-multicore |
Fixed process-local groups of thread-affine runtimes connected through norn-channel. |
norn-nursery |
Scoped local concurrency for child futures that may borrow from their environment. |
There is no top-level norn runtime crate. Applications select the layers they
need and place them under norn-executor::LocalExecutor. For example, the timer
driver wraps another Park implementation, while norn-uring::Driver can serve
as the Linux I/O layer.
use norn_executor::park::SpinPark;
use norn_executor::{spawn, LocalExecutor};
let mut executor = LocalExecutor::new(SpinPark);
let value = executor.block_on(async {
spawn(async { 21 * 2 }).await.unwrap()
});
assert_eq!(value, 42);SpinPark is useful for examples and cases where busy-spinning is intentional.
ThreadPark blocks the runtime thread on a condition variable. On Linux,
norn-uring::Driver implements the same Park interface and drives I/O
completion while the executor is parked.
norn-task, norn-executor, norn-timer, norn-channel, and norn-nursery
are platform-independent Rust crates. norn-uring and its I/O APIs are compiled
only on Linux. The workspace is structured so the non-io_uring crates can
still be built on macOS.
examples/norn-kvis a small block-oriented key/value store. It usesnorn-uringon Linux and a blocking backend elsewhere.examples/ping-pong-grpcruns a tonic gRPC client and server over Norn's executor, timer, TCP, and filesystem layers. This example requires Linux.norn-channelcrate documentation demonstrates a sharded cross-thread channel topology.norn-nurserycrate documentation demonstrates scoped borrowing, nested child tasks, and early termination.
examples/norn-kv-bench is the end-to-end
benchmark for runtime optimization. It drives norn-kv-server with a mixed
memcached-binary workload and reports validated, low-noise server cost per
request (instructions, CPU time, context switches) at saturation and at fixed
offered rates, per-class latency, and paired baseline/candidate comparisons.
The benches package contains focused task, executor, timer,
channel, HTTP, buffer, and io_uring benchmarks that diagnose why an
end-to-end number moved. Results and methodology are recorded alongside the
benchmarks.
The repository includes a Nix development shell with the Rust tooling used by the project:
nix develop
cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-depsLinux and a kernel with io_uring support are required to run the
norn-uring tests. The other crates can be tested independently with commands
such as cargo test -p norn-task or cargo test -p norn-timer.
The task representation and scheduling state machine draw on techniques used
by Tokio. The io_uring submission model
also draws on tokio-uring, and the
scoped-concurrency API is informed by the
moro experiment. These projects are
design influences. Norn makes no API-compatibility claim.