Zig 标准库、I/O 接口与并发：把知识串起来

June 26, 2026 编程学习 Zig, 标准库, Std.Io, 并发, Unmanaged, 学习笔记 Zig 语言学习系列 4539 字 10 分钟阅读

本文基于 Zig 0.16。

经过前五篇的旅程——语法、错误处理、内存管理、编译期计算、构建系统——现在到了收官篇，该把知识串起来了。

0.16 是两个重要版本的交汇点：标准库容器完成了 Unmanaged 迁移，同时引入了革命性的 std.Io 接口。这两个变化深刻影响了 Zig 代码的写法。本篇将围绕它们展开，最后用三语言实战对比收束，并给出学习路线和资源。

标准库常用容器：Unmanaged 迁移

Zig 0.16 的标准库容器经历了一次关键的架构变更——Unmanaged 迁移。其核心思想是：不再把 allocator 藏在结构体里，而是每次需要分配时显式传入。这与 Zig “显式优先”（explicit over implicit）的哲学完全一致。

不过，0.16 的迁移进度并非一刀切。ArrayList 和 HashMap 的迁移状态存在重要的不对称性，写代码时必须留意。

ArrayList：已完成迁移

从 0.16 起，std.ArrayList(T) 默认就是非托管版本。结构体只含 items 和 capacity 两个字段，不再存储 allocator。因此 append、appendSlice、deinit 等需要分配或释放内存的方法都接收 allocator 参数：

zig
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const std = @import("std");

pub fn main() !void {
    const gpa = std.heap.page_allocator;

    // 0.16 起 std.ArrayList(T) 是非托管版本：结构体不存储 allocator
    var list: std.ArrayList(i32) = .empty;          // 零容量初始化
    defer list.deinit(gpa);                          // deinit 接收 allocator

    // 预分配容量（可选）：var list = try std.ArrayList(i32).initCapacity(gpa, 10);

    try list.append(gpa, 1);                         // append 接收 allocator
    try list.append(gpa, 2);
    try list.appendSlice(gpa, &[_]i32{ 3, 4, 5 });   // appendSlice 接收 allocator

    std.debug.print("长度: {d}\n", .{list.items.len}); // items 是公开字段
    for (list.items) |item| {
        std.debug.print("{d}\n", .{item});
    }

    if (list.pop()) |last| {                         // pop 不需要 allocator
        std.debug.print("弹出: {d}\n", .{last});
    }
}

关键的 API 签名变化一目了然：

用 .empty 初始化（零容量），而非 std.ArrayList(T).init(allocator)
append/appendSlice/deinit 都接收 allocator 参数
pop/get/items 这类不涉及分配的操作不需要 allocator

HashMap：尚未迁移，默认仍是托管

与 ArrayList 不同，std.StringHashMap(V) 尚未迁移，默认仍是托管版本（结构体内部存储 allocator）。因此 init(allocator)、put、deinit 等方法不需要接收 allocator：

zig
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const std = @import("std");

pub fn main() !void {
    const gpa = std.heap.page_allocator;

    // std.StringHashMap(V) 仍是托管版本：init 时存储 allocator
    var map = std.StringHashMap(i32).init(gpa);
    defer map.deinit();                              // deinit 不需要 allocator

    try map.put("apple", 1);                         // put 不需要 allocator
    try map.put("banana", 2);

    if (map.get("apple")) |v| {                      // get 返回 ?V
        std.debug.print("apple: {d}\n", .{v});
    }

    var it = map.iterator();
    while (it.next()) |entry| {
        std.debug.print("{s}: {d}\n", .{ entry.key_ptr.*, entry.value_ptr.* });
    }

    _ = map.remove("banana");                        // remove 返回 bool
    std.debug.print("剩余: {d}\n", .{map.count()});
}

可选：StringHashMapUnmanaged（显式 opt-in）

若你仍想用非托管版本，可以显式选择 StringHashMapUnmanaged：

zig
1
2
3
4
// 若想要非托管的 map，显式用 StringHashMapUnmanaged
var map: std.StringHashMapUnmanaged(i32) = .empty;
defer map.deinit(gpa);                  // 此时 deinit 需要 allocator
try map.put(gpa, "apple", 1);           // 此时 put 也需要 allocator

