# Learn Zig Series (#18) - Async Concepts and Event Loops ![zig.png](https://images.hive.blog/DQmaHuB6qTWHaSpJHQ1S8FCCRmNQuUxTcPZdU4yKHsJ7vEP/zig-banner.png) ### What will I learn - You will learn why Zig removed async/await and what replaced it; - the difference between blocking I/O, non-blocking I/O, and I/O multiplexing; - how `poll()` and `epoll` work at the OS level and how Zig exposes them; - building a simple event loop from scratch using `std.posix.poll`; - multiplexing multiple TCP connections without threads; - comparing Zig's approach to Python asyncio and Node.js event loops; - when to use threads vs event loops vs blocking I/O; - practical patterns for writing concurrent network services in Zig. ### Requirements - A working modern computer running macOS, Windows or Ubuntu; - An installed Zig 0.14+ distribution (download from ziglang.org); - The ambition to learn Zig programming. ### Difficulty - Intermediate ### Curriculum (of the `Learn Zig Series`): - [Zig Programming Tutorial - ep001 - Intro](https://hive.blog/programming/@scipio/zig-programming-tutoroial-ep001-intro) - [Learn Zig Series (#2) - Hello Zig, Variables and Types](https://hive.blog/hive-196387/@scipio/learn-zig-series-2-hello-zig-variables-and-types) - [Learn Zig Series (#3) - Functions and Control Flow](https://hive.blog/hive-196387/@scipio/learn-zig-series-3-functions-and-control-flow) - [Learn Zig Series (#4) - Error Handling (Zig's Best Feature)](https://hive.blog/hive-196387/@scipio/learn-zig-series-4-error-handling-zigs-best-feature) - [Learn Zig Series (#5) - Arrays, Slices, and Strings](https://hive.blog/hive-196387/@scipio/learn-zig-series-5-arrays-slices-and-strings) - [Learn Zig Series (#6) - Structs, Enums, and Tagged Unions](https://hive.blog/hive-196387/@scipio/learn-zig-series-6-structs-enums-and-tagged-unions) - [Learn Zig Series (#7) - Memory Management and Allocators](https://hive.blog/hive-196387/@scipio/learn-zig-series-7-memory-management-and-allocators) - [Learn Zig Series (#8) - Pointers and Memory Layout](https://hive.blog/hive-196387/@scipio/learn-zig-series-8-pointers-and-memory-layout) - [Learn Zig Series (#9) - Comptime (Zig's Superpower)](https://hive.blog/hive-196387/@scipio/learn-zig-series-9-comptime-zigs-superpower) - [Learn Zig Series (#10) - Project Structure, Modules, and File I/O](https://hive.blog/hive-196387/@scipio/learn-zig-series-10-project-structure-modules-and-file-io) - [Learn Zig Series (#11) - Mini Project: Building a Step Sequencer](https://hive.blog/hive-196387/@scipio/learn-zig-series-11-mini-project-building-a-step-sequencer) - [Learn Zig Series (#12) - Testing and Test-Driven Development](https://hive.blog/hive-196387/@scipio/learn-zig-series-12-testing-and-test-driven-development) - [Learn Zig Series (#13) - Interfaces via Type Erasure](https://hive.blog/hive-196387/@scipio/learn-zig-series-13-interfaces-via-type-erasure) - [Learn Zig Series (#14) - Generics with Comptime Parameters](https://hive.blog/hive-196387/@scipio/learn-zig-series-14-generics-with-comptime-parameters) - [Learn Zig Series (#15) - The Build System (build.zig)](https://hive.blog/hive-196387/@scipio/learn-zig-series-15-the-build-system-buildzig) - [Learn Zig Series (#16) - Sentinel-Terminated Types and C Strings](https://hive.blog/hive-196387/@scipio/learn-zig-series-16-sentinel-terminated-types-and-c-strings) - [Learn Zig Series (#17) - Packed Structs and Bit Manipulation](https://hive.blog/hive-196387/@scipio/learn-zig-series-17-packed-structs-and-bit-manipulation) - [Learn Zig Series (#18) - Async Concepts and Event Loops](https://hive.blog/hive-196387/@scipio/learn-zig-series-18-async-concepts-and-event-loops) (this post) # Learn Zig Series (#18) - Async Concepts and Event Loops Welcome back! In [episode #17](https://hive.blog/hive-196387/@scipio/learn-zig-series-17-packed-structs-and-bit-manipulation) we went deep into packed structs and bit manipulation -- defining fields down to individual bits, `@bitCast` for reinterpreting bit patterns, endianness handling with `std.mem.bigToNative`, and a real DNS header parser. I teased at the end that we'd start looking at concurrency and event-driven programming. Well, here we are, and the story is more interesting than you might expect. Because Zig had async/await. Past tense. It was in the language for years, with stackless coroutines, an event loop in the standard library, the whole deal. And then Andrew Kelley and the core team ripped it all out. Completely. Not deprecated, not hidden behind a flag -- removed. In Zig 0.11 the async/await keywords stopped compiling. The `std.event.Loop` module was deleted. If you search for old Zig tutorials from 2021-2022, you'll find async examples that don't compile anymore. Why? And what do you use instead? That's what this episode is about ;-) Here we go! ## Solutions to Episode 17 Exercises Before we get into event loops, here are the solutions to last episode's exercises on packed structs and bit manipulation. Complete code, copy-paste-and-run. **Exercise 1** -- `IpFlags` packed struct for IPv4 flags + fragment offset: ```zig const std = @import("std"); const testing = std.testing; const IpFlagsOffset = packed struct(u16) { // After byte-swap from big-endian to native (little-endian): // bits 0-12: fragment offset // bit 13: more fragments (MF) // bit 14: don't fragment (DF) // bit 15: reserved (always 0) fragment_offset: u13, more_fragments: bool, dont_fragment: bool, reserved: u1 = 0, }; fn parseIpFlagsOffset(raw_be: u16) IpFlagsOffset { const native = std.mem.bigToNative(u16, raw_be); return @bitCast(native); } test "DF=1 only" { // Big-endian: 0x4000 = 0100 0000 0000 0000 // bit 14 (DF) = 1, rest = 0 const result = parseIpFlagsOffset(0x4000); try testing.expect(result.dont_fragment); try testing.expect(!result.more_fragments); try testing.expectEqual(@as(u13, 0), result.fragment_offset); } test "fragment offset 185" { // Fragment offset 185 = 0x00B9 in low 13 bits // No flags set: 0x00B9 in big-endian const result = parseIpFlagsOffset(0x00B9); try testing.expect(!result.dont_fragment); try testing.expect(!result.more_fragments); try testing.expectEqual(@as(u13, 185), result.fragment_offset); } test "MF=1 with offset" { // MF bit is bit 13 in big-endian = 0x2000 // offset 100 = 0x0064 // combined: 0x2064 const result = parseIpFlagsOffset(0x2064); try testing.expect(!result.dont_fragment); try testing.expect(result.more_fragments); try testing.expectEqual(@as(u13, 100), result.fragment_offset); } ``` The key: IPv4 sends flags + fragment offset as a big-endian u16. After byte-swapping to native order, the fragment offset occupies the low 13 bits and the flags sit above it. The packed struct maps directly to this layout. **Exercise 2** -- `BitVector` backed by a `u64`: ```zig const std = @import("std"); const testing = std.testing; const BitVector = struct { bits: u64, pub fn init() BitVector { return .{ .bits = 0 }; } pub fn set(self: *BitVector, index: u6) void { self.bits |= @as(u64, 1) << index; } pub fn clear(self: *BitVector, index: u6) void { self.bits &= ~(@as(u64, 1) << index); } pub fn isSet(self: BitVector, index: u6) bool { return (self.bits & (@as(u64, 1) << index)) != 0; } pub fn count(self: BitVector) u7 { return @popCount(self.bits); } pub fn iterator(self: BitVector) Iterator { return .{ .remaining = self.bits }; } const Iterator = struct { remaining: u64, pub fn next(self: *Iterator) ?u6 { if (self.remaining == 0) return null; const index: u6 = @ctz(self.remaining); self.remaining &= self.remaining - 1; // clear lowest set bit return index; } }; }; test "set, check, clear, count" { var bv = BitVector.init(); bv.set(0); bv.set(5); bv.set(63); try testing.expect(bv.isSet(0)); try testing.expect(bv.isSet(5)); try testing.expect(bv.isSet(63)); try testing.expect(!bv.isSet(1)); try testing.expectEqual(@as(u7, 3), bv.count()); bv.clear(5); try testing.expect(!bv.isSet(5)); try testing.expectEqual(@as(u7, 2), bv.count()); } test "iterator yields ascending indices" { var bv = BitVector.init(); bv.set(63); bv.set(0); bv.set(5); var iter = bv.iterator(); try testing.expectEqual(@as(u6, 0), iter.next().?); try testing.expectEqual(@as(u6, 5), iter.next().?); try testing.expectEqual(@as(u6, 63), iter.next().?); try testing.expectEqual(@as(?u6, null), iter.next()); } ``` The iterator trick uses `@ctz` (count trailing zeros) to find the lowest set bit, then `remaining &= remaining - 1` to clear it. This classic bit manipulation pattern yields set bits in ascending order without needing a loop over all 64 positions. **Exercise 3** -- I2C address byte with packed struct and `@bitCast`: ```zig const std = @import("std"); const testing = std.testing; const I2cAddress = packed struct(u8) { rw: bool, // bit 0: read/write (0=write, 1=read) device: u7, // bits 1-7: device address }; fn buildAddress(device: u7, read: bool) u8 { return (@as(u8, device) << 1) | @intFromBool(read); } fn parseAddress(raw: u8) struct { device: u7, rw: bool } { return .{ .device = @truncate(raw >> 1), .rw = (raw & 1) == 1, }; } test "build and parse write address for EEPROM" { const raw = buildAddress(0x50, false); // 0x50 << 1 | 0 = 0xA0 try testing.expectEqual(@as(u8, 0xA0), raw); const parsed = parseAddress(raw); try testing.expectEqual(@as(u7, 0x50), parsed.device); try testing.expect(!parsed.rw); } test "build and parse read address for EEPROM" { const raw = buildAddress(0x50, true); // 0x50 << 1 | 1 = 0xA1 try testing.expectEqual(@as(u8, 0xA1), raw); const parsed = parseAddress(raw); try testing.expectEqual(@as(u7, 0x50), parsed.device); try testing.expect(parsed.rw); } test "bitCast matches manual construction" { const manual = buildAddress(0x50, true); const via_struct = I2cAddress{ .device = 0x50, .rw = true }; const from_struct: u8 = @bitCast(via_struct); try testing.expectEqual(manual, from_struct); // And back const back: I2cAddress = @bitCast(manual); try testing.expectEqual(@as(u7, 0x50), back.device); try testing.expect(back.rw); } ``` The neat part: `@bitCast` on the packed struct produces the exact same byte as the manual shift-and-OR construction. That's the whole point of packed structs -- they're just a declarative way to describe bit layouts that the compiler turns into the same machine code you'd write by hand. Right, on to event loops ;-) ## Why Zig killed async/await This is actually a fascinating story in language design, and I think it's worth understanding because it says something deep about Zig's philosophy. Zig's async/await (from roughly 0.5 through 0.10) worked through **stackless coroutines**. When you called an `async` function, the compiler would transform it into a state machine, allocate a frame on the heap, and suspend/resume at `await` points. There was a `std.event.Loop` that used `epoll` (Linux) or `kqueue` (macOS) under the hood to manage I/O readiness. It worked. People built real things with it. But the implementation had problems. Deep problems. The async transformation complicated the compiler massively -- it interacted badly with comptime, with error handling, with the debug info generator. Every new language feature had to be "async-aware" or it would break in subtle ways. Andrew Kelley estimated that async accounted for roughly a third of the compiler's complexity while serving maybe 5% of use cases. The core team decided: a systems programming language shouldn't force a specific concurrency model on you. Instead, Zig should give you the **building blocks** -- threads via `std.Thread`, raw OS primitives via `std.posix`, and the type system to make them safe -- and let you build (or import) whatever concurrency model fits your problem. This is the same philosophy that drives Zig's approach to memory management (no built-in GC, bring your own allocator) and error handling (explicit errors, no exceptions). The language gives you control. It doesn't make choices for you. So what do you actually use instead? Three things: 1. **`std.Thread`** for CPU-bound parallelism (we'll cover threading in a later episode) 2. **OS I/O multiplexing** (`poll`, `epoll`, `kqueue`) for network/file I/O 3. **Third-party event loop libraries** like `zig-aio` or `libxev` for production systems This episode focuses on #2 -- understanding I/O multiplexing from first principles and building with it in Zig. ## Blocking vs non-blocking I/O To understand event loops, you first need to understand what "blocking" means at the OS level. When you call `read()` on a socket, two things can happen: **Blocking** (the default): the thread stops and waits until data arrives. Could be microseconds, could be minutes. During that wait, the thread does absolutely nothing. In a single-threaded program, the entire application freezes: ```zig const std = @import("std"); const net = std.net; pub fn main() !void { // Open a listening socket const address = net.Address.initIp4(.{ 127, 0, 0, 1 }, 8080); var server = try std.posix.socket( std.posix.AF.INET, std.posix.SOCK.STREAM, 0, ); defer std.posix.close(server); try std.posix.bind(server, &address.any, address.getOsSockLen()); try std.posix.listen(server, 128); std.debug.print("Listening on :8080\n", .{}); // This BLOCKS until a client connects const client_fd = try std.posix.accept(server, null, null, 0); defer std.posix.close(client_fd); var buf: [1024]u8 = undefined; // This BLOCKS until the client sends data const n = try std.posix.read(client_fd, &buf); std.debug.print("Received: {s}\n", .{buf[0..n]}); } ``` That code handles exactly ONE client. While it's blocked on `accept()`, it can't do anything else. While it's blocked on `read()`, same thing. If two clients connect at the same time, the second one waits until the first is completely done. **Non-blocking**: you set the `NONBLOCK` flag on the file descriptor. Now `read()` returns immediately -- either with data (if some was available) or with `error.WouldBlock` (if nothing was ready). Your code stays in control: ```zig const std = @import("std"); const posix = std.posix; pub fn main() !void { const address = std.net.Address.initIp4(.{ 127, 0, 0, 1 }, 8080); var server = try posix.socket( posix.AF.INET, posix.SOCK.STREAM | posix.SOCK.NONBLOCK, // <-- non-blocking 0, ); defer posix.close(server); try posix.bind(server, &address.any, address.getOsSockLen()); try posix.listen(server, 128); std.debug.print("Listening on :8080 (non-blocking)\n", .{}); while (true) { const result = posix.accept(server, null, null, posix.SOCK.NONBLOCK); if (result) |client_fd| { std.debug.print("Got connection: fd={d}\n", .{client_fd}); posix.close(client_fd); } else |err| { if (err == error.WouldBlock) { // No connection waiting right now -- do other stuff std.time.sleep(10 * std.time.ns_per_ms); continue; } return err; } } } ``` Non-blocking is better -- you're not frozen. But now you're polling in a tight loop, burning CPU. You keep asking "any data yet? any data yet? any data yet?" a thousand times a second. That's wasteful. What you really want is for the OS to tell you when something is ready, so you can sleep efficiently in between. That's what `poll()` does. ## poll() -- the universal I/O multiplexer `poll()` is a POSIX system call that takes a list of file descriptors and says "wake me up when ANY of these are ready for reading, writing, or have an error." It's supported on Linux, macOS, BSDs, and basically everything except Windows (which has its own thing with IOCP). Here's how it works in Zig: ```zig const std = @import("std"); const posix = std.posix; pub fn main() !void { const address = std.net.Address.initIp4(.{ 127, 0, 0, 1 }, 8080); var server = try posix.socket( posix.AF.INET, posix.SOCK.STREAM | posix.SOCK.NONBLOCK, 0, ); defer posix.close(server); // Allow address reuse so we can restart quickly try posix.setsockopt(server, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1))); try posix.bind(server, &address.any, address.getOsSockLen()); try posix.listen(server, 128); std.debug.print("Listening on :8080 with poll()\n", .{}); // Our poll set: just the server socket for now var fds: [64]posix.pollfd = undefined; var nfds: usize = 1; fds[0] = .{ .fd = server, .events = posix.POLL.IN, // interested in: "ready to accept" .revents = 0, }; while (true) { // Block until at least one fd is ready (timeout = -1 means wait forever) const ready = try posix.poll(fds[0..nfds], -1); if (ready == 0) continue; // timeout (shouldn't happen with -1) // Check each fd var i: usize = 0; while (i < nfds) { if (fds[i].revents == 0) { i += 1; continue; } if (fds[i].fd == server) { // Server socket: new connection waiting if (fds[i].revents & posix.POLL.IN != 0) { const client = posix.accept( server, null, null, posix.SOCK.NONBLOCK, ) catch |err| { if (err == error.WouldBlock) { i += 1; continue; } return err; }; std.debug.print("New connection: fd={d}\n", .{client}); // Add to poll set if (nfds < fds.len) { fds[nfds] = .{ .fd = client, .events = posix.POLL.IN, .revents = 0, }; nfds += 1; } else { std.debug.print("Too many connections, rejecting\n", .{}); posix.close(client); } } } else { // Client socket: data available if (fds[i].revents & posix.POLL.IN != 0) { var buf: [1024]u8 = undefined; const n = posix.read(fds[i].fd, &buf) catch 0; if (n == 0) { // Connection closed std.debug.print("Connection closed: fd={d}\n", .{fds[i].fd}); posix.close(fds[i].fd); // Remove from poll set by swapping with last fds[i] = fds[nfds - 1]; nfds -= 1; continue; // don't increment i } std.debug.print("fd={d}: {s}", .{ fds[i].fd, buf[0..n] }); // Echo it back _ = posix.write(fds[i].fd, buf[0..n]) catch {}; } if (fds[i].revents & posix.POLL.HUP != 0) { std.debug.print("Hang up: fd={d}\n", .{fds[i].fd}); posix.close(fds[i].fd); fds[i] = fds[nfds - 1]; nfds -= 1; continue; } } i += 1; } } } ``` This is a fully functional multi-client echo server in about 80 lines. No threads. No async/await. No framework. Just one thread, one `poll()` call, and a loop. The key insight: `poll()` is the event loop. The `while (true)` with `poll()` at the top IS the pattern that Node.js, Python's asyncio, and every other event-driven framework is built on top of. They just hide it behind nicer APIs. Here you're seeing the raw mechanism. The `pollfd` struct has three fields: - `fd`: the file descriptor to monitor - `events`: what you're interested in (`POLL.IN` for read-ready, `POLL.OUT` for write-ready) - `revents`: what actually happened (filled in by the kernel after `poll()` returns) When you call `poll()`, the thread sleeps efficiently (the kernel puts it to sleep, no CPU burned) until at least one file descriptor has an event. Then you iterate through the array checking `revents` to see which ones are ready. ## Building a structured event loop That raw poll loop works, but it's messy. Let's wrap it in a proper struct that manages connections and provides a cleaner interface. This is the foundation of what eventually becomes something like `libxev` or `libuv`: ```zig const std = @import("std"); const posix = std.posix; const net = std.net; const EventLoop = struct { const max_fds = 256; server_fd: posix.socket_t, fds: [max_fds]posix.pollfd, nfds: usize, running: bool, pub fn init(port: u16) !EventLoop { const address = net.Address.initIp4(.{ 127, 0, 0, 1 }, port); const fd = try posix.socket( posix.AF.INET, posix.SOCK.STREAM | posix.SOCK.NONBLOCK, 0, ); errdefer posix.close(fd); try posix.setsockopt( fd, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1)), ); try posix.bind(fd, &address.any, address.getOsSockLen()); try posix.listen(fd, 128); var self = EventLoop{ .server_fd = fd, .fds = undefined, .nfds = 1, .running = true, }; self.fds[0] = .{ .fd = fd, .events = posix.POLL.IN, .revents = 0, }; return self; } pub fn deinit(self: *EventLoop) void { var i: usize = 0; while (i < self.nfds) : (i += 1) { posix.close(self.fds[i].fd); } } pub fn run(self: *EventLoop) !void { std.debug.print("Event loop running (max {d} connections)\n", .{max_fds - 1}); while (self.running) { const ready = try posix.poll(self.fds[0..self.nfds], 1000); if (ready == 0) continue; // timeout, check self.running var i: usize = 0; while (i < self.nfds) { if (self.fds[i].revents == 0) { i += 1; continue; } if (self.fds[i].fd == self.server_fd) { try self.handleAccept(); } else { if (!self.handleClient(i)) continue; // fd was removed, don't increment } i += 1; } } } fn handleAccept(self: *EventLoop) !void { const client = posix.accept( self.server_fd, null, null, posix.SOCK.NONBLOCK, ) catch |err| { if (err == error.WouldBlock) return; return err; }; if (self.nfds >= max_fds) { std.debug.print("Max connections reached, dropping\n", .{}); posix.close(client); return; } self.fds[self.nfds] = .{ .fd = client, .events = posix.POLL.IN, .revents = 0, }; self.nfds += 1; std.debug.print("[+] Connection (total: {d})\n", .{self.nfds - 1}); } fn handleClient(self: *EventLoop, index: usize) bool { var buf: [4096]u8 = undefined; if (self.fds[index].revents & (posix.POLL.HUP | posix.POLL.ERR) != 0) { self.removeClient(index); return false; } if (self.fds[index].revents & posix.POLL.IN != 0) { const n = posix.read(self.fds[index].fd, &buf) catch { self.removeClient(index); return false; }; if (n == 0) { self.removeClient(index); return false; } // Echo back _ = posix.write(self.fds[index].fd, buf[0..n]) catch {}; } return true; } fn removeClient(self: *EventLoop, index: usize) void { std.debug.print("[-] Disconnect (remaining: {d})\n", .{self.nfds - 2}); posix.close(self.fds[index].fd); self.fds[index] = self.fds[self.nfds - 1]; self.nfds -= 1; } }; pub fn main() !void { var loop = try EventLoop.init(8080); defer loop.deinit(); try loop.run(); } ``` This is structuraly identical to what's happening inside Node.js. Node's `libuv` library is a C event loop that uses `epoll` on Linux, `kqueue` on macOS, and IOCP on Windows. When you write `server.on('connection', callback)` in JavaScript, that callback gets stored in a list and invoked when `poll()`/`epoll_wait()` tells `libuv` the socket is ready. The JavaScript callback abstraction is nicer, sure. But underneath it's this exact same pattern. The difference is that in Zig you OWN the loop. You can customize the allocation strategy (remember [ep007](https://hive.blog/hive-196387/@scipio/learn-zig-series-7-memory-management-and-allocators)? bring your own allocator). You can add custom file descriptors for timers, signals, or IPC. You can profile exactly which syscalls are happening. There's no magical runtime making decisions for you. ## epoll -- when poll() isn't enough `poll()` has a scaling problem. Every time you call it, you pass the entire array of file descriptors to the kernel. The kernel scans through all of them to find which ones are ready. With 10 connections, that's fine. With 10,000, it's slow -- O(n) per call, and you're making that call thousands of times per second. Linux solved this with `epoll`. Instead of passing the whole list every time, you register file descriptors once with an epoll instance, and the kernel maintains an internal data structure that tracks readiness efficently. When you call `epoll_wait()`, it returns only the file descriptors that are actually ready -- O(1) in practice. ```zig const std = @import("std"); const posix = std.posix; const linux = std.os.linux; pub fn main() !void { const address = std.net.Address.initIp4(.{ 127, 0, 0, 1 }, 8080); const server = try posix.socket( posix.AF.INET, posix.SOCK.STREAM | posix.SOCK.NONBLOCK, 0, ); defer posix.close(server); try posix.setsockopt( server, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1)), ); try posix.bind(server, &address.any, address.getOsSockLen()); try posix.listen(server, 128); // Create epoll instance const epfd = try posix.epoll_create1(0); defer posix.close(epfd); // Register server socket with epoll var server_event = linux.epoll_event{ .events = linux.EPOLL.IN, .data = .{ .fd = server }, }; try posix.epoll_ctl(epfd, linux.EPOLL.CTL_ADD, server, &server_event); std.debug.print("Listening on :8080 with epoll\n", .{}); var events: [64]linux.epoll_event = undefined; while (true) { // Wait for events -- returns only READY fds const n_ready = posix.epoll_wait(epfd, &events, -1); for (events[0..n_ready]) |ev| { if (ev.data.fd == server) { // Accept new connection const client = posix.accept( server, null, null, posix.SOCK.NONBLOCK, ) catch |err| { if (err == error.WouldBlock) continue; return err; }; // Register with epoll var client_event = linux.epoll_event{ .events = linux.EPOLL.IN, .data = .{ .fd = client }, }; try posix.epoll_ctl( epfd, linux.EPOLL.CTL_ADD, client, &client_event, ); std.debug.print("[+] New connection fd={d}\n", .{client}); } else { // Client data var buf: [4096]u8 = undefined; const n = posix.read(ev.data.fd, &buf) catch 0; if (n == 0) { std.debug.print("[-] Closed fd={d}\n", .{ev.data.fd}); posix.close(ev.data.fd); // epoll auto-removes closed fds continue; } _ = posix.write(ev.data.fd, buf[0..n]) catch {}; } } } } ``` Notice the API difference: with `poll()` you manage the array yourself and scan all entries after every call. With `epoll` you register once with `epoll_ctl(CTL_ADD, ...)` and the kernel gives you back only the ready descriptors. For high-connection-count servers (web servers, game servers, chat systems), this scales dramatically better. The tradeoff: `epoll` is Linux-only. macOS has `kqueue` (similar concept, different API). Windows has IOCP (completely different model -- completion-based rather than readiness-based). For cross-platform code, you either use `poll()` (works everywhere but scales worse) or you write a platform abstraction layer. This is exactly what libraries like `libxev` do -- they pick the best multiplexer for each platform. ## How this compares to Python and Node.js If you come from Python or JavaScript (and if you've been following my [Python series](https://hive.blog/utopian-io/@scipio/learn-python-series-intro) you probably know Python), here's how the models compare: **Python asyncio**: uses `epoll`/`kqueue` under the hood, but wraps everything in coroutines with `async`/`await`. When you `await socket.recv()`, Python's event loop suspends your coroutine, registers the socket for readiness, and resumes you when data arrives. The implementation is in C (in `_selector` and `_asyncio` modules). You never see the raw `epoll` calls. **Node.js**: uses `libuv` (a C library) which wraps `epoll`/`kqueue`/IOCP. Everything is callback-based: `socket.on('data', callback)`. The event loop is hidden entirely. You register callbacks and Node calls them when I/O is ready. `async`/`await` in JavaScript is just syntactic sugar over Promises, which are sugar over callbacks. **Zig (now)**: gives you the raw OS primitives. `std.posix.poll()`, `std.posix.epoll_ctl()`, `std.posix.socket()`. No hidden runtime, no coroutine transformation, no callback registration system. You build the loop yourself, or you use a library like `libxev` that builds it for you. The philosophical difference is real. Python and Node say: "concurrency is hard, let us handle the low-level stuff." Zig says: "concurrency is hard, and the low-level stuff is where the bugs hide, so you should understand and control it." Neither approach is wrong -- they serve different needs. If you're building a web app, asyncio or Node are excellent. If you're building the web server that asyncio runs on, or a database engine, or a game server that needs microsecond-level control over I/O scheduling -- you want what Zig gives you. Having said that, you don't HAVE to use raw `poll()` in Zig. The ecosystem has proper event loop libraries: - **`libxev`** by Loris Cro (Zig core team member): production-grade, cross-platform event loop with `epoll`/`kqueue`/IOCP backends - **`zig-aio`**: io_uring-based async I/O (Linux-only, extremely high performance) These give you nice APIs while still being transparent about what's happening underneath. No magic. ## When to use what This is the practical question. Three tools, three use cases: **Blocking I/O** (the default): - Simple command-line tools that do one thing at a time - Scripts that read a file, process it, write output - Client programs that connect to one server - Anything where "wait for this one thing" is all you need ```zig // Simple: just read the whole file const content = try std.fs.cwd().readFileAlloc(allocator, "data.txt", 1024 * 1024); ``` **Threads** (`std.Thread`): - CPU-bound work: parsing, compression, encryption, number crunching - When you need true parallelism (multiple CPU cores doing diferent work) - Background tasks that don't need to coordinate with I/O - Worker pools for request processing ```zig // Spawn a thread for heavy computation const handle = try std.Thread.spawn(.{}, computeHash, .{data}); // ... do other stuff ... handle.join(); ``` **Event loops / I/O multiplexing** (`poll`, `epoll`, `kqueue`): - Servers handling many simultaneous connections - Programs waiting on multiple I/O sources (network + stdin + timers) - When you need thousands of concurrent connections on one thread - Real-time systems where thread creation overhead matters ```zig // One thread handling many sockets const ready = try posix.poll(fds[0..nfds], timeout); ``` The common mistake is reaching for threads when you need concurrency but not parallelism. If your program is waiting on 100 network connections, you don't need 100 threads -- you need one thread with `poll()`. Threads add overhead: each one consumes stack memory (typically 2-8 MB), context switching isn't free, and shared state needs synchronization. For I/O-bound workloads, a single-threaded event loop often outperforms a thread-per-connection model. The other common mistake is building a custom event loop when a library would do. If you're writing a production network service in Zig, use `libxev` or a similar library. Building your own event loop is educational (that's why we did it in this episode!) but production event loops need to handle edge cases: partial writes, EINTR, TCP keepalives, connection timeouts, backpressure, graceful shutdown. A mature library handles all of that. ## A practical pattern: handling timeouts One thing event loops are great at is timeouts. With blocking I/O, implementing a timeout requires either threads or signals (both messy). With `poll()`, it's built right in -- the last parameter is a timeout in milliseconds: ```zig const std = @import("std"); const posix = std.posix; fn waitForDataWithTimeout(fd: posix.socket_t, timeout_ms: i32) !enum { data, timeout, closed } { var fds = [1]posix.pollfd{.{ .fd = fd, .events = posix.POLL.IN, .revents = 0, }}; const ready = try posix.poll(&fds, timeout_ms); if (ready == 0) return .timeout; if (fds[0].revents & posix.POLL.HUP != 0) return .closed; if (fds[0].revents & posix.POLL.IN != 0) return .data; return .closed; } pub fn main() !void { const address = std.net.Address.initIp4(.{ 127, 0, 0, 1 }, 8080); var server = try posix.socket( posix.AF.INET, posix.SOCK.STREAM | posix.SOCK.NONBLOCK, 0, ); defer posix.close(server); try posix.setsockopt( server, posix.SOL.SOCKET, posix.SO.REUSEADDR, &std.mem.toBytes(@as(c_int, 1)), ); try posix.bind(server, &address.any, address.getOsSockLen()); try posix.listen(server, 128); std.debug.print("Waiting for connection (5s timeout)...\n", .{}); switch (try waitForDataWithTimeout(server, 5000)) { .data => { const client = try posix.accept(server, null, null, 0); defer posix.close(client); std.debug.print("Got connection!\n", .{}); std.debug.print("Waiting for data (3s timeout)...\n", .{}); switch (try waitForDataWithTimeout(client, 3000)) { .data => { var buf: [1024]u8 = undefined; const n = try posix.read(client, &buf); std.debug.print("Received: {s}\n", .{buf[0..n]}); }, .timeout => std.debug.print("Client timed out, no data\n", .{}), .closed => std.debug.print("Client disconnected\n", .{}), } }, .timeout => std.debug.print("No connections in 5 seconds, exiting\n", .{}), .closed => {}, } } ``` The `waitForDataWithTimeout` function is clean and composable. You can use it anywhere you need to wait for I/O with a deadline. The return type is an enum that tells you exactly what happened -- data arrived, the timeout expired, or the connection was closed. Pattern matching with `switch` handles all cases. No exceptions, no error codes to look up, no surprises. This pattern extends naturally to more complex scenarios: connection establishment timeouts, keepalive ping/pong, request processing deadlines. The event loop gives you precise control over timing that you simply don't have with blocking I/O. ## Exercises 1. Modify the `EventLoop` struct from the "structured event loop" section to track how many bytes each client has sent (add a `bytes_received` field per connection). When a client disconnects, print the total bytes received from that client. You'll need to store per-connection state -- consider using a separate array indexed the same way as the `fds` array, or using a struct that contains both the `pollfd` and the metadata. Test by connecting with `nc localhost 8080` (or `telnet`), sending a few messages, then disconnecting. 2. Write a "multi-source monitor" program that uses `poll()` to simultaneously watch stdin (fd 0) and a TCP server socket. When data arrives on stdin, print it prefixed with `[stdin]`. When a TCP client connects, accept it and print `[net] new connection`. When a connected client sends data, print `[net] data: ...`. When either stdin reaches EOF or the user types "quit", shut down the event loop cleanly (close all sockets, print a summary of connections handled). This combines file descriptor types in a single poll set. 3. Extend the epoll echo server with a per-connection inactivity timeout. If a client hasn't sent any data in 10 seconds, disconnect them. You'll need to track the last-activity timestamp per connection (use `std.time.milliTimestamp()`) and on each `epoll_wait` call, sweep through connections to find stale ones. Use a timeout on `epoll_wait` itself (e.g. 1000ms) so you get control back periodically even when no I/O events happen. This is how production servers implement connection timeouts. ## Before you close this tab... - Zig had async/await but **removed it** (0.11+). The feature added massive compiler complexity for limited use cases. Instead, Zig provides raw OS primitives and lets you build or import the concurrency model you need. - **Blocking I/O** stops your thread until data arrives. Simple but can't handle multiple connections without multiple threads. **Non-blocking I/O** returns immediately with `error.WouldBlock` if nothing is ready. Better, but busy-polling wastes CPU. - **`poll()`** solves busy-polling: you give the kernel a list of file descriptors, it sleeps your thread efficiently, and wakes you when any of them are ready. This is the foundation of all event loop implementations. - **`epoll`** (Linux) improves on `poll()` for high connection counts. Instead of passing the whole fd list every call, you register fds once and get back only the ready ones. O(1) vs O(n). macOS uses `kqueue` (similar idea, different API). - Building an event loop in Zig is remarkably transparent: `std.posix.poll()`, `std.posix.epoll_ctl()`, and `std.posix.socket()` are thin wrappers over the syscalls. No hidden runtime, no magic. You see every syscall happening. - **Use blocking I/O** for simple tools and single-connection clients. **Use threads** for CPU-bound parallelism. **Use event loops** for I/O-bound concurrency (many connections, multiple I/O sources, timeouts). - For production Zig network services, use a library like `libxev` (by Loris Cro, cross-platform) or `zig-aio` (io_uring-based) rather than rolling your own event loop. They handle the platform differences and edge cases you don't want to debug at 3 AM. Next episode we'll look at SIMD -- using Zig's `@Vector` type to process multiple data elements in a single instruction. If you thought packed structs gave you control over memory layout, wait until you're running the same operation on 16 bytes simulateously ;-) ### Thanks for reading! @scipio