ZIO Asynchronous I/O Framework

The select() function allows a task to suspend until one of several different types of events occurs. This is more efficient than spawning multiple tasks for different event types.

select() accepts a struct containing pointers to various event sources, including:

• JoinHandle: Fires when a task completes.
• Timeout: Fires when a duration elapses.
• Signal: Fires when a signal is received.
• Channel: Fires when data is available to receive.

select() returns a union indicating which specific event was triggered, allowing you to handle different event types in a single loop.

// select() suspends until one of the provided events occurs
const event = select(.{
    .timer = &my_timer,
    .signal = &shutdown_signal,
});

switch (event) {
    .timer => { /* handle timer */ },
    .signal => { /* handle signal */ },
    // ... other cases
}

A Channel is a typed queue used to pass messages between tasks without using shared memory or locks. Channels provide type safety and use suspending send() and receive() operations.

Channel Types

• Buffered Channels: Have a fixed capacity (e.g., 16 slots). send() only blocks when the buffer is full. Use these to decouple producers and consumers and handle bursts of work.
• Unbuffered Channels: Have no capacity. send() blocks until a receiver calls receive(), providing a direct handoff between tasks.

Error Handling

When a channel is closed, send() or receive() will return error.ChannelClosed, which can be used to signal tasks to exit gracefully.

ZIO allows you to write client handlers that look like simple, synchronous, blocking code, but they are actually non-blocking and asynchronous under the hood.

When performing I/O (like read or writeAll) or calling sleep, the current task is suspended and the runtime switches to other available tasks. This allows a single server to handle thousands of concurrent connections efficiently without needing a dedicated OS thread per client.

A Group is used to implement structured concurrency. It manages a collection of tasks and ensures that their lifetimes are bound to the group's scope.

Key behaviors:

• Automatic Cleanup: When a group is cancelled (e.g., via defer group.cancel()), all tasks spawned within that group are also cancelled. This prevents task leaks and ensures a clean shutdown of all child handlers (like client connections) when the main process exits.
• Spawning: Use group.spawn() to create a new task (fiber) that runs concurrently with the current execution flow.

The zio.ev event loop provides high-performance, platform-specific async I/O:

• Linux: Uses io_uring with an automatic epoll fallback.
• Windows: Uses iocp (I/O Completion Ports).
• macOS/BSD: Uses kqueue.
• Other systems: Falls back to poll.

I/O Capabilities:

• Network I/O: Asynchronous on all supported systems.
• File-system I/O: Asynchronous on Linux and Windows; simulated using an auxiliary thread pool on other systems.
• Concurrency: Supports structured concurrency via Group and zero-allocation intrusive data structures.

ZIO is an async I/O framework for Zig that provides a runtime for executing stackful coroutines (fibers/green threads) on one or more CPU threads. It uses event-driven OS APIs (like io_uring, iocp, or kqueue) under the hood to make asynchronous operations appear as blocking calls, simplifying state management.

Key components include:

• Runtime: Executes coroutines on CPU threads.
• Asynchronous I/O Layer: Provides non-blocking OS API integration.
• Synchronization Primitives: Cooperate with the runtime (e.g., channels).
• Structured Concurrency: Uses task groups for managing concurrent tasks.

ZIO integrates seamlessly with Zig's standard library by implementing the std.Io interface, allowing it to work with any Zig 0.16+ networking library.

While std.Io.Evented is intended to provide similar functionality, ZIO is a more complete and cross-platform solution.

Key differences:

• Completeness: std.Io.Evented is considered unfinished and may lack essential functionality.
• Architecture: ZIO uses a layered architecture with a cross-platform event loop and a fiber/coroutine runtime built on top. This makes it easier to support multiple operating systems (Linux, Windows, macOS, etc.) compared to the standard library's approach of reimplementing the interface for each backend.
• Access: ZIO allows you to reach into the event loop directly if you need functionality not covered by the std.Io interface.

Channels can be used to safely transfer ownership of heap-allocated memory between tasks. This avoids use-after-free or double-free errors without requiring complex locking.

Pattern:

1. Producer (Worker): Allocates memory (e.g., using gpa.dupe) for a result, then send()s the pointer/struct through the channel.
2. Consumer (Collector): receive()s the result from the channel, uses the data, and is then responsible for calling gpa.free() to release the memory.

// In worker (Producer)
const result = SearchResult{
    .file_path = path,
    .line_number = line_number,
    .line = try gpa.dupe(u8, line), // Allocate
};
// ... 
try results_channel.send(result);

// In collector (Consumer)
const result = results_channel.receive() catch ...;
// ... use result ...
gpa.free(result.line); // Free

Tasks

A task is a lightweight unit of execution (similar to a goroutine or fiber). Tasks are highly scalable; you can spawn thousands of them because they use automatically growing stacks and are managed by a pool of OS threads distributed by the ZIO runtime.

Structured Concurrency

ZIO follows the principle of structured concurrency via Group. This means child tasks cannot outlive their parent scope. If the parent scope exits or the group is cancelled, all child tasks are guaranteed to be cancelled, making concurrent code easier to reason about and preventing resource leaks.

ZIO implements the standard std.Io.Reader and std.Io.Writer interfaces. This allows you to use any existing Zig library that relies on these interfaces without needing special async-aware versions. The ZIO runtime handles the async I/O transparently under the hood.

Compatible libraries include:

• std.http for HTTP protocol handling
• std.crypto.tls for TLS/SSL connections
• std.json for JSON parsing
• Any third-party library that accepts std.Io.Reader or std.Io.Writer.

ZIO provides cross-platform support for various operating systems and hardware architectures:

Supported Operating Systems

• Linux: Uses io_uring with an automatic fallback to epoll.
• Windows: Uses iocp.
• macOS & BSDs: Uses kqueue.
• Other systems: Uses poll.

Supported Architectures (User-mode context switching)

• x86_64
• aarch64
• arm
• thumb
• riscv32 / riscv64
• loongarch64
• powerpc64