给 Go / Rust 开发者的对照

与 Go 不同，Zig 没有内置的 append() 函数——动态数组操作用 std.ArrayList 的 append 方法。
与 Rust 不同，Zig 没有 HashMap::new()——无论托管还是非托管版本，Zig 都需要显式传入 allocator（要么在 init 时传入，要么每次方法调用传入）。分配行为始终完全可见。

这一不对称性是 0.16 当下的真实状态：ArrayList 已完全完成迁移，而 HashMap 仍在过渡中。如果你照着旧资料写 std.ArrayList(T).init(allocator) 会编译失败——记住，对 ArrayList 用 .empty，对 StringHashMap 仍是 .init(gpa)。

std.Io 接口：0.16 的重磅革新

如果说 Unmanaged 迁移是一个重要的架构改进，那么 std.Io 接口就是 Zig 0.16 版本中最重要的新特性。它的设计思路与分配器模式如出一辙——通过依赖注入的方式，让同一份业务逻辑代码可以在不同的执行模型下运行。

设计思路

Zig 0.16 的核心思想是：凡是可能阻塞控制流或引入不确定性的操作，都归 I/O 接口管。这意味着文件读写、网络通信、进程管理，甚至某些同步原语，都需要通过 Io 实例来执行。

入口签名非常直观：

zig
1
2
3
4
5
6
7
const std = @import("std");

pub fn main(init: std.process.Init) !void {
    const gpa = init.gpa;
    const io = init.io;
    // 业务逻辑用 io 做文件/网络/进程 I/O
}

注意这里的 main 函数签名——它接收一个 std.process.Init 参数，其中包含了全局分配器（gpa）和 I/O 实例（io）。你的程序不再直接调用系统调用，而是通过 io 实例来执行 I/O 操作。

I/O 后端实现

std.Io 是一个接口而非具体实现。不同的后端决定了 I/O 操作的实际执行方式：

后端	执行模型	底层实现	适用场景	状态
`Io.Threaded`	同步阻塞，多线程并行	操作系统线程	CPU 密集型、简单应用	稳定（默认入口）
`Io.Evented`	事件驱动，异步非阻塞	用户态栈切换 / 工作窃取（M:N 线程）	I/O 密集型、高并发服务	实验性
`Io.Uring`	—	Linux io_uring	—	概念验证（未完成）
`Io.Kqueue`	—	macOS kqueue	—	概念验证
`Io.Dispatch`	—	macOS Grand Central Dispatch	—	概念验证
`Io.failing`	—	模拟无操作	测试	测试用

对于大多数开发者来说，默认使用 Io.Threaded，它功能完整且经过充分测试。Io.Evented 作为实验性后端，为高并发场景提供了未来的方向——它基于用户态栈切换和工作窃取（M:N 线程，即"绿色线程"/协程），但 API 可能还会变化。

高层原语

std.Io 不只是一个 I/O 抽象，它还提供了一套丰富的高层并发原语：

Future — 任务级异步，对应一个异步操作的句柄
Group — 管理一批独立任务，可以统一 await 或 cancel
Queue(T) — 多生产者多消费者的线程安全队列
Select — 对多个 I/O 事件进行选择
Batch — 批量 I/O 操作
Clock / Duration / Timestamp / Timeout — 时间和超时相关的原语

这些原语构成了 Zig 0.16 异步编程的基础设施。你不需要学习复杂的 async/await 关键字（它们在 0.13.0 就已移除），而是通过组合这些原语来表达并发逻辑。

并发编程：Thread.Pool 让位 Io.Group

std.Thread.Pool 在 0.16 版本中已被移除，取而代之的是 std.Io.Group。这是一个重要变化——如果你之前读过任何关于 Zig 线程池的资料，请注意它们已经过时了。

旧模式（已移除）

zig
1
2
3
4
5
fn doAllTheWork(pool: *std.Thread.Pool) void {
    var wg: std.Thread.WaitGroup = .{};
    pool.spawnWg(wg, doSomeWork, .{ pool, &wg, first_work_item });
    wg.wait();
}

新模式（0.16+）

zig
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
fn doAllTheWork(io: std.Io) void {
    var g: std.Io.Group = .init;
    errdefer g.cancel(io);
    g.async(io, doSomeWork, .{ io, &g, first_work_item });
    try g.await(io);
}

