Introduction

Volt is an async I/O runtime for Zig. It provides a work-stealing task scheduler, synchronization primitives, channels, networking, filesystem, timers, and process management — everything you need to build concurrent servers and services, in one package.

Volt brings the same architecture that powers Tokio in Rust to Zig, adapted for Zig’s value semantics and comptime specialization. Zero-allocation waiters, lock-free channels, and O(1) worker waking make it fast. An explicit Io handle (no hidden globals) makes it predictable. It is the I/O counterpart to Blitz (CPU parallelism), the same way Tokio complements Rayon.

Quick Example

const volt = @import("volt");

pub fn main() !void {
    try volt.run(serve);
}

fn serve(io: volt.Io) void {
    var listener = volt.net.listen("0.0.0.0:8080") catch return;
    defer listener.close();
    while (listener.tryAccept() catch null) |conn| {
        _ = io.@"async"(echo, .{conn.stream}) catch continue;
    }
}

fn echo(stream: volt.net.TcpStream) void {
    var s = stream;
    defer s.close();
    var buf: [4096]u8 = undefined;
    while (true) {
        const n = s.tryRead(&buf) catch return orelse continue;
        if (n == 0) return;
        s.writeAll(buf[0..n]) catch return;
    }
}

Key Features

Work-Stealing Scheduler

LIFO slot + local ring buffer + global injection queue. Cooperative budgeting (128 polls/tick), O(1) bitmap worker waking, and EWMA-based adaptive scheduling. Spawn thousands of tasks across all cores without manual thread management.

Zero-Allocation Primitives

Mutex, RwLock, Semaphore, Barrier, Notify, OnceCell — waiters are embedded directly in futures on the stack. No heap allocation per contended wait. Every primitive offers tryX() (non-blocking, no runtime needed) and x(io) (async, requires runtime).

Lock-Free Channels

MPSC/MPMC (Vyukov ring buffer), Oneshot, Broadcast, Watch, and Select. Bounded channels provide backpressure. 48 B/op total vs 217 B/op in Tokio across channel benchmarks.

Cross-Platform I/O

io_uring (Linux), kqueue (macOS), IOCP (Windows), epoll (fallback) — auto-detected at startup. TCP, UDP, Unix domain sockets, filesystem, process spawning, and signal handling.

Timers and Timeouts

Nanosecond-precision Duration and Instant types. Hierarchical timer wheel, async Sleep, recurring Interval, and Deadline/Timeout combinators. Wrap any operation with a timeout in one line.

Lightweight Tasks

Each task is a state machine at ~256-512 bytes, not a coroutine stack (16-64 KB). Predictable memory, cache-friendly layout, millions of concurrent tasks. Same tradeoff Tokio made — stackless wins where density matters.

Why Volt?

Compared to Other Zig Async Options

Feature	Volt	zio	Zig `std.Io` (in dev)
Work-stealing scheduler	Yes (Tokio-style)	Multi-threaded scheduler	No (OS threads)
Sync primitives	6 types, zero-alloc	Yes, incl. channels	Mutex, Condition
Channels	4 types + Select	Yes	Queue (MPMC bounded)
Platform backends	io_uring, kqueue, IOCP, epoll	io_uring, kqueue, IOCP, epoll	Threaded + proof-of-concept io_uring, kqueue
Cooperative budgeting	Yes (128 polls/tick)	No	No
Blocking pool	Yes (auto-scaling, 512 threads)	No	N/A (threaded model)
Graceful shutdown	Built-in signal handling	Cancellation support	First-class cancellation
Coroutine model	Stackless by choice (~256-512 B/task)	Stackful (growable stacks)	Explicit I/O interface

Two-Tier API — Use Without a Runtime

Every async primitive provides two access patterns, and they have different runtime requirements:

// Tier 1: No runtime needed -- works anywhere, even in main()
var mutex = volt.sync.Mutex.init();
if (mutex.tryLock()) {
    defer mutex.unlock();
    // critical section
}

