zig #

notes on zig patterns. organized by topic — version-specific migration notes live in versions/, everything else is idiom notes annotated with the release they were learned on.

issue tracking #

zig moved from github to codeberg. old issues (≤25xxx) are on github, new issues (30xxx+) are on codeberg.org/ziglang/zig.

curl -s "https://codeberg.org/api/v1/repos/ziglang/zig/issues?state=all&q=flate"

stdlib + language idioms #

• arraylist - ownership patterns (toOwnedSlice vs deinit)
• binary - encoding/decoding wire formats (CBOR, CAR, varints, arenas)
• comptime - type generation, tuple synthesis, string validation, anytype adapters, comptime-sql escape hatches
• concurrency - atomics vs mutex, callback pattern, ring buffers (threads; for std.Io-based concurrency see io/)
• crypto - ecdsa paths, signature verification
• database - zqlite, connection patterns, transactions
• hashmap - StringHashMap, O(1) block index, managed vs unmanaged
• interfaces - comptime duck typing, type-returning functions, vtables
• json - Stringify with writers, parse with arenas
• modules - file + directory pattern (foo.zig + foo/)
• structs - copy semantics, internal storage for strings
• testing - silent test discovery loss, multi-module test targets, comptime-folding, leaky apis
• text - []const u8 is bytes: character vs byte vocabularies, std.unicode, where classification stops

std.Io (0.16+) #

• io/ — the std.Io interface: everything that can block moves through it
  • README — overview, backends, design philosophy
  • concurrency — async vs concurrent, Future, Group, Select, Queue
  • synchronization — Mutex, Condition, CancelProtection, cancellation model
  • patterns — backend selection, InitOptions, debug_io, long-lived tasks, networking
• fibers — building stackful fibers: the ReleaseSafe clobber bugs (LLVM drops ~{x30}, x18 missing on linux) proven by IR-vs-disasm, mmap vs guard-page stacks, why blocking work must not go on fibers, testing on the arch you deploy to

project lessons #

• zig build with no -Doptimize is a Debug build, and -Dtarget does not change that. a deploy recipe that only cross-compiles ships debug crypto: every TLS handshake takes seconds and a loop of HTTPS calls looks hung. pass -Doptimize=ReleaseSafe (or ReleaseFast) in every deploy recipe and check zig build --help output for the mode when something is inexplicably slow. (find-bufo bot, 2026-08-29: 20–26s per request → ~10ms.)

• cli — building a terminal CLI: stdout/stderr split, broken-pipe handling, pager/browser via process.spawn

• logging — std.log, std.options.logFn, OTEL bridges, why direct-emit APIs are an anti-pattern

• libuv-process-lifetimes — initialized-on-error handles and close callbacks at a Zig/C boundary

• atomic-rate-meter — "current rate of X" with a lock-free hot path + shared sampler thread

• per-command-arena — protocol-client lifetime trick: arena reset per command

• page-allocator-granularity — small-alloc leak amplification through page_allocator

• ziglua-ffi — embedding Lua 5.1 via ziglua, the redis.call upvalue pattern

subsystems #

• build/ - build system patterns from large projects (basics, organization, dependencies, codegen, cross-compilation, distribution)
• websocket/ - the first-party websocket.zig fork, its API divergence from upstream
• versions/ - release-keyed migration notes (0.15 fmt/io overhauls, 0.16 migration)

sources #

patterns derived from building and studying:

libraries #

• websocket.zig - first-party fork of karlseguin/websocket.zig, tracked for 0.16 — see websocket/
• zqlite.zig - sqlite wrapper