fn doSomeWork(io: std.Io, g: *std.Io.Group, foo: Foo) void {
    foo.doTheThing();
    for (foo.new_work_items) |new| {
        g.async(io, doSomeWork, .{ io, g, new });
    }
}

关键变化：

不再需要显式的 Thread.Pool 初始化 — Io.Group 是一个值类型（= .init），开箱即用
使用 errdefer 保证取消 — 如果后续操作出错，可以统一 cancel 所有任务
async 方法接受 io 实例 — 决定了任务在哪个后端上执行（线程还是事件驱动）
await 方法等待所有任务完成 — 返回值是 !void，可以传播错误

迁移注意事项

官方提示，如果你的代码中使用了线程同步原语，在迁移到 0.16 时也需一并替换：

旧（已移除 / 不建议）	新（0.16+）
`std.Thread.Pool`	`std.Io.Group`
`std.Thread.Mutex`	`std.Io.Mutex`
`std.Thread.Condition`	`std.Io.Condition`
`std.Thread.ResetEvent`	`std.Io.Event`
`std.Thread.WaitGroup`	`Io.Group` 的 `await`

关于"函数着色"

Zig 的 I/O 和并发模型在很大程度上解决了经典的"函数着色"问题——即异步函数和同步函数无法直接相互调用的问题：

✅ 不需要 async 关键字标记函数 — 早在 0.13.0 就已移除
✅ 同一份业务逻辑代码可以在同步或异步模式下运行 — 通过 io 参数切换后端
✅ 依赖注入而非硬编码执行模型 — 代码本身不关心是线程还是事件驱动
⚠️ 但 I/O 操作仍需通过 io 接口调用 — 存在一定程度的"接口着色"

Go/Rust 开发者注意：Zig 的并发模型与 Go 和 Rust 都不同。它不像 Go 有内置的 goroutine 调度器，也不像 Rust 有 async/await 的 Future 系统。Zig 的思路是：提供底层原语（线程、Io.Group、Io.Evented），让库和应用自己选择并发策略。std.Io 的设计目标就是让业务逻辑与执行模型解耦。

多语言对比综合案例

在系列收官之际，我们通过一组三语言对比案例来综合复习 Zig 的核心特性。以下三个案例分别展示了动态数组、泛型函数和结构体与方法在 Go、Rust 和 Zig 三种语言中的实现。

案例3：动态数组

Go：

go
1
2
3
4
5
6
7
8
9
func main() {
    var nums []int
    nums = append(nums, 1)
    nums = append(nums, 2, 3)

    for i, v := range nums {
        fmt.Printf("[%d] %d\n", i, v)
    }
}

Rust：

rust
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
fn main() {
    let mut nums = Vec::new();
    nums.push(1);
    nums.push(2);
    nums.push(3);

    for (i, v) in nums.iter().enumerate() {
        println!("[{}] {}", i, v);
    }
}

Zig（0.16+ Unmanaged 模式）：

zig
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
pub fn main(init: std.process.Init) !void {
    const gpa = init.gpa;
    var nums: std.ArrayList(i32) = .empty;
    defer nums.deinit(gpa);

    try nums.append(gpa, 1);
    try nums.append(gpa, 2);
    try nums.append(gpa, 3);

    for (nums.items, 0..) |v, i| {
        std.debug.print("[{}] {}\n", .{ i, v });
    }
}

注意：Zig 示例已更新为 0.16+ 的 Unmanaged 模式——使用 .empty 初始化，append 和 deinit 都接受 allocator 参数。

案例4：泛型函数

Go（1.18+ 泛型）：

go
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
func sum[T int | float64](nums []T) T {
    var total T
    for _, v := range nums {
        total += v
    }
    return total
}

func main() {
    ints := []int{1, 2, 3}
    fmt.Println(sum(ints)) // 6
}

Rust（trait bound）：

rust
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
fn sum<T: Add<Output = T> + Copy>(nums: &[T]) -> T {
    let mut total = nums[0];
    for &v in nums {
        total = total + v;
    }
    total
}

fn main() {
    let nums = vec![1, 2, 3];
    println!("{}", sum(&nums)); // 6
}

Zig（comptime 泛型）：

