zio

# ZIO - Async I/O framework for Zig

[![CI](https://github.com/lalinsky/zio/actions/workflows/test.yml/badge.svg)](https://github.com/lalinsky/zio/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Zig](https://img.shields.io/badge/zig-0.17.0-orange.svg)](https://ziglang.org/download/)
[![Documentation](https://img.shields.io/badge/docs-online-green.svg)](https://lalinsky.github.io/zio/)

ZIO is an asynchronous runtime for Zig, in the same spirit as Go's runtime or Tokio: it schedules lightweight coroutines onto a pool of OS threads, and gives you blocking-looking network, file, and process I/O that's actually backed by non-blocking, event-driven OS APIs under the hood. On top of that, it's a full implementation of the standard library's [`std.Io`] interface, so Zig 0.17 code written against `std.Io` runs on zio unmodified.

> The main branch is for Zig 0.17. For Zig 0.16, use the v0.19.x releases or the [`zig-0.16`](https://github.com/lalinsky/zio/tree/zig-0.16) branch.

[`std.Io`]: https://ziglang.org/documentation/0.17.0/std/#std.Io

## Architecture

zio is built in layers, and each layer is usable on its own:

- **`zio.ev`**: a cross-platform, callback-based event loop (`io_uring`/`epoll`/`kqueue`/`iocp`/`poll`), in the same space as [libuv] or [libxev]. You can use this independently for async I/O without coroutines, or to embed zio's I/O into an existing callback-driven loop. For example, see [blazio], a CPython `asyncio` event loop built on `zio.ev`.
- **`zio.coro`**: stackful coroutine primitives (context switching, growable stacks, manual scheduling), with no I/O or scheduler attached. This is what you'd build a different kind of scheduler on top of, if `zio.Runtime`'s isn't the one you want.
- **`zio.Runtime`**: the full runtime. It schedules `zio.coro` coroutines across executor threads, drives their I/O through `zio.ev`, and adds structured concurrency (task groups), cancellation, synchronization primitives, and the `std.Io` implementation. Most programs use this directly and never touch the layers below it.

A runtime can run single-threaded, or multi-threaded in one of two modes. With work-stealing (the default), idle executors steal work from busy ones. This keeps every thread busy when runnable work is spread unevenly to begin with. With pinned scheduling, a task stays on whichever executor it was spawned on for its entire life, with no migration and no cross-executor synchronization on the scheduling path, at the cost of no rebalancing if load is uneven. The mode is chosen at compile time in your root module:

```zig
pub const zio_options: zio.Options = .{ .scheduling = .pinned };
```

[libuv]: https://github.com/libuv/libuv
[libxev]: https://github.com/mitchellh/libxev
[blazio]: https://github.com/lalinsky/blazio

## Features

- Support for Linux (`io_uring` with automatic `epoll` fallback), Windows and Wine (`iocp`), macOS/FreeBSD/NetBSD/OpenBSD (`kqueue`), and many other sys