// Tier 2: Requires the runtime (volt.run or Io.init)
mutex.lock(io);    // blocks this task until acquired
defer mutex.unlock();

The tryX() tier (tryLock, tryAcquire, trySend, tryRecv) and all filesystem/networking operations work without starting a runtime. Use them in CLI tools, scripts, or libraries that don’t need async. The convenience tier (mutex.lock(io), ch.send(io, val), sem.acquire(io, n)) requires the io: volt.Io handle — the type system enforces this at compile time, so you can’t accidentally call async APIs without a runtime. See Basic Concepts for the full breakdown.

Benchmark Highlights

All measurements on Apple M3 Pro, nanoseconds per operation, 4 worker threads.

Volt vs Tokio (Rust)

Benchmark	Volt	Tokio	Winner
Channel send	11.1 ns	16.3 ns	Volt +1.5x
Channel recv	11.4 ns	22.3 ns	Volt +2.0x
Channel roundtrip	23.1 ns	37.8 ns	Volt +1.6x
Channel MPMC (4P + 4C)	73.3 ns	132.8 ns	Volt +1.8x
Oneshot	27.1 ns	51.5 ns	Volt +1.9x
Broadcast (4 recv)	95.2 ns	143.8 ns	Volt +1.5x
Watch	45.7 ns	145.4 ns	Volt +3.2x

Benchmark	Volt	Tokio	Winner
Mutex (uncontended)	31.8 ns	28.2 ns	Tokio +1.1x
RwLock read	25.3 ns	27.1 ns	Volt +1.1x
RwLock write	20.7 ns	25.2 ns	Volt +1.2x
Semaphore	22.7 ns	33.7 ns	Volt +1.5x
Mutex contended (4 tasks)	91.7 ns	207.9 ns	Volt +2.3x
RwLock contended (4R + 2W)	149.5 ns	247.4 ns	Volt +1.7x
Semaphore contended (8T, 2 permits)	139.4 ns	323.0 ns	Volt +2.3x

Benchmark	Volt	Tokio	Winner
OnceCell get	2.0 ns	1.0 ns	Tokio +2.0x
OnceCell set	41.8 ns	90.8 ns	Volt +2.2x
Barrier	50.9 ns	1,312.8 ns	Volt +25.8x
Notify	15.6 ns	18.9 ns	Volt +1.2x

Benchmark	Volt	Tokio	Winner
Spawn + await	29,597 ns	18,946 ns	Tokio +1.6x
Spawn batch (per task)	601.0 ns	611.4 ns	Tie
Blocking spawn	25,037 ns	12,483 ns	Tokio +2.0x

Overall: Volt wins 16 of 21 benchmarks. Tokio wins 4 (mutex uncontended, OnceCell get, spawn+await, blocking spawn), 1 tie. Memory: 284 B/op total vs Tokio’s 1,868 B/op — 6.6x less. Allocations: 3.0/op vs 17.1/op. Volt’s architecture is derived from Tokio — we would not be here without their work. See Comparing with Tokio for methodology and full results.

Module Overview

Module	Description
`volt.Io`	Runtime handle: `@"async"`, `concurrent`, passed explicitly like `Allocator`
`volt.Future(T)`	Async result handle: `.@"await"(io)`, `.cancel(io)`
`volt.Group`	Structured concurrency: `.spawn()`, `.wait()`, `.cancel()`
`volt.sync`	Synchronization: Mutex, RwLock, Semaphore, Notify, Barrier, OnceCell
`volt.channel`	Message passing: Channel, Oneshot, Broadcast, Watch
`volt.net`	Networking: TCP, UDP, Unix sockets, DNS resolution
`volt.fs`	Filesystem operations
`volt.stream`	I/O streams: Reader, Writer, buffered I/O
`volt.time`	Duration, Instant, Sleep, Interval, Deadline
`volt.signal`	Signal handling (SIGINT, SIGTERM)
`volt.process`	Process spawning and piped I/O
`volt.shutdown`	Graceful shutdown coordination