zig
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
fn sum(comptime T: type, nums: []const T) T {
    var total: T = 0;
    for (nums) |v| {
        total += v;
    }
    return total;
}

pub fn main() void {
    const nums = [_]i32{1, 2, 3};
    const result = sum(i32, &nums); // 6
    std.debug.print("{}\n", .{result});
}

Zig 使用 comptime T: type 实现泛型，不需要 Go 的类型约束或 Rust 的 trait bound——“只要类型支持 + 操作就能用”，这是编译期鸭子类型的体现。

案例5：结构体与方法

Go：

go
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
type Point struct {
    X, Y float64
}

func (p Point) Distance() float64 {
    return math.Sqrt(p.X*p.X + p.Y*p.Y)
}

func main() {
    p := Point{X: 3, Y: 4}
    fmt.Println(p.Distance()) // 5
}

Rust：

rust
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
struct Point {
    x: f64,
    y: f64,
}

impl Point {
    fn distance(&self) -> f64 {
        (self.x * self.x + self.y * self.y).sqrt()
    }
}

fn main() {
    let p = Point { x: 3.0, y: 4.0 };
    println!("{}", p.distance()); // 5
}

Zig：

zig
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
const Point = struct {
    x: f64,
    y: f64,

    fn distance(self: *const Point) f64 {
        return @sqrt(self.x * self.x + self.y * self.y);
    }
};

pub fn main() void {
    const p = Point{ .x = 3.0, .y = 4.0 };
    std.debug.print("{}\n", .{p.distance()}); // 5
}

Zig 的结构体将数据和方法定义在一起（没有 Go 的 receiver 语法或 Rust 的 impl 块），方法通过 self: *const T 参数显式接收调用者引用。

学习路线图

如果你是从第一篇一路看到现在的，其实已经走过了第一阶段。以下是完整的四个阶段建议：

阶段一：基础入门（1-2 周）

变量、常量、基本数据类型
控制流（if、switch、循环）
函数定义与调用
结构体与方法
错误处理基本用法（try/catch）

阶段二：核心概念（2-3 周）

分配器模式与内存管理
comptime 编译期计算
泛型编程（comptime T: type + anytype）
标准库常用数据结构
defer/errdefer 资源管理

阶段三：进阶特性（3-4 周）

指针与切片操作
编译期反射与元编程
并发编程（Io.Group、std.Thread）
std.Io 接口（0.16+，注意版本变化）
与 C 语言互操作

阶段四：实战项目（持续）

命令行工具开发
网络编程（可关注 libxev 等社区库）
系统级编程
参与开源项目

学习资源推荐

官方资源

Zig 官方文档：ziglang.org/documentation/ — 最权威的参考
Zig Learn：ziglearn.org/ — 社区维护的入门教程
Zig 源码：codeberg.org/ziglang/zig — 标准库是最好的学习材料
Zig 下载：ziglang.org/download/

中文资源

Zig 语言圣经：course.ziglang.cc/ — 中文入门教程
Zig 中文社区：ziggit.cn/ — 中文讨论社区

进阶资源

Loris Cro’s Blog：kristoff.it/blog/ — Zig 核心开发者的博客
LWN.net：lwn.net/ — 深度技术文章
Zig Show：YouTube 频道，社区访谈和技术分享

写在最后

Zig 是一门还在快速演进的语言。这六篇的跨度从 0.11 写到 0.16，见证了 async/await 的移除、Thread.Pool 的告别、ArenaAllocator 的线程安全化、GeneralPurposeAllocator 的退役、标准库容器的 Unmanaged 迁移，以及 std.Io 接口的诞生。

这些演进背后有一条清晰的哲学线：暴露机制，而非强加策略。分配器是传入的参数而不是全局的设定；I/O 是通过接口注入的选择而不是内建的语义；编译期是你可以触碰的开关而不是黑箱。

如果你读到了这里，希望这六篇文章能成为你 Zig 之旅的开端。源码是最诚实的文档——去读标准库的源码，去写点实际的东西。在 ziggit.cn 上提问，在 Codeberg 上提 PR，在 Zig Show 的讨论中参与。这门语言还年轻，它的故事远没写完。

而你，就是下一个写故事的人。

所属系列: Zig 语言学习系列

← 上一篇结构体与 comptime：编译期计算的威力