Zig:从设计哲学到核心特性 · Zig 0.17 完整学习手册(含 18 讲专题深化)
From Beginner to Slightly Less Beginner · 设计哲学 + 工程实践 + 系统设计 · 已全面修订至 Zig 0.17
依据 B 站《Zig 编程语言》合集共 19 讲整理(第一部分 1 讲 + 第二部分 12 讲 + 第三部分 6 讲)· 过时写法逐条标注 · 每段代码均经 0.17.1 编译运行
19 讲视频教材化 · 43 章节正文与附录 · 30 段可运行示例 · 0.17.1 编译器实测校对
Markdown 版说明:本文件由同目录 HTML 手册完整转换生成,内容与 2026-11-15 版 HTML 一致;网页的交互目录、深色模式、代码复制按钮不适用,章节跳转改用显式锚标记与顶部目录。全部 Zig 示例仍以
Zig 0.17.1实测结果为准。
来源与校对说明
| 项目 | 内容 |
|---|---|
| B 站视频 | BV1qB4p6fE7g · Zig:从设计哲学到核心特性的深度解析 |
| UP 主 / 发布 | myfreax · 2026-11-08 · 合集《Zig 编程语言》第 46 集 |
| 分 P | P1 中文配音 / P2 原声,各 78:04 |
| 原始演讲 | Zig: From Beginner to Slightly Less Beginner,Sawyer X 主讲,Code Maven / Zig Maven 主办,2026-10-29 |
| 主持人 | Gabor Szabo(szabgab) |
| 原视频 | youtube.com/watch?v=jWCQXBVIyrY |
| 内容依据 | 该视频完整英文转录(含问答)、演讲文字笔记、B 站视频元数据 |
| 版本依据 | Zig 0.17.0 官方 Release Notes、0.17 官方文档、本机 0.17.1 标准库源码与编译器实测 |
| 第三部分来源 | B 站《Zig 编程语言》合集另外 6 讲(StaticStringMap、两种队列、DoD、任务取消、无指针编程、内存布局),完整索引与材料局限见附录 G |
关于版本:视频录制于 0.17.0 发布后不久,但幻灯片中的代码沿用了更早版本(0.14 / 0.15 及以前)的写法。本手册不照抄幻灯片,而是把每个示例重写为 0.17 合规形式;凡视频里出现的旧写法,都在对应章节用「过时提醒」列出,并在第 12 章汇总。
0.17.1 实测通过
手册中 10 段 Zig 代码全部是独立完整程序,逐段用本机 0.17.1 编译并运行成功。第 12 章列出的 8 条「已移除」写法,也都用 0.17.1 实际编译过,附的是真实报错信息,不是推测。
标记图例
| 标记 | 含义 |
|---|---|
| 过时提醒 · 0.17 已移除 | 该写法在 0.17 直接编译失败,必须改写 |
| 过时提醒 · 0.17 已改名 | 旧名字不存在或已弃用,给出新名字 |
| 过时提醒 · 仍可编译但已弃用 | 最危险:不报错、不警告,但应尽快替换 |
| 过时提醒 · 静默行为变化 | 能编译、结果可能悄悄错,必须人工审查 |
| 0.17.1 实测通过 | 本段代码已在 0.17.1 编译运行结果正确 |
| 演讲原话 | 视频中 Sawyer X 的观点,保留其原意 |
目录
第一部分 · 设计哲学与核心特性
- 00 阅读前:0.17 的代码基线
- 01 这场演讲到底在讲什么
- 02 第一性原则:一切可见
- 03 贯穿示例(一):手写配置解析
- 04 显式内存分配:Allocator 是参数
- 05 缺失值:?T 与一个 orelse 走天下
- 06 错误即值:!、try、catch 与穷尽 switch
- 07 标签联合:数据自带元数据
- 08 多序列 for:长度不匹配就报错
- 09 清理:defer 与 errdefer
- 10 comptime:用 Zig 写 Zig
- 11 SIMD:向量只是一种类型
- 12 重点:0.17 过时语法与内容总清单
- 13 练习与自测
- 14 延伸资源
第二部分 · 专题深化(12 讲)
- Ⅱ 第二部分导学与课程地图
- 15 Allocator 心智模型
- 16 安全分配器与泄漏报告
- 17 ArenaAllocator 与批量释放
- 18 FBA 与 MemoryPool 零堆分配
- 19 ArrayList 增长与指针失效
- 20 HashMap 键的所有权与顺序
- 21 MultiArrayList 与 SoA
- 22 枚举集合:零分配
- 23 选型学:决策路径
- 24 Async I/O 与并发
- 25 SIMD 实战:CSV 解析
- 26 构建系统:DAG 与跨平台
第三部分 · 进阶专题(6 讲)
- Ⅲ 第三部分导学与专题地图
- 27 StaticStringMap 编译期分派
- 28 PriorityQueue 与 Deque
- 29 DoD 实战与实测
- 30 任务取消协议
- 31 无指针数据结构
- 32 内存布局与位宽
附录
- 附录 A 问答环节精要
- 附录 B 全部示例索引与运行方式
- 附录 C 参考来源
- 附录 D 视频课程索引(12 讲)
- 附录 E 0.16→0.17 迁移速查
- 附录 F 综合实验与自测
- 附录 G 视频课程索引(6 讲)
- 附录 H 第三部分实验与自测
00 阅读前:0.17 的代码基线
先把「能跑起来的 0.17 程序」长什么样定下来,后面所有示例都建立在这套基线上。
const std = @import("std");
// Zig 0.17: main 接收 std.process.Init,stdout 通过 init.io 显式写出。
pub fn main(init: std.process.Init) !void {
var buf: [1024]u8 = undefined;
var file_writer = std.Io.File.stdout().writerStreaming(init.io, &buf);
const out = &file_writer.interface;
try out.print("Hello, {s}!\n", .{"Zig 0.17"});
try out.print("1 + 2 = {d}\n", .{1 + 2});
try out.flush(); // 忘记 flush 就没有任何输出
}
运行:
zig run 01_hello.zig
# Hello, Zig 0.17!
# 1 + 2 = 3
三个 0.17 要点:
main(init: std.process.Init)是新入口。init.io把「可能阻塞的操作」显式交给调用者,和Allocator是同一种设计;init.gpa、init.arena、init.environ、init.args也在其中。- Writer 带缓冲区,缓冲区由你提供,因此没有隐式分配;写完必须
flush()。 std.debug.print在 0.17 依然可用、且不需要io,适合教学与诊断(官方 0.17 文档的第二个 Hello World 就是它)。本手册后面的短示例用它,是为了让重点落在语言特性上,而不是 I/O 样板。
过时提醒 · 0.17 已移除
老教程里的
std.io.getStdOut().writer()/std.io.fixedBufferStream(...)全部失效。0.17.1 实测报错:error: root source file struct 'std' has no member named 'io'。文件系统同理:std.fs.cwd().openFile(...)改为std.Io.Dir.cwd().openFile(io, ...),每个磁盘操作都要传io。
0.17.1 实测通过
上面这段 Hello 程序输出
Hello, Zig 0.17!与1 + 2 = 3。
01 这场演讲到底在讲什么
Sawyer X 有 20 多年开发经验,曾是 Perl 5 的语言负责人(Pumpking)。他开场就划了两条线:这不是「我的语言比你的语言好」的辩论,而是看一门语言用什么思路去解决工程问题;另外,幻灯片里的例子是为了表达想法,不是最优解。
演讲原话
「语法是别人教你一门语言时最先讲的东西……但我真正想谈的,是这门语言用来解决问题的那些想法。」「Zig 的语言本身很小,一天就够;标准库很大,能做很多很酷的事。」
所以整场演讲只用几页讲语法:i32、分号、return result、花括号,剩下全在讲设计取舍。语法里唯一被他特意拎出来的是点号:
const Level = enum { debug, info, warn };
const Server = struct {
log: Level = .info, // 等价 Level.info:类型已知,Zig 自己推断
};
.info、.{ ... }、.transfer 里的点,意思都是「帮我推断」。这个细节后面会反复出现。
关于设计哲学,他给了个「钟摆」比喻:一端是语言替你包办一切、同时收走控制权;另一端是给你全部控制权、但什么都要自己写。Zig 在找中间位置——把问题范围收窄,砍掉那些在两端来回摆的「好点子」,再给你一套干净利落的工具。运行 zig zen 能看到官方版的表达:没有隐藏控制流、没有隐式内存分配、没有预处理器和宏、把问题尽可能变成编译期错误。
02 第一性原则:一切可见
演讲的核心论证从一行伪代码开始:A = B + C。在多数语言里,你其实说不准它会做什么:
+有没有被重载?是给B重载了,还是给C,还是两者都有?C是不是一个背后带 getter 的属性?在 Perl 里,读写变量甚至可能触发 magic 回调。- 等号左边是什么上下文?Perl 能按返回值所处的位置改变操作。
- 会不会抛出异常?异常会飞到哪里去?不在你眼前。
演讲原话
「在 Zig 里它只做一件事:把 B 和 C 相加,存进 A。就这样。文档第一句就是:如果一段代码看起来不像函数调用,它就不会调用函数。」
由此推出四条,正好对应演讲后面每一章:
| 原则 | 具体含义 | 对应章节 |
|---|---|---|
| 没有隐藏控制流 | 没有异常、没有运算符重载、没有 getter / magic 回调;因此「提前 return」很省心 | 06、07 |
| 没有隐式内存分配 | 任何要向操作系统要内存的函数,都会收到一个 allocator;签名就是说明书 | 04 |
| 没有宏 | 元编程就是 Zig 本身,不是「用另一门语言去写你想要的语言」 | 10 |
| 清理就地可见 | defer / errdefer 写在需要它的作用域里 | 09 |
顺带一个反直觉的结论:没有 allocator 参数,本身也是信息——它说明这个函数根本不分配内存。演讲开头那版配置解析代码就是如此。
03 贯穿示例(一):手写配置解析
演讲用同一个例子串起全场:把 "port=9000 workers=8 log=warn tls=yes" 这样的字符串解析进一个 Server 结构体。
需求与约束(视频逐条列过):
port是u16,workers是u8(最多 255),timeout是f32(允许小数);- 有默认值:
port = 8080、log = .info; - 要校验:字符串当数字、数值过大、未知日志级别、结构体里不存在的键(比如
color)、只有键没有值。
第一版是手写 if 链。注意:下面是按 0.17 重写并通过编译的版本,与幻灯片里的旧写法不同。
const std = @import("std");
const Level = enum { debug, info, warn };
const Server = struct {
port: u16 = 8080,
workers: u8 = 4,
timeout: f32 = 1.5,
log: Level = .info,
tls: bool = false,
};
// 视频里的「第一版」:每个 key 都要手写一遍检查、解析、赋值
fn parseServer(text: []const u8) !Server {
var result: Server = .{};
var pairs = std.mem.tokenizeAny(u8, text, " \n");
while (pairs.next()) |pair| {
const eq = std.mem.findScalar(u8, pair, '=') orelse return error.MissingEquals;
const key = pair[0..eq];
const value = pair[eq + 1 ..];
if (value.len == 0) return error.MissingValue;
if (std.mem.eql(u8, key, "port")) {
result.port = try std.fmt.parseInt(u16, value, 10);
} else if (std.mem.eql(u8, key, "workers")) {
result.workers = try std.fmt.parseInt(u8, value, 10);
} else if (std.mem.eql(u8, key, "timeout")) {
result.timeout = try std.fmt.parseFloat(f32, value);
} else if (std.mem.eql(u8, key, "log")) {
result.log = std.meta.stringToEnum(Level, value) orelse return error.InvalidLog;
} else if (std.mem.eql(u8, key, "tls")) {
if (std.mem.eql(u8, value, "true") or std.mem.eql(u8, value, "yes")) {
result.tls = true;
} else if (std.mem.eql(u8, value, "false") or std.mem.eql(u8, value, "no")) {
result.tls = false;
} else return error.InvalidBool;
} else {
return error.UnknownKey;
}
}
return result;
}
pub fn main() !void {
const s = try parseServer("port=9000 workers=8 log=warn tls=yes");
std.debug.print("port={d} workers={d} timeout={d} log={t} tls={}\n", .{
s.port, s.workers, s.timeout, s.log, s.tls,
});
}
输出:port=9000 workers=8 timeout=1.5 log=warn tls=true
0.17.1 实测通过
运行结果如上。注意这里
{t}用于打印枚举标签,是 0.17 的格式写法;老代码里的{}在 0.17 已不调用自定义format方法。
过时提醒 · 0.17 已改名
找等号用
std.mem.findScalar,旧教程与幻灯片常见的std.mem.indexOfScalar在 0.17 只是弃用别名(仍能编译)。indexOf系列整体改名为find系列。另外std.fmt.parseInt/parseFloat/std.meta.stringToEnum在 0.17 依然有效,可以放心用。
演讲原话
「你看着这段代码,可能和我想的一样:这很丑。我自己写的代码我也不喜欢它。」问题不在语法,而在于每个字段都要重复写「键名、检查、解析方式、存到哪里」这四件事。第 10 章会用 comptime 把它彻底消掉。
04 显式内存分配:Allocator 是参数
场景:从用户列表里筛出 18 岁以上的成年人,生成一个新的列表(而不是惰性迭代)。
| 语言 | 做法 | 谁负责增长 | 谁负责回收 |
|---|---|---|---|
| Python | [u for u in users if u.age >= 18] | 运行时 / GC | GC |
| Perl | grep { $_->{age} >= 18 } @users | 运行时 | 引用计数 |
| Go | append(adults, u) | 运行时 | GC |
| Rust | users.iter().filter(...).collect() | 全局堆 | 所有权 / Drop |
| C | malloc + 自己 realloc + 检查返回值 | 你 | 你 |
| Zig | try list.append(gpa, u) | 你传入的 allocator | 同一个 allocator |
Sawyer 的重点不是「谁更省事」,而是换内存策略的代价。Rust 想把结果放进 bump allocator,得改函数签名、改返回类型、collect 变 collect_in、引入 crate;Zig 里 findAdults 一个字都不用改,因为 allocator 本来就是参数。
const std = @import("std");
const User = struct { name: []const u8, age: u8 };
const users = [_]User{
.{ .name = "Ada", .age = 36 },
.{ .name = "Grace", .age = 37 },
.{ .name = "Linus", .age = 16 },
.{ .name = "Margaret", .age = 12 },
};
// 分配器是普通参数:签名本身就说明「这个函数可能会分配内存」。
fn findAdults(gpa: std.mem.Allocator, all: []const User) ![]User {
var list: std.ArrayList(User) = .empty;
errdefer list.deinit(gpa); // 仅在返回错误时清理
for (all) |u| {
if (u.age >= 18) try list.append(gpa, u);
}
return list.toOwnedSlice(gpa);
}
fn report(label: []const u8, gpa: std.mem.Allocator) !void {
const adults = try findAdults(gpa, &users);
defer gpa.free(adults);
std.debug.print("{s}: {d} adults\n", .{ label, adults.len });
}
pub fn main() !void {
// 0.17 的泄漏检测分配器:deinit() 返回泄漏数量
var safe: std.heap.SafeAllocator = .init(std.heap.page_allocator, .{});
defer std.debug.assert(safe.deinit() == 0);
try report("SafeAllocator", safe.allocator());
// 换分配器,findAdults 一行都不用改
var arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator);
defer arena.deinit();
try report("ArenaAllocator", arena.allocator());
var backing: [1024]u8 = undefined;
var fixed: std.heap.FixedBufferAllocator = .init(&backing);
try report("FixedBufferAllocator", fixed.allocator());
}
输出:
SafeAllocator: 2 adults
ArenaAllocator: 2 adults
FixedBufferAllocator: 2 adults
0.17.1 实测通过
三种分配器输出一致;
SafeAllocator.deinit()返回0,表示无泄漏。
分配器选择就是设计选择
- Arena:演讲里用「整层停车场」作比喻——一次向操作系统要大块内存,之后内部分配不再打扰 OS,程序结束时整体释放。短命的 CLI 程序用它可以完全不用逐项 free。
- FixedBufferAllocator:在栈上划 1 KB,全程不碰堆;超出就返回
error.OutOfMemory。 - SafeAllocator:0.17 的调试期分配器,检查泄漏、double free、越界。
- 演讲问答里明确说:同一个程序完全可以混用多个分配器,按操作的生命周期挑。
泄漏能被测试抓到
const std = @import("std");
test "intentional leak" {
const buf = try std.testing.allocator.alloc(u8, 3);
_ = buf; // 故意不 free:测试分配器会报告泄漏位置
}
0.17.1 的 zig test 实际输出(节选):
1/1 leak_test.test.intentional leak...OK
[SafeAllocator] (err): leaked [addr: 1c34f3f0010, len: 3 (0x3) align: 1] allocated at:
leak_test.zig:4:48: ... in test.intentional leak
All 1 tests passed.
1 errors were logged.
过时提醒 · 静默行为变化
注意最后两行:测试显示通过,但泄漏被记录成一条 error log。0.17 的
std.testing.allocator底层是SafeAllocator,它报告泄漏但不一定让测试失败。视频里说「运行就会告诉你泄漏了」,在 0.17 依然成立,但不要以为zig test一定返回失败码——CI 里要盯着日志,或在代码里断言deinit() == 0。
过时提醒 · 0.17 已移除
视频把分配器叫 GPA(General Purpose Allocator),这是过时名称。0.17.1 实测:
error: root source file struct 'heap' has no member named 'GeneralPurposeAllocator'。演变链条是GeneralPurposeAllocator→DebugAllocator→std.heap.SafeAllocator。
过时提醒 · 0.17 已改名
视频里的
std.ArrayList(T).init(gpa)/list.append(x)/list.deinit()是托管版写法,0.15 起已改为非托管:.empty初始化、append(gpa, x)、deinit(gpa)、toOwnedSlice(gpa)。0.17.1 实测报错:error: struct 'array_list.Aligned(u8,null)' has no member named 'init'。这样写代码更啰嗦一点,但每一次可能分配内存的调用都能看见 allocator,正是第 02 章的原则。
过时提醒 · 仍可编译但已弃用
std.heap.DebugAllocator、std.heap.stackFallback中前者是别名、后者已移除(BufferFirstAllocator取代)。另外 0.17 的ArrayList新增lockPointers()/unlockPointers():如果你持有 list 内部元素的指针或切片,上锁后任何会导致失效的操作会直接断言,便于抓隐藏 bug。
05 缺失值:?T 与一个 orelse 走天下
「按名字查用户,可能查不到」在各语言里的结果:C 可能段错误;Perl 的自动活化会悄悄造出一个 hash 引用;Python 抛 AttributeError;Java 抛异常;Rust / Swift / Kotlin / Zig 编译期就拦住。
Zig 的写法是加一个问号:
fn findUser(name: []const u8) ?User { ... } // ?T = 要么 T,要么 null
完整示例:
const std = @import("std");
const User = struct { name: []const u8, age: u8 };
const users = [_]User{
.{ .name = "Ada", .age = 36 },
.{ .name = "Grace", .age = 37 },
.{ .name = "Linus", .age = 16 },
};
fn findUser(name: []const u8) ?User {
for (users) |u| {
if (std.mem.eql(u8, u.name, name)) return u;
}
return null;
}
pub fn main() void {
// 1) if + 捕获:存在与不存在两条路径都写清楚
if (findUser("Grace")) |u| {
std.debug.print("found: {s} ({d})\n", .{ u.name, u.age });
} else {
std.debug.print("not found\n", .{});
}
// 2) orelse 返回错误
const required = findUser("Ada") orelse return;
std.debug.print("required: {s}\n", .{required.name});
// 3) orelse 提供默认值
const guest: User = findUser("Nobody") orelse .{ .name = "guest", .age = 0 };
std.debug.print("default: {s}\n", .{guest.name});
// 4) orelse continue:跳过缺失项
var adults: usize = 0;
for (users) |u| {
const found = findUser(u.name) orelse continue;
if (found.age >= 18) adults += 1;
}
std.debug.print("adults: {d}\n", .{adults});
// 5) orelse unreachable:断言必然存在
const certain = findUser("Linus") orelse unreachable;
std.debug.print("certain: {s}\n", .{certain.name});
}
0.17.1 实测通过
输出
found: Grace (37)/required: Ada/default: guest/adults: 2/certain: Linus。
演讲最漂亮的一段对比:Rust 处理这四种意图需要 ok_or()?、let Some(x) = ... else { continue; }、unwrap_or(default)、unwrap() 四套东西;Zig 只有一个 orelse——返回错误、跳过、给默认值、断言存在,全靠右侧表达式不同。这是「少记规则、多靠组合」的设计取向。
可选值与错误在语法上也是对仗的:
| 意图 | 可选值 ?T | 错误联合 !T |
|---|---|---|
| 类型标记 | ? | ! |
| 就地兜底 | orelse | catch |
| 向上冒泡 | 无(要么给值,要么处理) | try |
| 带捕获的分支 | if (x) |v| | if (x) |v| ... else |err| |
06 错误即值:!、try、catch 与穷尽 switch
配置文件给了 port=web 会怎样?演讲做了一张很毒舌的对照表:
| 语言 | 解析失败的结果 |
|---|---|
C (atoi) | 返回 0,还得自己查 errno |
| Perl | 尽力取前导数字,取不到就当 0,只给一条 warning |
| Go | 经常看到 port, _ := ...,忽略 err 后同样拿到 0 |
| Python | 抛异常,至少算个错误 |
| Java | 「Java 热爱异常」 |
| Rust | 编译期/警告层面拦住 |
| Zig | 编译不过,或者必须显式处理错误 |
Zig 的错误就是枚举值,写在函数签名里:
const std = @import("std");
// 错误是签名的一部分:!u16 表示「要么 u16,要么一个错误值」。
fn parsePort(text: []const u8) !u16 {
const port = try std.fmt.parseInt(u16, text, 10); // try = 出错就把错误返回给调用者
if (port == 0) return error.PortZero; // 自定义错误,无需注册
return port;
}
pub fn main() void {
// 0.17 推荐 {t} 打印错误名 / 枚举标签
for ([_][]const u8{ "8080", "0", "web", "70000" }) |text| {
const port = parsePort(text) catch |err| switch (err) {
error.PortZero => 0,
error.Overflow => 0,
error.InvalidCharacter => 0,
// 漏掉任何一个分支,编译器都会报错(穷尽性检查)
};
std.debug.print("port(\"{s}\") = {d}\n", .{ text, port });
}
// catch 也能拿到错误名
_ = parsePort("web") catch |err| {
std.debug.print("rejected: {t}\n", .{err});
return;
};
}
0.17.1 实测通过
输出
port("8080") = 8080、其余三项为0,最后打印rejected: InvalidCharacter。
三个要点:
!u16是 error union:u16或某个错误。!单独用(不写具体集合)就是「让编译器推导所有可能的错误」;想收窄可以写error{ Overflow, InvalidCharacter, PortZero }!u16。try只有一个含义:出错就把这个错误原样返回。catch |err| switch (err) { ... }必须覆盖全部可能的错误,否则编译不过;想偷懒要显式写else。
演讲原话
「异常是另一套系统:你要学它的层级、checked / unchecked、wrap / rethrow……最后你是在给异常编程,而不是在处理错误。」他同样吐槽 Rust 的错误生态(
From、Display、thiserror、anyhow)过于庞大。
代价也要讲清楚:错误只是枚举值,不带 payload。想要附带诊断信息(证书详情、连接上下文),得额外返回一个诊断结构体,不能像异常那样塞字段。
过时提醒 · 0.17 已移除
errdefer |err| { ... }这种带错误捕获的写法在 0.17 不再解析,0.17.1 实测报错:error: expected block or expression, found '|'。改用catch |err| { 记录日志; return err; },把处理逻辑放到错误发生的边界。普通errdefer(无捕获)仍然有效。
07 标签联合:数据自带元数据
支付场景:现金是一个金额,银行卡有持卡人,银行转账有 IBAN。老办法是「数据 + 一个 kind 变量」两条信息轨道;新增一种支付方式时,旧代码不会有任何提示。Perl、Python 如此,C 要打开全部编译警告才可能提示,Rust 的 match 能兜住,Zig 也能。
const std = @import("std");
// 标签联合:数据 + 「我是哪一种」的元数据,编译器帮你保管
const Payment = union(enum) {
cash: u32,
card: struct { holder: []const u8, last4: []const u8 },
transfer: struct { iban: []const u8 },
};
const Level = enum { debug, info, warn };
fn describe(p: Payment) void {
// 穷尽 switch:新增一种支付方式而漏处理,编译不通过
switch (p) {
.cash => |amount| std.debug.print("cash: {d}\n", .{amount}),
.card => |c| std.debug.print("card: {s} ({s})\n", .{ c.holder, c.last4 }),
.transfer => |t| std.debug.print("transfer: {s}\n", .{t.iban}),
}
}
pub fn main() void {
const p: Payment = .{ .transfer = .{ .iban = "DE89370400440532013000" } };
describe(p);
// 点号推断:比较时写 .transfer 而不是 Payment.transfer
if (p == .transfer) std.debug.print("is transfer\n", .{});
// 直接向编译器问 tag,不用为了拿名字再写一整个 switch。
// 0.17 里 {t} 用于打印枚举标签 / 错误名。
std.debug.print("tag = {s}, level = {t}\n", .{ @tagName(p), Level.info });
}
0.17.1 实测通过
输出
transfer: DE89370400440532013000/is transfer/tag = transfer, level = info。
演讲强调的两个 Zig 特色:
- 点号推断:写
.{ .transfer = ... }、.card分支、p == .transfer,都不用重复Payment.前缀;Rust 得写全Payment::Card。 @tagName直接问标签:Rust 想知道 tag 名通常得再写一次 match,在每个分支里造字符串;Zig 因为 union 自带 tag,可以直接取。访问不匹配的字段(在 card 上取iban)也会被检查。
08 多序列 for:长度不匹配就报错
三个名字、两个年龄,一起遍历会怎样?C 越界读垃圾值;Perl 给 undef 加 warning;Python 的 zip 和 Rust 的 zip 都悄悄丢掉多出来的名字。Zig 拒绝猜测。
const std = @import("std");
pub fn main() void {
const names = [_][]const u8{ "Ada", "Grace", "Linus" };
const ages = [_]u8{ 36, 37, 55 };
// for 可以同时迭代任意多个序列,并用 0.. 生成无界索引
for (names, ages, 0..) |name, age, i| {
std.debug.print("{d}: {s} is {d}\n", .{ i, name, age });
}
// 长度不一致:编译期已知时是编译错误;运行期才知道时 panic
const short = [_]u8{ 1, 2 };
const both: []const u8 = &short;
const known = [_][]const u8{ "x", "y", "z" };
_ = both;
_ = known;
}
0.17.1 实测通过
输出三行
0: Ada is 36/1: Grace is 37/2: Linus is 55。
规则:编译期能判定长度不一致 → 编译错误;只有运行期才知道长度 → panic。把两个序列换成不等长数组在本机编译会直接被拒。0.. 是无界 range,会跟着最短的序列一起结束,不用手算长度。
演讲原话
「我要小小地夸一下这个设计:想迭代几个变量就写几个,用最少的文字把当前项捕获出来,同时又不会默默做错事。」
09 清理:defer 与 errdefer
清理逻辑的演化:C 常常把 cleanup 集中到函数末尾的 goto cleanup,得自己保持同步;C++ 靠析构函数(清理发生在别处);Python 的 with 很好但要求对象支持上下文管理、还会引入一层作用域;Go 的 defer 思路对,但作用域是整个函数,放在循环里会一直攒到函数结束。
Zig 的 defer 是当前作用域,errdefer 只在函数因错误返回时执行:
const std = @import("std");
fn risky(fail: bool) !void {
const buf = try std.heap.page_allocator.alloc(u8, 3);
defer std.heap.page_allocator.free(buf); // 作用域结束一定执行
errdefer std.debug.print("cleanup on error only\n", .{}); // 只在出错返回时执行
if (fail) return error.BadInput;
std.debug.print("success path\n", .{});
}
pub fn main() void {
// 0.17 移除了 errdefer |err| 捕获;要拿错误就 catch 后自行返回
risky(false) catch |err| {
std.debug.print("caught: {t}\n", .{err});
};
risky(true) catch |err| {
std.debug.print("caught: {t}\n", .{err});
};
}
0.17.1 实测通过
输出
success path→cleanup on error only→caught: BadInput。成功路径不会触发errdefer。
注意 errdefer 与 defer 的先后顺序(LIFO):同一作用域里后注册的先执行。写资源初始化时,把 errdefer 紧跟在成功分配之后是惯例——初始化一半出错也能收干净。
过时提醒 · 0.17 已移除
0.16 及以前可以用
errdefer |err|拿到即将返回的错误。0.17 删除了该捕获(见第 06 章的实测报错)。需要错误信息时,用catch |err| { ...; return err; }在错误边界处理。
10 comptime:用 Zig 写 Zig
这是全场的收束,也是版本差异最大的一章。演讲要解决的问题就是第 03 章那句「这很丑」。
思路分两层:
第一层:类型也是值。 u16、f32、enum 都是 comptime type 类型的值,可以当参数传给函数。于是写一个通用的 parseValue(T, text),用 @typeInfo(T) 判断种类,分派到 parseInt / parseFloat / stringToEnum / 布尔比较。
第二层:结构体的字段信息也是编译期数据。 用 @typeInfo(Server) 拿到字段名和字段类型,inline for 在编译期把 if 链全部展开,@field(result, name) 负责把值写进对应字段。于是 parse(Server, text) 和 parse(Client, text) 用的是同一个函数——结构体自己就是配置格式的说明书,加字段不用改解析器。
过时提醒 · 0.17 已移除 · 本章最重要
幻灯片里的元编程基于
@typeInfo(T).@"struct".fields,遍历|f|再取f.name/f.type。这在 0.17 编译不过:0.17.1 实测error: no field named 'fields' in struct 'lang.Type.Struct'。0.17 改成平行数组:field_names[i]、field_types[i]、field_attrs[i]按下标对应;枚举用field_names/field_values;联合体、声明、函数参数、错误集也全部改成平行数组。默认值现在通过field_attrs[i].defaultValue(T)读取。下面的完整代码已按此改写并通过编译。
const std = @import("std");
const Level = enum { debug, info, warn };
const Server = struct {
port: u16 = 8080,
workers: u8 = 4,
timeout: f32 = 1.5,
log: Level = .info,
tls: bool = false,
};
const Client = struct {
name: []const u8 = "guest",
max_connections: u32 = 10,
tls: bool = false,
};
// 类型是值:传进来一个 type,按它的种类决定怎么解析。
fn parseValue(comptime T: type, text: []const u8) !T {
if (T == []const u8) return text;
return switch (@typeInfo(T)) {
.@"int" => try std.fmt.parseInt(T, text, 10),
.float => try std.fmt.parseFloat(T, text),
.bool => blk: {
if (std.mem.eql(u8, text, "true") or std.mem.eql(u8, text, "yes")) break :blk true;
if (std.mem.eql(u8, text, "false") or std.mem.eql(u8, text, "no")) break :blk false;
return error.InvalidBool;
},
.@"enum" => std.meta.stringToEnum(T, text) orelse return error.InvalidEnum,
else => @compileError("unsupported field type: " ++ @typeName(T)),
};
}
// 用 @typeInfo 读出结构体字段名 + 字段类型,编译期把 if 链全部展开。
fn parse(comptime T: type, text: []const u8) !T {
var result: T = .{};
const info = @typeInfo(T).@"struct";
var pairs = std.mem.tokenizeAny(u8, text, " \n");
while (pairs.next()) |pair| {
const eq = std.mem.findScalar(u8, pair, '=') orelse return error.MissingEquals;
const key = pair[0..eq];
const value = pair[eq + 1 ..];
if (value.len == 0) return error.MissingValue;
var matched = false;
inline for (info.field_names, info.field_types) |name, FieldType| {
if (!matched and std.mem.eql(u8, key, name)) {
@field(result, name) = try parseValue(FieldType, value);
matched = true;
}
}
if (!matched) return error.UnknownKey;
}
return result;
}
pub fn main() !void {
const s = try parse(Server, "port=9000 workers=8 log=warn tls=yes");
std.debug.print("server: port={d} workers={d} timeout={d} log={t} tls={}\n", .{
s.port, s.workers, s.timeout, s.log, s.tls,
});
const c = try parse(Client, "name=alpha max_connections=64");
std.debug.print("client: name={s} max={d} tls={}\n", .{ c.name, c.max_connections, c.tls });
// 未覆盖的错误类型:编译期就会拒绝
_ = parse(Server, "color=red") catch |err| {
std.debug.print("rejected: {t}\n", .{err});
};
}
输出:
server: port=9000 workers=8 timeout=1.5 log=warn tls=true
client: name=alpha max=64 tls=false
rejected: UnknownKey
0.17.1 实测通过
输出如上。给
Client加一个max_connections: u32字段,解析器无需改动就自动支持——这正是演讲想表达的「用 Zig 写 Zig」。
几个语法点:
.@"int"/.@"enum"是带引号的标识符,用于int、enum、struct这类保留字作为 union tag 的场合;视频里专门夸了这个设计。comptime T: type中的comptime对类型参数可省略,写出来是为了强调。inline for不是运行期循环,编译期就把每个字段展开成一段独立的 if,因此@field的字段名必须是编译期已知的。else => @compileError(...):遇到不支持的字段类型,直接变成编译期错误,而不是运行期崩溃。这就是第 02 章「把问题尽量冒到编译期」的落点。
过时提醒 · 0.17 已改名
std.meta.fields(T)、std.meta.fieldInfo、fieldNames、fieldTypes在 0.17 被弃用,统一改用@typeInfo;std.meta.Int/std.meta.Tuple移除,改用@Int/@Tuple内建函数。0.17 起@Type也被一组更具体的内建函数取代(@Struct、@Enum、@Int、@Pointer、@Fn、@Union等),没有@Array,数组仍用普通语法。
对比其他语言的同类能力:C 靠 X macro / 预处理器,Python 靠运行期 setattr,Go 靠运行期反射,Rust 靠 Serde 派生宏。演讲的评价是:这些都很强,但等于「再学一套系统」;Zig 只是多写了两个关键字,其余全是普通 Zig 代码。
11 SIMD:向量只是一种类型
SIMD(Single Instruction Multiple Data)用一条 CPU 指令对一组数做同样的运算。别的语言往往要引库、写 intrinsic、处理平台差异;Zig 里它是一个类型。
const std = @import("std");
pub fn main() void {
// SIMD 在 Zig 里就是「一种类型」
const a: @Vector(4, u32) = .{ 1, 2, 3, 4 };
const b: @Vector(4, u32) = .{ 10, 20, 30, 40 };
const sum = a + b; // 一条 CPU 指令完成 4 组加法
std.debug.print("a + b = {any}\n", .{sum});
std.debug.print("reduce = {d}\n", .{@reduce(.Add, sum)});
}
0.17.1 实测通过
输出
a + b = { 11, 22, 33, 44 }与reduce = 110。
过时提醒 · 0.17 已移除
想批量造重复数组时,老写法
"-" ** 5已失效(0.17.1 实测报错:error: binary operator '*' has whitespace on one side, but not the other,报错信息完全不提**)。0.17 用const dashes: [5]u8 = @splat('-');。++数组拼接不受影响。
演讲还顺带提了没展开的特性:packed struct(嵌入式)、WebAssembly 目标、以及某些场景能生成比 C 更快的代码。
12 重点:0.17 过时语法与内容总清单
这一章是给「照着视频/旧教程抄代码」的人准备的。所有标注 实测 的报错,都用本机 Zig 0.17.1 编译得到。
12.1 视频与幻灯片里直接出现的过时内容
| # | 视频中的写法 / 说法 | 0.17 事实 | 0.17.1 实测结果 |
|---|---|---|---|
| 1 | GPA、std.heap.GeneralPurposeAllocator | 改叫 std.heap.SafeAllocator,构造为 .init(backing, .{}) | error: struct 'heap' has no member named 'GeneralPurposeAllocator' |
| 2 | ArrayList(T).init(gpa)、append(x)、deinit() | 非托管:.empty、append(gpa, x)、deinit(gpa) | error: struct 'array_list.Aligned(u8,null)' has no member named 'init' |
| 3 | @typeInfo(T).@"struct".fields | 平行数组 field_names / field_types / field_attrs | error: no field named 'fields' in struct 'lang.Type.Struct' |
| 4 | 问答里「以前可以直接 import C」 | @cImport / @cInclude / @cDefine / @cUndef 全部移除,改用外部 translate-c 包或 b.addTranslateC | error: invalid builtin function: '@cImport' |
| 5 | ReleaseFast / Debug 等构建模式叫法 | std.lang.Optimize:.debug / .safe / .fast / .small;读 builtin.optimize | error: no field named 'Debug' in enum 'lang.Optimize' |
| 6 | 老教程配套的 std.io.getStdOut().writer() | std.Io.File.stdout().writerStreaming(init.io, &buf),写完 flush() | error: struct 'std' has no member named 'io' |
| 7 | errdefer |err| | 捕获移除,改 catch |err| { ...; return err; } | error: expected block or expression, found '|' |
| 8 | "-" ** 5 | const dashes: [5]u8 = @splat('-') | error: binary operator '*' has whitespace on one side, but not the other |
| 9 | {} 触发自定义 format | 自定义格式化用 {f},方法签名改为 format(self, writer: *std.Io.Writer);{t} 打印枚举/错误名 | 行为变化,不一定报错 |
| 10 | 「测试分配器会告诉你泄漏了」 | 0.17 的 SafeAllocator 会记录泄漏日志,但 zig test 仍可能显示 All 1 tests passed | 实测 1 errors were logged. |
| 11 | main() !void + std.debug.print | 仍然合法,官方 0.17 文档仍在用;只是新代码推荐 main(init: std.process.Init) | 编译通过 |
12.2 0.16 → 0.17 的破坏性变更(查漏用)
语言层
- 移除数组重复
**、void{}(改用{})、errdefer |err|、i0(改u0)、internal/link_oncelinkage。 @bitCast改为按逻辑位重解释,涉及 array / vector 时旧代码可能静默出错(见 12.4)。@hasDecl现在只对 public 声明返回 true,不再因「同文件」而改变。- 新增
@backingInt/@fromBackingInt(替代@intFromEnum/@enumFromInt/ 部分@bitCast)、@divCeil、@SpirvType。 packed struct/packed union在布局要紧时需显式写 backing int,如packed struct(u8) { ... }。- C 翻译从编译器移到外部包;语法被正式规范化并加入模糊测试。
标准库
| 旧 | 新 |
|---|---|
std.builtin.* | std.lang.*(旧名暂为弃用别名) |
std.builtin.OptimizeMode、.ReleaseFast | std.lang.Optimize、.fast |
builtin.mode / builtin.os.tag | builtin.optimize / builtin.target.os.tag |
std.gpu | std.spirv(无别名) |
info.fields[i].name / .type | info.field_names[i] / info.field_types[i] / info.field_attrs[i] |
std.meta.fields / Int / Tuple | @typeInfo / @Int / @Tuple |
std.fmt.allocPrint(gpa, ...) | gpa.print(...) |
std.fmt.bufPrint(&buf, ...) | std.mem.print(&buf, ...) |
std.fmt.bufPrintZ / gpa.dupeZ | std.mem.printSentinel / gpa.dupeSentinel |
DebugAllocator(.{}) | SafeAllocator;deinit() 返回泄漏数而非 .ok / .leak |
std.heap.stackFallback | std.heap.BufferFirstAllocator(无别名) |
ArrayList.getLast() / getLastOrNull() | last()(返回 ?T) |
bit_set.initEmpty() / initFull() | .empty / .full;StaticBitSet → std.bit_set.Static |
std.ascii.indexOfIgnoreCase | std.ascii.findIgnoreCase |
std.Io.File.OpenFlags / CreateFlags | std.Io.Dir.OpenFileOptions / CreateFileOptions |
std.mem.writePackedIntNative | std.mem.writePackedInt(..., .native) |
std.bit_set.Integer.initEmpty 等 | .empty;std.EnumSet 同样移除 initEmpty |
std.zon.parse、Uri / net.HostName | 均被重构 / 解耦 |
另外:0.17 给 ArrayList 增加了 lockPointers() / unlockPointers(),持有内部元素指针时可让失效操作直接断言;SafeAllocator 引入;std.zon.parse 重做。
构建系统(0.17 改动最大的地方)
zig build拆成 configurer(执行 build.zig)与 maker(执行构建图)两个进程,引入 Build Server Protocol;这也导致 ZLS 在 0.17.0 上暂时不可用。b.args移除 →run_cmd.addPassthruArgs()。b.build_root/install_path/install_prefix/cache_root/pathFromRoot()/getInstallPath()移除 →b.root;verbose、release_mode等移到b.graph。- 自定义
makeFn步骤移除 → 写成小程序 +b.addExecutable+b.addRunArtifact。 - 重命名:
b.lazyDependency→b.dependencyLazy、b.runAllowFail→b.runFallible、一批add*Arg→add*Arg2(带.prefix选项)。 zig build不再接受--global-cache-dir、--zig-lib-dir、--build-runner;--zig-lib=<path>替代--zig-lib-dir。- 新增
zig fmt --complexity、zig fmt --upgrade;增量编译用zig build -fincremental。
过时提醒 · 结论修正
视频问答里说「0.16 → 0.17 的变化不大,不是翻天覆地」。对应用层代码大致成立(
std.json、std.process.Init、std.Io.Dir、File 的 reader/writer 都没变);但对构建脚本不成立:0.16 项目用zig init生成的build.zig在 0.17 会先于你的代码编译失败。升级时请先改build.zig,再谈业务代码。
12.3 仍能编译、但已弃用(最容易埋雷)
0.17.1 实测,下面这些旧名字编译完全通过、没有任何警告:std.fmt.bufPrint、std.fmt.allocPrint、std.mem.indexOfScalar、std.heap.DebugAllocator、std.builtin、builtin.mode、switch 里的 .Debug / .ReleaseFast prong、ArrayList.getLast()、std.StaticBitSet 等。
它们在标准库里是带 Deprecated 标记的别名,教程照抄旧名也不会被工具提醒。新代码请直接写 12.2 右栏的新名字。
12.4 静默行为变化(编译器不救你)
| 变更 | 风险 |
|---|---|
@bitCast 对 array / vector 改为逻辑位语义 | 依赖字节序的旧代码可能算错,且没有编译错误。全局搜 @bitCast 人工复核 |
std.mem.containsAtLeastScalar 末两参数顺序反转 | 0.16 是 (count, element),0.17 是 (element, count);两个都是整数,类型正确、结果相反,无警告 |
std.testing.allocator 泄漏检测 | 0.17 仅记录 error log,测试仍可显示通过;CI 需检查日志或断言 deinit() == 0 |
@hasDecl 只认 public 声明 | 同文件内的私有声明现在返回 false |
ArrayList.setKey 不再重算索引 | 性能提升,但依赖旧副作用的逻辑要复核 |
12.5 升级操作清单
- 先跑
zig fmt(或zig fmt --upgrade),它会修掉一大部分机械重命名。 - 改
build.zig:b.args→addPassthruArgs()、路径字段 →b.root、自定义makeFn→ 外部小程序;检查 CI 脚本里的旧 flag。 - 全局搜索:
@cImport、**、errdefer |、void{}、i0、.fields[、@bitCast、containsAtLeastScalar、GeneralPurposeAllocator、std.io。 - 把弃用别名批量替换成 12.2 的新名字。
- 若依赖 ZLS(编辑器补全/跳转),0.17.0 上暂不可用,先用「命令行诊断 +
zig fmt+ 语法高亮」过渡,等 ZLS 支持 Build Server Protocol 后再升级编辑器链。
13 练习与自测
先自己答,再对要点。带星号的是版本陷阱题。
A = B + C在 Zig 里为什么没有歧义?至少说出三种其他语言可能隐藏的行为。!u16和?u16分别解决什么问题?各自配套哪些关键字?- 把第 04 章的
findAdults从SafeAllocator换成ArenaAllocator,需要改动几处代码? - 0.17 为什么把 allocator 从
ArrayList里拿出来,改成每次调用都传? - 写一个
parsePort,要求port=0返回自定义错误,并用穷尽switch处理所有错误。 -
- 0.17 里怎么取结构体的字段名与字段类型?为什么幻灯片里的
.fields不行?
- 0.17 里怎么取结构体的字段名与字段类型?为什么幻灯片里的
inline for和普通for有什么不同?为什么@field的字段名必须是编译期已知?- 标签联合比「数据 + kind 变量」好在哪?
@tagName能省掉什么? - 三名字两年龄一起
for,0.17 会怎样?C / Python / Rust 分别会怎样? defer/errdefer与 Go 的defer在作用域上有什么差别?-
- 说出五个 0.17 已移除或改名的写法,并给出新写法。
-
- 哪几类过时写法编译器不会给任何提示?升级项目时怎么排查?
std.debug.print和std.Io.Writer各适合什么场景?为什么 writer 需要flush()?@Vector为什么说是「SIMD 只是一种类型」?@splat替代了什么旧语法?
答案要点
- 没有运算符重载、没有属性 getter、没有 magic 回调、没有异常跳转、没有按上下文改变的操作;「看起来不像函数调用,就不会调用函数」。
!T是错误联合,配try/catch/error;?T是可选值,配orelse/if (x) |v|/null。- 一处都不用改函数本身,只需在调用处换 allocator 参数;这正是演讲的核心论点。
- 让每一次可能分配内存的调用都在代码里可见,符合「没有隐式分配」,也便于同一容器混用不同分配策略。
- 见第 06 章;漏掉
error.Overflow或error.InvalidCharacter任一分支都会编译失败。 const info = @typeInfo(T).@"struct";后用info.field_names/info.field_types平行数组,inline for同时迭代;0.17 移除了.fields。inline for编译期展开,循环变量是comptime;@field要求字段名编译期已知,因此必须展开。- tag 由编译器维护,新增变体会触发穷尽检查;
@tagName可直接取标签名,不必为每个分支再写一遍字符串。 - 0.17 编译期已知长度就编译失败,运行期才知道则 panic;C 越界读垃圾,Python/Rust
zip静默截断。 - Zig 是当前作用域,Go 是整个函数;
errdefer只在错误返回路径执行。 - 见 12.1 表格,任取五条(GPA、ArrayList.init、
.fields、@cImport、std.io、**、errdefer |err|、.Debug等)。 - 弃用别名(
bufPrint/indexOfScalar/DebugAllocator…)与静默行为变化(@bitCast、containsAtLeastScalar参数顺序、测试泄漏只记日志);靠全局搜索 + 12.5 清单人工审查。 std.debug.print用于诊断、不需要io;正式输出走std.Io.Writer,缓冲区由调用者提供,所以必须flush()。@Vector(4, u32)直接相加即一条 SIMD 指令;@splat取代了被移除的**数组重复语法。
14 延伸资源
| 资源 | 地址 | 说明 |
|---|---|---|
| 官方学习页 | ziglang.org/learn | 演讲首推入口 |
| Zig 0.17.0 语言参考 | ziglang.org/documentation/0.17.0 | 篇幅不大,一天能读完 |
| 0.17.0 Release Notes | ziglang.org/download/0.17.0/release-notes.html | 本手册 12.2 的主要依据 |
| 命令行自带 | zig zen、zig std | 前者打印设计箴言,后者在浏览器打开标准库文档 |
| Ziglings 练习 | codeberg.org/ziglings/ziglings | 演讲强烈推荐:编译报错即题目,修好进入下一关 |
| Ziggit 论坛 | ziggit.dev | 非新手专区,但提问质量很高;先读社区规则 |
| 旧版本迁移对照 | ziglang.in · Migrate from an Older Zig | 0.15/0.16 大变更(writer、Io、非托管容器) |
| 0.16 → 0.17 变更 | ziglang.in · What Changed in Zig 0.17 | 逐条带可运行代码 |
| 演讲页 | zig.code-maven.com | 主办方页面 |
| 本视频 | B 站 BV1qB4p6fE7g / 原视频 | 中文配音 / 英文原声 |
| B 站合集《Zig 编程语言》 | myfreax 的合集(47 集) | 第二部分 12 讲的出处,完整索引见附录 D |
PART II · 专题深化 · 从「知道设计哲学」到「会做工程决策」
第一部分回答「Zig 为什么这样设计」;第二部分回答「真写程序时该选什么、会踩什么坑」。依据 B 站《Zig 编程语言》合集中的 12 讲视频,按教材体例重写:每章含学习目标、原理、0.17.1 实测代码、陷阱清单与小结。
第二部分导学:课程地图与学习路径
这 12 讲不是 12 个孤立知识点,而是三条互相咬合的线:内存从哪来、数据怎么摆、系统怎么跑。把它们和第一部分的设计原则对上,才算真正读懂 Zig。
导学.1 版本基线:视频讲 0.16,本手册写 0.17
12 讲里有 8 讲标题明确标注 0.16.0(Ziggurat 的「分配器与数据结构」系列),其余是 2025—2026 年的大会演讲与专题。第一部分的第 12 章已经系统梳理过 0.16 → 0.17 的破坏性变更;本部分采取同样的原则:
- 不照抄视频代码。所有示例用本机 Zig 0.17.1 重写,逐段编译运行通过;输出的数值、报错、容量增长都是真实结果,不是示意。
- 差异显式标注。凡视频里的 0.16 写法在 0.17 已改名 / 移除 / 行为变化,用「过时提醒」或「版本对照」标出,并在附录 E汇总成速查表。
- 概念与 API 分开。分配器的心智模型、AoS/SoA 布局、函数颜色、DAG 构建图这些是不随版本变的思想;具体函数名会变,把两层分开记,升级时才不会全盘重学。
阅读约定
标注「0.17.1 实测通过」的代码块都是完整独立程序(含
@import("std")与main),保存为.zig后zig run 文件名.zig即可复现;第 26 章的构建脚本是三文件小项目,需按目录结构保存。
导学.2 12 讲 → 12 章课程地图
| 讲 | 视频主题(B 站) | 本手册章节 | 要回答的核心问题 |
|---|---|---|---|
| 1 | Allocator 的本质与核心心智模型 | 15 | 为什么看函数签名就能知道它是否分配内存? |
| 2 | DebugAllocator:捕获泄漏和双重释放 | 16 | 怎么让内存错误在开发期自己跳出来? |
| 3 | ArenaAllocator:一次性释放所有内存 | 17 | 大量小对象同生共死时,能否不逐个 free? |
| 4 | FixedBufferAllocator 与 MemoryPool | 18 | 内存上限已知、或对象反复生灭时怎么做到零堆开销? |
| 5 | ArrayList:会增长的列表 | 19 | 增长时数据会搬家吗?指针什么时候失效? |
| 6 | HashMap 及其相关功能 | 20 | 谁拥有 key 指向的内存?什么时候要保序? |
| 7 | MultiArrayList:one array per field | 21 | 为什么换一种内存布局就能快? |
| 8 | EnumArray / EnumMap / EnumSet | 22 | 键是编译期已知的枚举时,能不能完全不分配? |
| — | (前 8 讲综合) | 23 | 把分配器与容器组合成一张可执行的选型决策树 |
| 9–10 | Async 的故事 / 创始人深解 Async I/O | 24 | 为什么 Zig 删掉了 async 关键字,又把 I/O 变成参数? |
| 11 | Zig + SIMD 极致性能 CSV 解析器 | 25 | 零分配流式 + 向量化如何把 20 分钟压到 7 秒? |
| 12 | 构建系统:DAG 与跨平台编译 | 26 | build.zig 到底在描述什么?怎么交叉编译? |
导学.3 三条学习路径
| 路径 | 章节顺序 | 适合谁 | 学完应能做到 |
|---|---|---|---|
| 内存线 | 15 → 16 → 17 → 18 | 刚从 GC 语言转来、被 ownership 困扰的人 | 读懂任意函数签名的内存含义,按生命周期挑分配器,并写出能自动抓泄漏的测试 |
| 数据线 | 19 → 20 → 21 → 22 → 23 | 要写解析器、服务端、游戏循环的人 | 在 ArrayList / HashMap / SoA / 枚举集合之间按访问模式选型,而不是凭习惯 |
| 系统线 | 24 → 25 → 26 | 关注吞吐、并发与交付的人 | 理解显式 Io 与取消模型,写出向量化热路径,用 DAG 组织多目标构建 |
与第一部分呼应
第 02 章说「没有隐式内存分配」、第 04 章说「Allocator 是参数」。第二部分把这些原则反过来用:既然分配器是参数,那么换分配器就是在换程序的成本结构;既然没有隐藏控制流,那么 I/O 与并发也必须像 allocator 一样显式传进来(第 24 章)。整门课是同一套哲学在不同尺度上的展开。
15 Allocator 心智模型:一个状态指针 + 一张函数表
对应视频《Zig 内存分配:Allocator 分配器的本质与核心心智模型》(BV1nhHA6NE4i)。这一讲的价值不在记 API,而在建立一条读代码的反射:看到 std.mem.Allocator 参数,就知道「这里会向系统要内存」;没看到,就知道「这里不会」。
学习目标
- 能解释
Allocator的数据结构本质,以及为什么它不需要语言运行时支持- 区分
alloc / free与create / destroy两对操作- 能写出「同一段逻辑、三种分配策略」的程序,并说明切换代价为零的原因
15.1 从函数签名读内存行为
| 函数签名 | 你能立刻推出什么 |
|---|---|
fn parse(s: []const u8) !Config | 不分配堆内存;返回值要么在栈上、要么借用输入切片;失败只可能是解析错误,不会是 OutOfMemory |
fn parse(gpa: Allocator, s: []const u8) !Config | 可能分配;错误集合里可能含 error.OutOfMemory;调用者可以决定用哪种策略 |
fn render(io: Io, w: *Writer) !void | 可能做阻塞 I/O;0.16 起 I/O 能力与 allocator 一样是显式参数(第 24 章) |
这条规则的价值在于可组合性:一个不分配的函数可以被安全地放进热循环、放进嵌入式环境、放进信号处理路径;一个接受 allocator 的函数则把所有策略决定权上交给了调用者。第 04 章那句「没有 allocator 参数,本身也是信息」到这里才真正落地。
15.2 Allocator 的本质:状态指针 + VTable
剥掉标准库的封装,std.mem.Allocator 在 0.17 里就是一个只有两个字段的结构体:
// lib/std/mem/Allocator.zig(0.17.1,字段级简化)
pub const Allocator = struct {
ptr: *anyopaque, // 指向分配器自己的状态
vtable: *const VTable, // 指向一张函数表
pub const VTable = struct {
alloc: *const fn (*anyopaque, len: usize, alignment: Alignment, ra: usize) ?[*]u8,
resize: *const fn (*anyopaque, memory: []u8, alignment: Alignment, new_len: usize, ra: usize) bool,
remap: *const fn (*anyopaque, memory: []u8, alignment: Alignment, new_len: usize, ra: usize) ?[*]u8,
free: *const fn (*anyopaque, memory: []u8, alignment: Alignment, ra: usize) void,
};
};
换句话说,分配器不是语言特性,是一个普通接口。Zig 没有全局堆、没有 new、没有默认 allocator;标准库提供若干实现,你也可以自己写一个(第 16 章的 OOM 注入就是一个)。这解释了三件事:
- 为什么切换策略几乎零成本:只是换了一个「指针 + 函数表」的值。
- 为什么
ArrayList这类容器在 0.15 之后变成非托管:把 allocator 藏在容器里,等于又把分配行为藏起来了。 - 为什么 Zig 能轻松做
freestanding:没有堆的目标,不传 allocator 即可,编译器不会替你偷偷生成 malloc 调用。
| VTable 操作 | 语义 | 失败表现 |
|---|---|---|
alloc | 申请一段指定长度与对齐的内存 | 返回 null → 上层得到 error.OutOfMemory |
resize | 原地扩大 / 缩小;不移动地址 | 返回 false 表示做不到,调用方改走「新分配 + 拷贝 + 释放」 |
remap | 允许移动地址的扩缩容 | 返回 null 表示失败,旧内存仍归调用者 |
free | 归还内存 | 无返回值;传错 allocator / 长度是未定义行为(第 16 章讲解如何抓) |
15.3 两对基本操作与常用方法
| 配对 | 适用对象 | 典型写法 | 易错点 |
|---|---|---|---|
alloc / free | 切片 []T | const xs = try gpa.alloc(u8, n); defer gpa.free(xs); | free 时长度必须与 alloc 一致 |
create / destroy | 单个 T | const p = try gpa.create(T); defer gpa.destroy(p); | destroy 不写长度,但类型必须匹配 |
dupe | 复制切片 | const copy = try gpa.dupe(u8, src); | 返回的是新内存,仍需 free |
dupeSentinel | 复制并加哨兵(0 结尾) | try gpa.dupeSentinel(u8, src, 0) | 0.17 取代 dupeZ(见 12.2) |
下面这段程序把「签名即说明书」和「策略可替换」放在同一个文件里。三处 gpa 的调用完全一样,但底层分别可以是固定缓冲、竞技场或页分配器:
const std = @import("std");
const Point = struct { x: i32, y: i32 };
// 签名里出现 Allocator,等于告诉调用者:这个函数会碰堆内存。
fn makeLine(gpa: std.mem.Allocator, n: usize) ![]Point {
const points = try gpa.alloc(Point, n); // 切片:alloc / free 配对
errdefer gpa.free(points);
for (points, 0..) |*p, i| {
p.* = .{ .x = @intCast(i), .y = @intCast(i * i) };
}
return points;
}
pub fn main() !void {
// 同一套调用代码,换掉 allocator 就换掉了整套内存策略。
var backing: [4096]u8 = undefined;
var fba: std.heap.FixedBufferAllocator = .init(&backing);
const gpa = fba.allocator();
const line = try makeLine(gpa, 3);
defer gpa.free(line);
const origin = try gpa.create(Point); // 单对象:create / destroy 配对
defer gpa.destroy(origin);
origin.* = .{ .x = 0, .y = 0 };
std.debug.print("len={d} last=({d},{d}) origin=({d},{d})\n", .{
line.len, line[2].x, line[2].y, origin.x, origin.y,
});
}
0.17.1 实测通过
输出
len=3 last=(2,4) origin=(0,0)。把fba.allocator()换成arena.allocator()或std.heap.page_allocator,makeLine一个字都不用改。
15.4 主函数里的内置分配器
0.16 起 main 可以接收 std.process.Init,运行期把三样东西交给你:init.gpa(带调试期泄漏检测的通用分配器)、init.arena(进程级竞技场,退出自动清理)、init.io(I/O 与并发能力)。0.17 保持了同样的结构,只是把环境变量与参数收进了 init.minimal。
原文补正 · 0.17 字段路径
第 00 章提到「
init.environ、init.args也在其中」。精确的 0.17.1 路径是init.environ_map与init.minimal.args/init.minimal.environ;init.gpa、init.arena、init.io三个字段本身保持不变。
视频说「你其实已经拥有一个 arena」,指的就是 init.arena:写一次性 CLI 时,把中间结果全挂上去,连 deinit 都不用写。第 17 章会展开它的适用边界。
15.5 陷阱清单
| 陷阱 | 后果 | 做法 |
|---|---|---|
| 用 A 分配、用 B 释放 | 未定义行为;安全分配器能抓到一部分 | 让 allocator 跟着数据走,或统一用一个 allocator |
忽略 OutOfMemory | 错误被 catch 吞掉后拿到脏数据 | try 向上冒泡;用 errdefer 清理半成品 |
| 把短命内存放进长命容器 | 悬空指针 | 需要长期持有时 dupe 一份(第 20 章) |
| 误以为对齐无关紧要 | SIMD / 原子操作在某些目标上崩溃 | 用 alignedAlloc,或让 create(T) 自动按 @alignOf(T) 处理 |
小结 Allocator 是一个值,不是全局状态。它把「内存策略」变成普通参数,于是函数签名成了成本说明书,切换策略无需改实现,没有堆的环境也能编译。第 16—18 章分别讲「怎么抓错」「怎么批量释放」「怎么完全不用堆」,都是这一模型的推论。
16 安全分配器:把内存错误变成可读报告
对应视频《Zig DebugAllocator: 捕获泄漏和双重释放 (0.16.0)》(BV1eDnd6ME4X)。核心主张:内存错误之所以难查,是因为错误发生在 A 处、症状出现在 B 处;调试分配器的职责是把两者用一份带栈轨迹的报告连起来。
学习目标
- 能区分四类内存错误,并说出 Zig 分别用什么机制暴露它们
- 会读 0.17 的泄漏报告,定位到具体行号
- 会用 OOM 注入验证错误路径,而不是祈祷线上不出错
16.1 四类内存错误与检测手段
| 错误 | C / 手工管理的典型症状 | Zig 调试期如何暴露 |
|---|---|---|
| 内存泄漏 leak | RSS 缓慢上涨,几小时后才 OOM | SafeAllocator.deinit() 打印分配栈并返回泄漏数量 |
| 双重释放 double free | 堆结构损坏,随机崩溃 | 分配器维护分配元数据,第二次 free 打印「分配 trace + 两次释放 trace」 |
| 释放后使用 UAF / 越界写 | 数据静默损坏,最难复现 | canary、释放后填充、check_write_after_free;Release 下靠边界检查 |
| 内存耗尽 OOM | 错误路径几乎从没被执行过,一执行就崩 | std.testing.FailingAllocator 按次数注入失败(16.3) |
16.2 0.17 的名字是 SafeAllocator
过时提醒 · 0.17 已改名
视频在 0.16 里用
std.heap.DebugAllocator(.{...})(更老的资料叫GeneralPurposeAllocator/ GPA)。0.17 的正式名字是std.heap.SafeAllocator,构造方式为.init(backing, .{});DebugAllocator只是弃用别名。deinit()在 0.16 返回std.heap.Check.ok / .leak,0.17 直接返回泄漏个数usize。
0.17 的 SafeAllocator.Options 主要字段:stack_trace_frames(默认调试构建 7 帧)、check_write_after_free、canary、以及两个桶大小对数。注意它不再提供 0.16 的 enable_memory_limit / requested_memory_limit——想测 OOM 要走 16.3 的注入路线。
const std = @import("std");
pub fn main() !void {
// 0.17:SafeAllocator.init(底层分配器, 选项),deinit() 返回泄漏数量。
var safe: std.heap.SafeAllocator = .init(std.heap.page_allocator, .{});
defer std.debug.print("leak count = {d}\n", .{safe.deinit()});
const a = safe.allocator();
const leaked = try a.alloc(u8, 24);
leaked[0] = 'Z'; // 故意不 free:deinit 会打印分配栈
const ok = try a.alloc(u8, 8);
defer a.free(ok);
std.debug.print("allocated: {d} + {d} bytes\n", .{ leaked.len, ok.len });
}
在 0.17.1 上实际运行,先打印正常输出,然后 deinit() 给出下面这份报告(节选,路径已省略目录):
allocated: 24 + 8 bytes
error(SafeAllocator): leaked [addr: 258e3e00010, len: 24 (0x18) align: 1] allocated at:
02_safe_allocator.zig:9:31: 0x7ff7a7a18b61 in main
const leaked = try a.alloc(u8, 24);
^
... lib/std/start.zig:788: ... in callMain
leak count = 1
| 报告字段 | 怎么读 |
|---|---|
addr / len / align | 泄漏块的地址、请求长度、对齐要求;len 帮你反推是哪类对象 |
allocated at: | 分配点的栈轨迹,第一行通常就是你要找的源码行(示例中为第 9 行 a.alloc(u8, 24)) |
leak count = 1 | deinit() 的返回值;CI 里断言 == 0 比看日志可靠 |
过时提醒 · 静默行为变化
呼应第 12.4 章:0.17 的
std.testing.allocator底层也是SafeAllocator,泄漏只记一条error(SafeAllocator)日志,zig test仍可能显示通过并返回 0。CI 必须检查日志,或在代码里断言deinit() == 0;仅凭退出码判断会漏掉泄漏。
16.3 OOM 注入:把「不可能」变成可测试
视频在 0.16 用 DebugAllocatorConfig 的 requested_memory_limit 主动耗尽预算。0.17 里更干净的做法是 std.testing.FailingAllocator:它按「第 N 次分配」精确注入失败,且能覆盖 resize 失败,不需要真的吃掉几个 GB 内存。
const std = @import("std");
// 用「第 N 次分配必定失败」来逼出错误处理路径,而不必真的耗尽内存。
fn loadConfig(gpa: std.mem.Allocator) !void {
const header = try gpa.alloc(u8, 16);
defer gpa.free(header);
const table = try gpa.alloc(u8, 256); // 第 2 次分配被注入失败
defer gpa.free(table);
std.debug.print("loaded {d} bytes\n", .{header.len + table.len});
}
pub fn main() !void {
var failing: std.testing.FailingAllocator = .init(std.heap.page_allocator, .{
.fail_index = 1, // 只允许成功 1 次
});
loadConfig(failing.allocator()) catch |err| {
std.debug.print("injected failure: {t}\n", .{err});
};
}
0.17.1 实测通过
输出
injected failure: OutOfMemory。注意defer gpa.free(header)在错误路径上依然执行——这正是defer相对errdefer的适用场景:只要申请成功就必须回收。
把 fail_index 从 0 扫到 N,可以系统性地验证「任意一次分配失败时,函数是否都不泄漏、不留半成品」。标准库自身就用这个思路做容器的失败注入测试,这是系统级代码里性价比极高的一类测试。
16.4 开发期与发布期的权衡
| 维度 | Debug / 开发期 | Release / 发布期 |
|---|---|---|
| 分配器 | SafeAllocator / init.gpa(调试模式自带检查) | page_allocator、smp_allocator、arena 或自定义池 |
| 开销 | 每次分配记元数据、抓栈、加 canary;明显变慢、内存放大 | 接近裸 malloc / bump |
| 安全检查 | 边界检查、整数溢出检查保留 | -Doptimize=fast / small 会移除大部分运行时检查 |
| 推荐做法 | 单元测试 + CI 全量开启,断言无泄漏 | 保留少量抽样监控;不要把调试分配器带上线 |
0.17 里 std.heap.smp_allocator 是面向多线程的通用分配器;SafeAllocator 本身是线程安全的(内部按线程分片 + 锁),但它的价值在诊断,不在吞吐。
小结 调试分配器把「看不见的内存错误」变成「带文件名和行号的结构化报告」。0.17 的三点变化必须记牢:名字改叫
SafeAllocator、deinit()返回数量、预算限制改由失败注入器负责。配合defer/errdefer(第 09 章),错误路径也能收得干净。
17 ArenaAllocator:生命周期与批量释放
对应视频《Zig ArenaAllocator:一次性释放所有内存 (0.16.0)》(BV14Tno64EwS)。一句话概括它的哲学:分配时随意,释放时一锅端。代价是「所有对象的生命周期必须一致」——这条约束一旦被破坏,就是悬空指针。
学习目标
- 能用 bump pointer 模型解释 arena 为什么快
- 识别「过早释放」与「把长命对象放进短命 arena」两类陷阱
- 掌握服务器主循环里的
reset(.retain_capacity)模式
17.1 Bump pointer 模型
Arena 向底层分配器申请大块内存(chunk),之后每次 alloc 只做一件事:把游标往前推 len 字节并返回旧地址。没有空闲链表、没有合并、没有锁竞争;对齐只是把游标向上取整。
| 操作 | 通用分配器 | ArenaAllocator |
|---|---|---|
| 分配 | 查空闲块 / 桶 / 锁 / 元数据 | 一次加法 + 边界判断 |
| 单个 free | 归还并可能合并 | 什么也不做(只有末尾分配可能被回退) |
| 整体释放 | 逐个归还 | deinit() 把 chunk 链表整体还给底层 |
| 内存峰值 | 接近实际用量 | 可能偏高;大量短命临时对象会一直占到 reset |
所以 arena 不是「更快的 malloc」,而是把 N 次释放压缩成 1 次。它最适合的形状是「一批对象同生共死」:一次编译任务、一次 HTTP 请求、一帧游戏渲染、一次 CLI 执行。第 15.4 节的 init.arena 是进程级版本——整个程序就是一个批次。
17.2 生命周期陷阱:过早释放与长命对象
头号陷阱 · 悬空指针
视频专门用一章讲「过早释放」:
arena.deinit()或reset()之后,所有从它拿到的切片、字符串、容器都立即失效,而编译器不会报错——它们仍是指向合法地址的普通指针。典型事故:把请求级 arena 里构造的字符串存进全局缓存。规则是:凡是要活得比 arena 久的数据,必须复制到别的分配器上(dupe到init.gpa或长命 allocator)。
| 反模式 | 症状 | 修正 |
|---|---|---|
每轮循环 defer arena.deinit(),却把结果返回给上一轮 | 读到随机字节 / 崩溃点飘忽 | 把 arena 建在循环外,用 reset 而不是反复 init/deinit |
| 把 arena 内存塞进长命 HashMap | 第一次 reset 后键全变垃圾 | 键 dupe 到长命分配器(第 20 章) |
| 在 arena 上放需要单独销毁的资源(文件句柄、锁) | 析构逻辑被跳过 | 这类资源用 defer 显式关闭,arena 只管纯内存 |
| 长时间运行的循环从不 reset | 内存单调上涨,看起来像泄漏 | 每轮开头 reset |
17.3 reset 的三种模式与服务器主循环
0.17 的 ArenaAllocator.ResetMode 有三个变体:
| 模式 | 行为 | 适用 |
|---|---|---|
.free_all | 把所有 chunk 还给底层,下次从头再来 | 批次结束后很久才会再来下一批;最省内存 |
.retain_capacity | 保留一块足够容纳上一轮峰值的缓冲 | 服务器循环:预热之后几乎不再调用底层分配器 |
.retain_with_limit: usize | 同上,但超过上限就收缩 | 流量波动大、担心偶发大请求把内存钉死 |
reset() 返回 bool:表示「预热是否成功」。失败时 arena 仍然可用,只是下一轮分配会变慢,因此通常不必让它中断业务。关键位置是每轮开头,这样上一轮的结果在整轮处理期间都有效:
const std = @import("std");
fn handleRequest(a: std.mem.Allocator, id: usize) !usize {
// 一次请求里的所有临时对象都挂在 arena 上,不需要逐个 free。
const buf = try a.alloc(u8, 512 * id);
buf[0] = 'x';
const label = try a.dupe(u8, "request");
_ = label;
return buf.len;
}
pub fn main() !void {
var arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator);
defer arena.deinit();
for (1..4) |id| {
// 关键:每轮开头 reset,而不是每轮结尾。否则下一轮会用到已释放的内存。
_ = arena.reset(.retain_capacity); // 保留已申请的大块,下一轮零系统调用
const n = try handleRequest(arena.allocator(), id);
std.debug.print("req {d}: {d} bytes, arena capacity {d}\n", .{
id, n, arena.queryCapacity(),
});
}
}
0.17.1 实测通过
输出:
req 1: 512 bytes, arena capacity 806→req 2: 1024 bytes, arena capacity 2062→req 3: 1536 bytes, arena capacity 2062。第三轮容量没有再涨,说明retain_capacity复用了预热好的大块,这正是循环里想要的稳态。
把 defer arena.deinit() 写在循环外、reset 写在循环内,是 Zig 服务端代码的高频惯用法。它与第 09 章的 defer 作用域规则是同一套思维:清理动作放在拥有它的那个作用域。
17.4 什么时候不用 Arena
- 对象生命周期参差:长连接里每个会话各自创建/销毁,用池或通用分配器更合适。
- 需要频繁单独释放大对象:arena 不会真的归还,内存峰值会持续偏高。
- 多线程共享写入:普通
ArenaAllocator.allocator()不是线程安全的;0.17 可用std.heap.smp_allocator作底层,或每个线程一个 arena。 - 内存上限严格(嵌入式):改用第 18 章的
FixedBufferAllocator,越界会明确返回OutOfMemory而不是继续向 OS 要。
小结 Arena 用「放弃单独释放」换取极快的分配和一次性的清理。它的正确性完全建立在生命周期一致这个前提上;
reset(.retain_capacity)让这个模型可以安全地用在长期运行的循环里。下一章把这个思路再推一步:连底层分配器都不用了。
18 FixedBufferAllocator 与 MemoryPool:零堆分配
对应视频《Zig FixedBufferAllocator 与 MemoryPool (0.16.0)》(BV1mNno6ZEGy)。这一讲给出两个「把内存上限握在自己手里」的工具,以及它们的组合拳:绝对不碰堆。
学习目标
- 能解释 FBA 的「栈上 bump + 不真正 free」语义与失败行为
- 理解 MemoryPool 的空闲链表复用,以及它适合的对象形状
- 能把两者叠加,写出零堆分配、内存占用可静态计算的程序
18.1 两种内存形态
| 堆(heap) | 你拥有的缓冲区(栈 / 静态区 / mmap 好的块) | |
|---|---|---|
| 谁决定上限 | 操作系统 / 运行时 | 你,编译期就写死 |
| 失败方式 | OutOfMemory,且时机不可预测 | OutOfMemory,可精确测试 |
| 系统调用 | 可能需要 | 零 |
| 可复现性 | 受其他进程影响 | 完全一致,适合实时系统 / 嵌入式 / 游戏主循环 |
FixedBufferAllocator(FBA)就是「你拥有的缓冲区」的适配器:.init(&buf) 之后按 bump 分配,end_index 记录已用字节。它的 free 只在「释放的正好是最后一块」时能回退游标,其余情况不会真的回收——所以它和 arena 一样,适合批量生命周期,不适合反复单独申请释放。
0.17 补充
0.17 把旧教程里的
std.heap.stackFallback换成了std.heap.BufferFirstAllocator(见 12.2):先用固定缓冲,用满后回退到另一个 allocator。它其实就是本节的组合思想在标准库里的成品。
18.2 MemoryPool:同构对象的槽位复用
粒子、网络连接、AST 节点这类对象有两个特征:类型完全相同、创建销毁极其频繁。通用分配器每次都要走一遍尺寸分类与元数据,而池的做法是:预先切好等大的槽位,用一条空闲链表串起来;create 从链表头摘一个,destroy 把它塞回去。分配与释放都是 O(1),且天然避免碎片。
版本对照 · 0.16 → 0.17
0.16 的
std.heap.MemoryPool(T)已经是非托管的(.empty+create(gpa)),但仍保留一个标了 Deprecated 的Managed包装(init(gpa)+create());0.17 把Managed/toManaged彻底删除了。视频里强调的「0.16 MemoryPool API 更新、要优雅地传参」,指的就是这次向非托管的转变。
18.3 组合:把池叠在固定缓冲上
MemoryPool 自己也需要一个 allocator 来扩充槽位。把它接到 FBA 上,整条链路就完全落在你给的那块栈内存里:没有 malloc、没有系统调用、内存上限在编译期可见。
const std = @import("std");
const Particle = struct { x: f32, y: f32, life: u8 };
pub fn main() !void {
// 1) 完全不碰堆:栈上 8 KiB 就是整个「堆」。
var backing: [8192]u8 = undefined;
var fba: std.heap.FixedBufferAllocator = .init(&backing);
const a = fba.allocator();
// 2) 对象池叠在 FixedBufferAllocator 上:回收的槽位直接复用。
var pool: std.heap.MemoryPool(Particle) = .empty;
defer pool.deinit(a);
const p = try pool.create(a);
p.* = .{ .x = 1.0, .y = 2.0, .life = 3 };
std.debug.print("first: x={d} life={d}\n", .{ p.x, p.life });
pool.destroy(p);
const q = try pool.create(a);
q.* = .{ .x = 9.0, .y = 8.0, .life = 1 };
std.debug.print("reused slot: {} x={d}\n", .{ p == q, q.x });
pool.destroy(q);
std.debug.print("heap bytes used: {d} / {d}\n", .{ fba.end_index, backing.len });
}
0.17.1 实测通过
输出
first: x=1 life=3/reused slot: true x=9/heap bytes used: 90 / 8192。p == q为真,直接证明销毁后的槽位被复用;总占用 90 字节是可静态核算的固定量。
若想连「扩容」都禁掉,用 std.heap.memory_pool.Extra(T, .{ .growable = false }) 配合 initPreheated / addCapacity 预热:池无法再向底层要内存,超额创建直接返回 error.OutOfMemory。这是硬实时系统里最常用的形态。
18.4 分配器选型速查(视频小节的 0.17 修订版)
| 需求 | 选谁 | 关键理由 |
|---|---|---|
| 开发调试、抓泄漏 / 重复释放 | SafeAllocator、init.gpa | 带栈轨迹报告(0.16 叫 DebugAllocator) |
| 大量同生命周期对象、批量释放 | ArenaAllocator | 一次 deinit / reset 收摊 |
| 内存上限已知、禁止堆 | FixedBufferAllocator | 零系统调用,超额可测 |
| 同类对象高频创建销毁 | MemoryPool(T) | 空闲链表 O(1) 复用、无碎片 |
| 先栈后堆的弹性方案 | BufferFirstAllocator | 小对象走缓冲,超出才回退 |
| 多线程通用场景 | smp_allocator / 每线程 arena | 避免共享游标竞争 |
| 直接向 OS 要页 | page_allocator | 每次分配至少一页,只适合大块、长命内存 |
小结 FBA 控制「内存从哪来」,MemoryPool 控制「同类对象怎么复用」,Arena 控制「什么时候统一收摊」——三者可以任意叠加,而且叠加后的接口仍然是那个「指针 + VTable」的
Allocator值。这正是第 15 章模型带来的组合自由度。
19 ArrayList:增长、指针失效与所有权移交
对应视频《Zig ArrayList: 会增长的列表 (0.16.0)》(BV1mMno6dE5i)。「会增长」三个字背后藏着本讲最重要的工程风险:增长可能搬走你的数据。
学习目标
- 说清
len/capacity的关系与几何增长的意义- 识别指针失效场景,会用 0.17 的
lockPointers()把隐患变成断言- 掌握两种删除语义、字符串构建与
toOwnedSlice的所有权移交
19.1 完整生命周期:非托管 API
var list: std.ArrayList(T) = .empty; // 0.15 起不再持有 allocator
defer list.deinit(gpa); // 归还内部缓冲
try list.append(gpa, item); // 每次可能分配都要显式传 gpa
const owned = try list.toOwnedSlice(gpa); // 交出所有权,list 复位为 .empty
defer gpa.free(owned);
从第 04 章起就强调过:把 allocator 从容器里拿出来是刻意的啰嗦。到第 19 章可以更进一步地说——它让「这次 append 会不会触发一次分配」变成一眼可见的事实,也让你能在同一段代码里对前 100 个元素用 arena、对结果用 gpa。
19.2 增长策略与 0.17.1 实测
容量不足时,容器通过 Allocator.VTable.remap 尝试原地扩展;不行就新分配一块更大的缓冲、把旧元素搬过去、释放旧块。扩容倍率由标准库决定,目标是让「追加 n 个元素」的摊还代价为 O(n)。0.17.1 上连续追加 200 个 u32,容量变化为:
const std = @import("std");
pub fn main() !void {
const gpa = std.heap.page_allocator;
var list: std.ArrayList(u32) = .empty;
defer list.deinit(gpa);
// 1) 观察几何增长:容量按策略跳跃,不是每次 +1。
var prev_cap: usize = 0;
for (0..200) |i| {
try list.append(gpa, @intCast(i));
if (list.capacity != prev_cap) {
prev_cap = list.capacity;
std.debug.print("len={d} -> capacity={d}\n", .{ list.items.len, prev_cap });
}
}
list.clearRetainingCapacity();
try list.appendSlice(gpa, &[_]u32{ 0, 1, 2, 3, 4, 5, 6, 7, 8 });
// 2) 扩容会搬移元素:持有内部指针时必须上锁,失效操作会直接断言。
list.lockPointers();
const first = &list.items[0];
std.debug.print("first = {d}\n", .{first.*});
list.unlockPointers();
// 3) 两种删除:orderedRemove 保序 O(n),swapRemove 用末尾元素填洞 O(1)。
const a = list.orderedRemove(0);
const b = list.swapRemove(0);
std.debug.print("removed {d} / {d}, items = {any}\n", .{ a, b, list.items });
// 4) 构建字符串:toOwnedSlice 把缓冲区所有权交给调用者。
var out: std.ArrayList(u8) = .empty;
errdefer out.deinit(gpa);
try out.appendSlice(gpa, "zig ");
try out.append(gpa, '0');
try out.appendSlice(gpa, ".17");
const text = try out.toOwnedSlice(gpa);
defer gpa.free(text);
std.debug.print("text = {s}\n", .{text});
}
0.17.1 实测通过
容量轨迹
33 → 83 → 158 → 270(首块 33,之后约 1.9~2.5 倍增长);后续输出first = 0、removed 0 / 1, items = { 8, 2, 3, 4, 5, 6, 7 }、text = zig 0.17。注意swapRemove(0)把末尾的 8 搬到了开头,顺序被破坏但只花 O(1)。
19.3 指针失效与 lockPointers
只要发生搬移,之前拿到的 &list.items[i]、list.items[0..n] 全部失效。这类 bug 在 C++ 里叫 iterator invalidation,在 Zig 里同样存在,但 0.17 给了主动防御:
| 写法 | 作用 | 代价 |
|---|---|---|
ensureTotalCapacity(gpa, n) | 先预留,之后 n 次 append 保证不搬移 | 一次分配;最推荐的写法 |
lockPointers() | 上锁后,任何会使指针失效的操作直接断言 | 仅调试期;用完 unlockPointers() |
| 存下标而不是指针 | 用 usize 记录位置,取值时再 items[i] | 无额外开销,跨扩容依然正确 |
toOwnedSlice(gpa) | 把缓冲变成独立切片,之后 list 可以销毁 | 所有权转移,别再对原 list 操作 |
易错点
orderedRemove/swapRemove都会让被删位置之后的下标失效,但不涉及重新分配内存。循环里边遍历边删除时,要么倒序遍历,要么收集待删下标再统一处理;第 08 章的多序列for长度检查在这里也帮不上忙。
19.4 构建字符串:谁拥有结果
ArrayList(u8) + appendSlice(gpa, ...) 是标准库里拼字符串的基础手段。收尾有两个选择:toOwnedSlice(gpa) 交出一块归调用者所有的内存(之后必须 gpa.free),或 items 直接借用(list 销毁即失效)。示例里用的是前者,配合 errdefer list.deinit(gpa) 保证中途出错也不泄漏。
如果结果只活到本次请求结束,把它挂在 arena 上、用 list.items 借用即可,连 free 都省了——这就是第 17 章与本章的组合点。
小结 ArrayList 的三大关键词是 容量、失效、所有权:预留容量避免搬移,用
lockPointers/ 下标代替裸指针,用toOwnedSlice明确结果归谁。它也是理解第 20—22 章所有容器的模板:非托管、显式 gpa、内部缓冲可能被搬走。
20 HashMap 家族:键的所有权与顺序
对应视频《Zig HashMap 及其相关功能:通过键查找 (0.16.0)》(BV1bcno6hEQx)。哈希表真正的难点从来不是 put / get,而是两件事:键指向的内存归谁管,以及要不要保持插入顺序。
学习目标
- 用
getOrPut把「查 + 插」合成一次哈希查找- 判断字符串键何时必须
dupe,并写出不泄漏的释放代码- 在 HashMap 与 ArrayHashMap 之间按访问模式选型
20.1 四个家族成员
| 类型(0.17) | 键 / 哈希 | 顺序 | 典型用途 |
|---|---|---|---|
std.AutoHashMap(K, V) | 整数、指针等可按位哈希的键 | 无 | ID → 对象 |
std.StringHashMap(V) | []const u8,按内容哈希 | 无 | 配置、词频 |
std.HashMap(K, V, Ctx, max_load) | 自定义上下文 | 无 | 自定义相等 / 哈希规则 |
std.array_hash_map.String(V) | 字符串,外加一个紧凑索引数组 | 保持插入顺序 | 需要可预测迭代、序列化、稳定输出 |
过时提醒 · 0.17 弃用别名
视频与旧教程常见的
std.StringArrayHashMap/std.ArrayHashMapUnmanaged/std.AutoArrayHashMapUnmanaged在 0.16 与 0.17 都是带 Deprecated 标记的别名,编译无警告。新代码请用std.array_hash_map.String(V)/.Auto(K,V)/.Custom(...);它们都是非托管容器,.empty初始化、put(gpa, ...)、deinit(gpa)。
20.2 getOrPut:一次查找完成计数
词频统计最朴素的写法是 get 一次、没有再 put 一次,等于做两遍哈希。getOrPut 返回一个结果结构,含 found_existing 与 value_ptr:不管键在不在,你都拿到一个可写的槽位。
const std = @import("std");
pub fn main() !void {
const gpa = std.heap.page_allocator;
// 1) getOrPut:一次哈希查找完成「查 + 插入」,避免 get 后再 put 查两遍。
var freq: std.StringHashMapUnmanaged(usize) = .empty;
defer freq.deinit(gpa);
const words = [_][]const u8{ "zig", "allocator", "zig", "simd", "allocator", "zig" };
for (words) |w| {
const gop = try freq.getOrPut(gpa, w);
if (!gop.found_existing) gop.value_ptr.* = 0;
gop.value_ptr.* += 1;
}
std.debug.print("zig={d} allocator={d}\n", .{ freq.get("zig").?, freq.get("allocator").? });
// 2) 键的所有权:键来自临时缓冲区时必须 dupe,否则缓冲区一失效就是悬空指针。
var owned: std.StringHashMapUnmanaged(usize) = .empty;
defer owned.deinit(gpa);
var tmp: [16]u8 = undefined;
const dynamic = try std.mem.print(&tmp, "kv-{d}", .{7});
const key = try gpa.dupe(u8, dynamic);
errdefer gpa.free(key);
try owned.put(gpa, key, 42);
defer gpa.free(key);
std.debug.print("owned[kv-7] = {d}\n", .{owned.get("kv-7").?});
// 3) ArrayHashMap:牺牲一点查找速度,换回稳定的插入顺序。
var ordered: std.array_hash_map.String(usize) = .empty;
defer ordered.deinit(gpa);
try ordered.put(gpa, "first", 1);
try ordered.put(gpa, "second", 2);
try ordered.put(gpa, "third", 3);
for (ordered.keys(), ordered.values()) |k, v| {
std.debug.print("{s}={d} ", .{ k, v });
}
std.debug.print("\n", .{});
}
0.17.1 实测通过
输出
zig=3 allocator=2/owned[kv-7] = 42/first=1 second=2 third=3。最后一行证明ArrayHashMap的迭代顺序与插入顺序一致,而HashMap不保证。
20.3 键的所有权:什么时候必须 dupe
| 键的来源 | 能否直接放进表里 | 原因 |
|---|---|---|
字符串字面量 / static 数据 | 可以 | 生命周期与进程相同 |
| 另一个长命分配器上的切片 | 可以,但要保证它活得比表久 | 本质是借用,需人工维持约束 |
栈上临时缓冲区(std.mem.print 的结果) | 不可以 | 函数返回即失效,之后所有查找读到野内存 |
| 请求级 arena 里的字符串 | 不可以(要长期留存时) | reset 之后全部悬空(第 17 章) |
示例里的处理方式是标准做法:const key = try gpa.dupe(u8, dynamic);,配 errdefer gpa.free(key) 覆盖 put 失败,成功后再用 defer gpa.free(key) 兜底。若表里有大量这类「自己的键」,更系统的写法是在 deinit 前用 keyIterator() 逐个释放——容器不会替你释放键指向的内存,因为它不知道你有没有所有权。这与第 02 章「没有隐藏控制流」完全一致:资源归还不该藏在 deinit 里。
20.4 顺序、内存与成本的取舍
| 维度 | HashMap(开放寻址) | ArrayHashMap |
|---|---|---|
| 查找 / 插入 | 平均 O(1),缓存局部性好 | 多一层索引,略慢 |
| 迭代 | 要跳过空槽,顺序不定 | 连续数组,顺序 = 插入顺序,缓存友好 |
| 删除 | 需要墓碑标记 | orderedRemove / swapRemove 语义同 ArrayList |
| 内存 | 为低装载率预留较多空间 | 额外一个索引数组,但键值对本身更紧凑 |
| 适合 | 纯查找、大表、热路径 | 要输出、要序列化、要稳定 diff / 测试快照 |
工程判断
「需要保序」往往不是性能问题,而是可复现性问题:日志、生成的配置文件、测试快照、JSON 输出,只要哈希顺序不稳定,diff 就会满天飞。这时候 ArrayHashMap 多付的一点代价非常划算。
小结 HashMap 的接口把三件事分开:值由容器管、键的所有权由你管、顺序由你选容器类型决定。
getOrPut省掉一次查找,dupe解决临时键,ArrayHashMap 解决可复现性。下一章开始处理「连哈希表都不该用」的场景。
21 MultiArrayList:SoA 与面向数据设计
对应视频《Zig MultiArrayList: one array per field (0.16.0)》(BV1QFno6wELX),也是 Andrew Kelley 反复强调的「面向数据设计(DoD)」最具体的一课:先问循环要读哪些字段,再决定内存怎么摆。
学习目标
- 画出 AoS 与 SoA 的内存布局差异,说明 padding 与 cache line 的影响
- 会用
items(.field)按字段访问,并理解类型安全的字段枚举- 能判断何时值得从 ArrayList 换成 MultiArrayList
21.1 AoS 的问题:你只想要 x,却搬来整个对象
普通 ArrayList(Particle) 是 AoS(Array of Structures):元素一个挨一个,每个元素内部按字段排列。CPU 取内存的最小单位是 64 字节 cache line,所以「只累加所有 x」时,y、kind、active 和结构体填充字节也会被一起载入——带宽花在了用不到的数据上。
| 布局 | 内存示意(4 个 Particle:f32,f32,u8,bool) | 只扫 x 时载入 |
|---|---|---|
| AoS | [x y k a _ _][x y k a _ _][x y k a _ _][x y k a _ _] | 4 × 12B = 48B,其中 32B 无用 |
| SoA | [x x x x][y y y y][k k k k][a a a a] | 16B,全是有用数据 |
0.17.1 实测 @sizeOf(Particle) == 12:两个 f32 占 8 字节,u8 + bool 占 2 字节,尾部 2 字节是对齐填充。SoA 把每个字段单独成数组,既消掉填充,又让扫描变成纯粹的连续读。
21.2 按字段访问:字段枚举是编译期的
std.MultiArrayList(T).items(.field) 的参数是一个由字段自动生成的枚举(Field),写错字段名是编译错误,不是运行期字符串查找。它内部为每个字段维护一段独立分配的内存,并用统一的 len 与 capacity 管理,因此多字段同时迭代天然等长——正好接上第 08 章的多序列 for。
const std = @import("std");
const Particle = struct {
x: f32,
y: f32,
kind: u8,
active: bool,
};
pub fn main() !void {
const gpa = std.heap.page_allocator;
var list: std.MultiArrayList(Particle) = .empty;
defer list.deinit(gpa);
for (0..4) |i| {
try list.append(gpa, .{
.x = @floatFromInt(i),
.y = 0,
.kind = @intCast(i % 2),
.active = i % 2 == 0,
});
}
// 每个字段单独成数组:只扫 x 时,kind / active 不会占缓存行。
const xs = list.items(.x);
const kinds = list.items(.kind);
var sum: f32 = 0;
for (xs) |x| sum += x;
std.debug.print("AoS element = {d}B (含填充), x 通道 = {d}B, sum = {d}\n", .{
@sizeOf(Particle), xs.len * @sizeOf(f32), sum,
});
// 多字段同时迭代:长度由同一个 len 保证(呼应第 08 章)。
for (xs, kinds) |x, k| std.debug.print("({d},{d}) ", .{ x, k });
std.debug.print("\n", .{});
}
0.17.1 实测通过
输出
AoS element = 12B (含填充), x 通道 = 16B, sum = 6,随后(0,0) (1,1) (2,0) (3,1)。同样 4 个元素,只扫 x 时 SoA 只需 16 字节连续数据,AoS 要 48 字节且带 2 字节/元素的填充。
21.3 多字段、标签联合与固定容量
- 多字段同时用:
list.slice()拿到一个包含所有字段切片的视图,适合一次遍历里读 2~3 个字段;读的字段越多,SoA 相对 AoS 的优势越小。 - 标签联合字段:视频提到
union(enum)也能作为字段。MultiArrayList 会为 tag 与 payload 分别建通道,代价是 payload 按最大变体分配;这是第 07 章与本章的交叉点。 - 固定容量:
initCapacity(gpa, n)后不再增长,配合appendAssumeCapacity可以写出完全无分支的热循环,适合 ECS / 粒子系统。 - 删除:
orderedRemove/swapRemove需要在所有字段通道上同步搬移,成本比 ArrayList 高;频繁随机删除的场景要重新评估。
21.4 什么时候值得换
| 信号 | 判断 |
|---|---|
| 元素数量大(万级以上)、循环只碰 1~2 个字段 | 强烈推荐 SoA,收益来自带宽与缓存 |
| 字段很多、每次都要读全对象 | AoS 更好,SoA 反而增加多次流与索引开销 |
| 元素频繁插入删除、顺序敏感 | 优先 ArrayList / ArrayHashMap |
| 要把某一列交给 SIMD 或外部 API | SoA 天然是连续数组,可直接喂给 @Vector(第 25 章) |
方法论
不要凭直觉改布局。先用基准测出「时间花在内存还是计算」:若 perf 里 cache miss / 带宽占主导,SoA 才可能带来成倍提升;若瓶颈是分支预测或算法复杂度,换布局几乎没用。第 25 章的 CSV 案例就是这套方法论的完整示范。
小结 MultiArrayList 把「结构体是内存布局」这件事变成可选项。它不改变算法,只是让数据按访问模式排列;这是 Zig 不给语言加抽象税、却愿意在标准库里提供底层布局工具的一个典型例子。
22 EnumArray / EnumMap / EnumSet:零分配集合
对应视频《Zig EnumArray, EnumMap 和 EnumSet:以枚举为键的集合 (0.16.0)》(BV18Fno6wE4T)。当键的集合在编译期就完全已知时,再去做哈希就是纯粹的浪费。
学习目标
- 区分三种枚举集合在「槽位是否必须有值」上的差异
- 理解它们为什么完全不需要 allocator、可以当普通值复制传递
- 能对比「手写数组 +
@intFromEnum」与标准库类型的取舍
22.1 三者的语义
| 类型 | 每个 tag 是否必须有值 | 底层表示 | 内存 | 例子 |
|---|---|---|---|---|
std.EnumArray(E, V) | 是,每个 tag 一个 V | 等价于 [N]V | N × sizeof(V) | 各日志级别计数 |
std.EnumMap(E, V) | 否,允许空槽 | [N]?V + 计数 | 略大,迭代跳过空槽 | 装备栏:只有部分槽位有物品 |
std.EnumSet(E) | 否,只有「在 / 不在」 | 位图 | 约 ceil(N/8) 字节 | 文件权限、功能开关 |
三者共同的优势:零分配、类型安全、可复制。索引直接用枚举 tag,不需要 @intFromEnum 强转,也不会出现「数组长度写错」「下标越界」这类手写数组常见错误。它们就是普通的值,可以放在结构体里、按值传参、放进 comptime 计算。
const std = @import("std");
const Level = enum { debug, info, warn, err };
const Slot = enum { head, chest, hands, feet };
const Perm = enum { read, write, execute };
pub fn main() void {
// 1) EnumArray:每个 tag 必有值,本质是 [N]V,完全不需要 allocator。
var counts: std.EnumArray(Level, u32) = .initFill(0);
counts.set(.warn, 3);
counts.getPtr(.info).* += 1;
std.debug.print("warn={d} info={d} sizeof={d}\n", .{
counts.get(.warn), counts.get(.info), @sizeOf(@TypeOf(counts)),
});
// 2) EnumMap:允许部分 tag 为空,迭代时自动跳过空槽。
var bag: std.EnumMap(Slot, []const u8) = .empty;
bag.put(.head, "helmet");
bag.put(.hands, "gloves");
std.debug.print("bag has {d} items, head={s}, chest={s}\n", .{
bag.count(), bag.get(.head).?, bag.get(.chest) orelse "empty",
});
// 3) EnumSet:位图,insert / contains / remove 都是位运算。
var perms: std.EnumSet(Perm) = .empty;
perms.insert(.read);
perms.insert(.write);
std.debug.print("read={} execute={} count={d}\n", .{
perms.contains(.read), perms.contains(.execute), perms.count(),
});
perms.remove(.write);
std.debug.print("after remove write={}\n", .{perms.contains(.write)});
}
0.17.1 实测通过
输出
warn=3 info=1 sizeof=16(4 个u32)、bag has 2 items, head=helmet, chest=empty、read=true execute=false count=2、after remove write=false。整段程序一次堆分配都没有。
22.2 与手写数组的对比
手写 [N]V + 强转 | EnumArray |
|---|---|
| 长度要自己写,加一个枚举值容易忘改 | 长度由枚举自动推导 |
每个访问点都要 @intFromEnum(tag) | 直接 get(.warn) / set(.warn, v) |
| 非连续枚举值需要额外映射 | 标准库内部处理 |
| 迭代要自己写索引循环 | iterator() 直接给出 key / value |
另一个常被忽略的亲戚是 std.EnumMultiset(按 tag 计数)与 std.StaticBitSet。选型的分界线很简单:只要键是编译期有限的枚举,就先考虑这一族,再考虑 HashMap。这也呼应第 10 章的 comptime 思想——把能在编译期确定的东西全部提前消掉。
22.3 选型决策
| 需求 | 选谁 |
|---|---|
| 每个 tag 都有值,且值类型相同 | EnumArray |
| 只有部分 tag 有值,或者「没有值」本身是业务状态 | EnumMap |
| 只需要判断存在性 / 组合标志位 | EnumSet |
| 键是运行期才知道的字符串或任意整数 | 回到第 20 章的 HashMap |
| 需要按 tag 计数、且要批量增删 | std.EnumMultiset / enums.EnumMultiset |
小结 枚举集合是「用类型把约束写进编译期」的典范:不需要 allocator、不需要哈希、不需要错误分支。它们和第 07 章的标签联合、第 10 章的 comptime 一起,构成 Zig 把运行期不确定性尽量前移的完整工具链。
23 选型学:从需求到容器的决策路径
本章是前八讲的综合,也是把「知道有哪些容器」升级为「能在需求评审时给出理由」的一章。Zig 标准库容器多,但选择逻辑其实只有四个问题。
学习目标
- 能用四个问题把需求收敛到一个容器 + 一个分配器
- 能解释常见组合(arena + ArrayList、FBA + Pool、SoA + SIMD)背后的成本模型
- 能识别「用错容器」的早期信号
23.1 四个问题
| # | 问自己 | 回答指向 |
|---|---|---|
| 1 | 元素的生命周期是整齐的一批,还是各自独立? | 整齐 → Arena;独立 → gpa / Pool;上限已知 → FBA |
| 2 | 键在编译期已知吗?是有限枚举吗? | 是 → EnumArray/Map/Set;否 → HashMap 家族 |
| 3 | 热循环读几个字段?是否要稳定顺序 / 可复现输出? | 字段少 + 量大 → SoA;要顺序 → ArrayHashMap / ArrayList |
| 4 | 对象是否同类型且高频生灭?内存是否必须可静态核算? | 是 → MemoryPool(可叠 FBA) |
23.2 四种高频组合
| 组合 | 解决什么 | 本手册示例 |
|---|---|---|
Arena + ArrayList | 一次请求里拼任意长度的结果,请求结束整体释放 | 第 17 章 + 第 19 章 |
FBA + MemoryPool | 嵌入式 / 游戏帧:零堆、上限可算、槽位复用 | 第 18 章 05_fba_pool.zig |
MultiArrayList + @Vector | 把某一列直接喂给 SIMD,消除 gather | 第 21 章 + 第 25 章 |
SafeAllocator + zig test | 开发期验证所有组合都不泄漏、错误路径能收干净 | 第 16 章 + 附录 F |
23.3 成本模型速查
| 操作 | ArrayList | ArrayHashMap | HashMap | MultiArrayList | Enum* |
|---|---|---|---|---|---|
| 追加 / 插入 | 摊还 O(1) | 平均 O(1) | 平均 O(1) | O(字段数) | O(1) |
| 按索引 / 键查 | O(1) | 平均 O(1) | 平均 O(1) | 按字段 O(1) | O(1) 直接索引 |
| 删除 | O(n) 保序 / O(1) 交换 | 同左 | 需墓碑 | O(字段数 × n) | O(1) |
| 迭代局部性 | 好 | 很好 | 需跳空槽 | 按列最优 | 最优 |
| 额外分配 | 增长时 | 增长时 | 增长时 | 增长时(每列) | 零 |
23.4 用错容器的早期信号
- 代码里出现大量
@intFromEnum(k)或手写数组长度常量 → 该用枚举集合。 - 为了稳定输出而在迭代前排序 → 该用 ArrayHashMap,而不是每次排序。
- 循环里只用一个字段,profile 却显示 cache miss 高 → 该评估 SoA。
- 到处
dupe字符串又到处free→ 生命周期没设计好,先问能不能整体 arena。 - 每个请求都
init/deinit一个 allocator → 该改成循环外 init + 循环内 reset。
贯穿全书的判断标准
Zig 的容器选型不追求「最强的数据结构」,而追求成本可见:分配发生在哪一行、内存在哪释放、迭代会碰到哪些字节,都应该能从代码里直接读出来。这也是第一部分第 02 章「一切可见」在数据结构层面的落点。
小结 先定生命周期,再定键的性质,再定访问模式,最后定内存上限。四步走完,容器与分配器基本就唯一确定了;剩下的只是把它写成 0.17 的非托管 API。附录 F 给了一组把本章决策树落到代码上的实验题。
24 Async I/O 与并发:从函数颜色到显式 Io
对应两讲:《Zig Async 的故事》(BV1WCWx6GEtV)与《Zig 创始人深度解释 Async I/O 与并发编程》(BV1PGxy6PE3E,Zigtoberfest 2025,约 116 分钟)。这是全书思想密度最高的一章,也是把第 04 章「Allocator 是参数」推广到 I/O 的一章。
学习目标
- 说清「函数颜色」问题,以及 Zig 旧 async 方案被弃用的原因
- 理解 0.16 起
std.Io为什么和Allocator同构- 区分 async 与 concurrent,说明
Group/Select/ 取消各自解决什么
24.1 函数颜色问题
在有 async/await 关键字的语言里,函数被染成两种颜色:普通函数和异步函数。异步函数只能被异步函数调用;想把一个同步库函数改成异步,调用链上每一层都要跟着改;标准库常常被迫维护两份实现。更麻烦的是,await 是一个语法层面的隐藏控制流——这恰恰违背第 02 章「看起来不像函数调用,就不会调用函数」的承诺。
| 方案 | 如何表达「等一等」 | 代价 |
|---|---|---|
| 回调 / Promise | 把后续逻辑塞进闭包 | 控制流碎片化,错误处理割裂 |
async/await 关键字 | 语言内建协程 | 函数染色、生态分裂、编译器复杂度 |
| Zig 0.11 之前的旧 async | 编译器生成无栈协程,suspend/resume | 与 C ABI / 回调 / 多种后端难以组合,最终被移除 |
| Zig 0.16 起:显式 Io | 把「能等待、能并发」的能力当作参数传进来 | 签名多一个参数,但没有颜色、没有隐藏状态机 |
《Zig Async 的故事》讲的是这段演进史:野心勃勃的编译器级 async 被删掉,换来的是一个更朴素、但能覆盖所有场景的库级接口。关键洞察是:异步真正需要的不是关键字,而是「谁拥有等待与并发的能力」——答案应该和内存一样,由调用者注入。
24.2 std.Io 与 Allocator 同构
std.mem.Allocator | std.Io | |
|---|---|---|
| 本质 | ptr + vtable(alloc/resize/remap/free) | userdata + vtable(文件、网络、时间、async/concurrent/await/cancel、锁、队列…) |
| 从哪来 | 调用者传入 gpa / arena / FBA | 0.16 起由 init.io 提供,也可自建 std.Io.Threaded |
| 换实现的代价 | 改一行参数 | 改一行参数:单线程事件循环 ↔ 线程池 ↔ 自定义后端 |
| 签名给的信息 | 「可能分配内存」 | 「可能阻塞、可能并发、可能被取消」 |
于是「同一个函数既能同步跑、也能并发跑」不再需要两份代码:函数只管调用 io.concurrent(...) 之类的接口,具体怎么调度由传进来的实现决定。0.17.1 的标准库里已经能看到 Io.Threaded、Io.Evented(io_uring / kqueue / Dispatch)、Io.Group、Io.Select、Io.Queue、互斥量与条件变量等完整设施。
24.3 异步不等于并发
Andrew Kelley 在演讲里反复区分这两个词,0.17.1 的接口也把它们做成了两个函数:
Io.async / Group.async | Io.concurrent / Group.concurrent | |
|---|---|---|
| 保证 | 任务不保证立即执行,结果直到 await 才一定可用;允许单线程栈式实现 | 更强:任务已获得一个并发执行单元,可以真的并行跑 |
| 实现自由度 | 高(单线程也能实现) | 低(后端必须支持并发,否则返回 error.ConcurrencyUnavailable) |
| 适用 | I/O 密集、只是不想阻塞当前逻辑 | CPU 密集、确实要多核一起算 |
演讲里那句「解耦函数调用与函数返回」说的就是 Future(T):调用 io.concurrent(fn, args) 立刻拿到一个 future,函数体可能还没跑完;等到真正需要结果时再 future.await(io)。中间这段时间,调用者可以继续做别的事。没有语法糖,没有隐藏的状态机——future 是一个普通值。
24.4 Group、Select 与取消:最难的正确性
| 原语 | 解决什么 | 0.17.1 中的形态 |
|---|---|---|
Io.Group | 把一组任务的生命周期绑在一起:一次性 await 全部;取消请求向所有成员传播 | Group.init / group.concurrent(io, fn, args) / group.await(io) / group.cancel(io) |
Io.Select(U) | 「谁先返回就处理谁」,结果用标签联合区分来源 | Select.init(io, buffer) / select.async(.field, fn, args) / await() / cancel() |
Cancelable | 统一的取消错误通道 | std.Io.Cancelable = error{Canceled};任务返回它即视为取消传播边界 |
Io.Queue(T) | 任务间传递结果,容量由调用者提供 | putOneUncancelable 等,队列关闭时返回 error.Closed |
| 并发限制 | 避免一次开 10 万个任务把内存打爆 | Threaded.init 的 concurrent_limit / async_limit,或用有界队列自行限流 |
演讲核心观点
难的从来不是「怎么启动一个任务」,而是怎么在任务被取消的任意时刻,把资源一点不漏地还回去。Zig 的答案是复用第 09 章已经存在的机制:
defer写在任务内部,无论正常返回、报错还是被取消都会执行;Group.await保证每个任务持有的资源在它自己返回时释放,而不是等整组结束。因此「长命 group + 反复加任务」并不构成泄漏。
演讲还专门讲了「资源归还」与「错误处理」:任务函数的返回值必须能强制转成 Cancelable!void,取消是错误集合里的一等成员;Select 用标签联合把不同任务的异构结果统一,避免 anytype 满天飞。这些设计与第 06 章「错误即值」、第 07 章「标签联合」是同一套类型工具,不需要再学一套并发 DSL。
const std = @import("std");
// 任务函数只需返回 Cancelable!void;它拿到的是调用者显式传下来的资源。
fn tick(id: u8, counter: *std.atomic.Value(u32)) std.Io.Cancelable!void {
_ = id;
_ = counter.fetchAdd(1, .monotonic);
}
pub fn main(init: std.process.Init) !void {
const io = init.io; // I/O 与并发能力像 Allocator 一样由调用者注入
var counter: std.atomic.Value(u32) = .init(0);
var group: std.Io.Group = .init;
for (0..4) |i| {
try group.concurrent(io, tick, .{ @as(u8, @intCast(i)), &counter });
}
try group.await(io); // 等所有任务完成;取消请求会沿 group 传播
std.debug.print("completed tasks = {d}\n", .{counter.load(.monotonic)});
}
0.17.1 实测通过
输出
completed tasks = 4。注意三点:io直接来自main(init: std.process.Init),没有全局运行时;任务函数不认识线程也不认识调度器,只拿到一个原子计数器;group.await(io)是唯一的同步点。
24.5 0.17 落地现状与风险提示
std.Io在 0.16 引入,0.17 继续演进;std.process.Init的io/gpa/arena三字段在 0.16 与 0.17 一致,是相对稳定的入口。- 0.17 把
errdefer |err|移除了(第 06、09 章),因此取消路径上想记录具体错误,要用catch |err| { ...; return err; }在边界处理。 - 文件名、错误名与取消 API 在 1.0 之前仍可能调整;写生产代码请以所用版本的
lib/std/Io.zig为准,不要照抄旧博客。 - 「显式 Io」不意味着所有库都会自动并发:只有接受
Io参数并主动调用async/concurrent的代码才具备并发能力。这依然是可见的、需要设计的。
小结 Zig 用「把能力当参数」替代了「给函数染色」。
Allocator是内存能力的参数,Io是等待与并发能力的参数;defer负责取消安全,错误联合负责取消传播,标签联合负责异构结果。整套并发模型没有引入新的语言机制,只是把第一部分的原则用到了极致。
25 SIMD 实战:把 CSV 解析压到 7 秒
对应视频《从 20 分钟到 7 秒:Zig + SIMD 构建极致性能的 CSV 流式解析器》(BV13axQ6YEUi,Peyman Mortazavi,Zigtoberfest 2026,约 80 分钟)。这是把第 11 章「向量只是一种类型」变成工程方法论的一讲。
学习目标
- 理解「零分配 + 流式」为什么能把常驻内存压到几百 KB
- 会写
@Vector→ 位掩码 → CTZ / BLSR 的向量化分隔符搜索- 能说出优化顺序:先改算法与内存,再改分支,最后才谈指令
25.1 问题设定:为什么 2 GB 文件会拖垮解析器
视频的起点是一个很常见的失败:用 Pandas / Python 解析 2 GB 以上的 CSV,耗时约 20 分钟,期间内存持续暴涨甚至崩溃。根因不在「Python 慢」四个字,而在三个具体的设计选择:
| 常见问题 | 后果 | Zig 方案 |
|---|---|---|
| 把整个文件读进内存 / 物化全表 | RSS 与文件大小同阶 | 固定大小缓冲 + 流式,内存与文件大小无关(视频报告常驻约 800 KB) |
| 每行、每字段都分配对象 | 分配器与 GC 成为热点 | 零分配:字段用切片指向输入缓冲,不复制 |
| 逐字节 if 判断分隔符 / 引号 | 分支预测失败率高,流水线反复清空 | SIMD 并行比较 + 位掩码,一次处理 32/64 字节,几乎没有分支 |
优化后的结果:同样的 2 GB 级输入,约 7 秒完成。数量级差异来自「内存流量」和「分支数」同时下降,而不是某个编译器开关。
25.2 零分配流式的三个不变量
- 缓冲区固定:一次读一个 chunk(如 32/64 字节的若干倍),无论文件多大,RSS 恒定。
- 状态跨 chunk 保留:引号状态、当前字段起点、上一块末尾的转义符都要显式存成几个标量,不能靠「再读一遍」。
- 字段不复制:字段以
[]const u8借用到缓冲区;跨 chunk 的字段才需要额外处理(回拷到固定边界区或增量消费)。
这三条和第 18 章的 FBA、第 17 章的 arena 是同一种思维:先给内存设一个硬上限,再设计算法去适配它。它们也解释了为什么这类代码在 Zig 里比在托管语言里好写——没有隐藏分配,缓冲区的生命周期完全可见。
25.3 向量化分隔符搜索:掩码 + CTZ + BLSR
第 11 章说过 @Vector(32, u8) 就是「32 个 u8 的类型」。把它用于 CSV 搜索只需三步:
| 步骤 | Zig 写法 | 作用 |
|---|---|---|
| 1. 并行比较 | v == @as(Vec, @splat(',')) | 得到 @Vector(32, bool),一条指令比完 32 字节 |
| 2. 压成位掩码 | @intFromBool → @bitCast 到 u32 | 32 个布尔压成 32 个位,第 i 位为 1 表示第 i 字节是分隔符 |
| 3. 迭代命中位 | @ctz(mask) + mask &= mask - 1 | CTZ 找最低位的 1;BLSR 清掉它。循环次数 = 命中数,而不是 32 次 |
引号与转义需要第二条向量通道:同一块数据再比一次 ",用位运算算出「哪些分隔符在引号内」,把它们从掩码里剔除。整个热循环没有逐字节分支,分支预测失误率自然降下来。
const std = @import("std");
const LANES = 32;
const Vec = @Vector(LANES, u8);
// 一次比较 32 字节,把「哪里有分隔符」压缩成一个 32 位掩码。
fn scanChunk(
gpa: std.mem.Allocator,
chunk: [LANES]u8,
needle: u8,
base: usize,
hits: *std.ArrayList(usize),
) !void {
const v: Vec = chunk;
const eq: @Vector(LANES, bool) = v == @as(Vec, @splat(needle));
const bits: @Vector(LANES, u1) = @intFromBool(eq);
var mask: u32 = @bitCast(bits);
// CTZ 取最低位 1 的位置,BLSR (mask &= mask-1) 清掉它;循环次数 = 命中数。
while (mask != 0) {
const lane: usize = @ctz(mask);
try hits.append(gpa, base + lane);
mask &= mask - 1;
}
}
pub fn main() !void {
const gpa = std.heap.page_allocator;
const line = "name,age,city,role,score,active,team,dept";
var hits: std.ArrayList(usize) = .empty;
defer hits.deinit(gpa);
// 流式:每次只喂一个 32 字节块,内存与文件总大小无关。
var start: usize = 0;
while (start < line.len) : (start += LANES) {
var chunk: [LANES]u8 = @splat(' '); // 补位不会命中逗号
const n = @min(LANES, line.len - start);
@memcpy(chunk[0..n], line[start..][0..n]);
try scanChunk(gpa, chunk, ',', start, &hits);
}
std.debug.print("comma positions: {any}\nfields: {d}\n", .{ hits.items, hits.items.len + 1 });
}
0.17.1 实测通过
输出
comma positions: { 4, 8, 13, 18, 24, 31, 36 }/fields: 8。41 字节的输入被切成两个 32 字节块,补位用空格(不会匹配逗号),结果与普通逐字节扫描完全一致。
教学说明
上面这段是可独立运行的最小内核,用来讲清掩码与位迭代;真实解析器还要处理引号状态机、跨块字段、CRLF、UTF-8 校验与输出。但热路径的形状不变:一次向量比较 → 一个掩码 → 按位消费。把
LANES换成 64 并改用u64掩码,就能在 AVX-512 类目标上进一步扩展。
25.4 优化顺序:先量,再改
| 阶段 | 先看什么指标 | 对应改动 |
|---|---|---|
| 1 | 峰值 RSS、分配次数 | 改流式、去掉逐行对象;收益通常最大 |
| 2 | cache miss / 内存带宽 | SoA 布局(第 21 章)、减少复制、对齐缓冲 |
| 3 | branch-misses | 向量比较 + 位掩码,把控制流变成数据 |
| 4 | IPC、指令数 | 最后才考虑 intrinsic、循环展开、@prefetch |
视频的基准测试部分也强调:要报告可复现的输入规模、机器与口径,否则「快了 170 倍」没有意义。第 23.4 节那句「不要凭直觉改布局」在这里同样成立——先测出瓶颈是内存、分支还是指令,再选武器。
小结 极致性能不是靠玄学指令,而是三个朴素决定的叠加:固定内存、零分配、把逐字节分支变成向量比较与位运算。第 11 章的
@Vector之所以被称为「只是一种类型」,正因为它可以直接嵌进这套普通的 Zig 代码里,不需要 intrinsic、不需要外部库。
26 构建系统:DAG 构建图与跨平台编译
对应视频《彻底搞懂 Zig 构建系统:DAG 构建图与跨平台编译实战》(BV1PDYy6XEeP,Code Guild,约 20 分钟)。这一讲把 zig build 从「一条命令」还原成「一张图」。
学习目标
- 说清
build.zig的build(b)为什么不执行编译- 能独立写出含 install / run / test / 自定义步骤的 0.17 构建脚本
- 掌握
-Dtarget、-Doptimize、-p与缓存目录的关系
26.1 四条命令的分工
| 命令 | 做什么 | 何时用 |
|---|---|---|
zig build-exe main.zig | 直接把一个源文件编译成可执行文件 | 单文件试验、教学、CI 里的极简检查 |
zig build-lib / build-obj | 编译库 / 目标文件 | 与 C 生态对接、手工链接 |
zig run / zig test | 编译并立即执行 / 跑测试 | 本手册所有单文件示例 |
zig build | 先编译并执行 build.zig 生成构建图,再由 runner 调度整张图 | 正式项目:多目标、多步骤、依赖、安装、打包 |
0.17 把 zig build 拆成了 configurer(跑 build.zig、产出构建图)与 maker(执行图)两个进程,并引入 Build Server Protocol。这正是第 12.2 章说的「0.17 对构建脚本是破坏性变更」的根因;副作用是 ZLS 在 0.17.0 上一度无法工作。
26.2 DAG:build() 描述图,runner 执行图
pub fn build(b: *std.Build) void 里每一个 b.addXxx 只是创建一个节点,step.dependOn(&other.step) 只是加一条有向边。函数返回后,runner 拿到一张 DAG:没有依赖关系的节点可以并行执行,输入没变的节点直接命中缓存跳过。
| 概念 | 含义 | 在脚本里 |
|---|---|---|
| Step(节点) | 一个可缓存的工作单元 | b.step("test", ...)、b.addRunArtifact(exe) |
| 依赖(边) | 先后顺序约束,同时决定缓存键 | a.dependOn(&b.step) |
| Artifact | 编译产物,也是节点 | b.addExecutable(.{...}) |
| Install | 把产物复制到安装前缀 | b.addInstallArtifact(exe, .{}) |
| 缓存 | .zig-cache/(本机中间产物);全局缓存按内容哈希复用 | 由 runner 管理,脚本不直接操作 |
| 安装前缀 | zig-out/(默认),-p 可改 | 正式交付物只从这里取 |
一个关键习惯
run步骤要显式dependOn(b.getInstallStep()):这样程序从安装目录启动,工作目录与真实部署一致;否则它会在缓存目录里跑,相对路径读取的资源可能全部找不到。模板项目就是这么写的。
26.3 一个完整、可运行的三文件项目
目录结构:build.zig、build.zig.zon、src/main.zig。三份文件都在本机 Zig 0.17.1 上实测通过。
① build.zig —— 描述五个节点
const std = @import("std");
// build() 并不执行编译,它只负责「描述」一张有向无环图(DAG)。
// 真正的编译、缓存判定与并行调度交给 build runner。
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// 节点 1:编译可执行文件。0.17 用 createModule 显式携带 target / optimize。
const exe = b.addExecutable(.{
.name = "ziglab",
.root_module = b.createModule(.{
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
}),
});
// 节点 2:把产物安装到 zig-out/bin(默认 install 步骤依赖它)。
const install = b.addInstallArtifact(exe, .{});
b.getInstallStep().dependOn(&install.step);
// 节点 3:运行。依赖 install,保证从安装目录启动。
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
run_cmd.addPassthruArgs(); // `zig build run -- arg1 arg2`
const run_step = b.step("run", "编译并运行 ziglab");
run_step.dependOn(&run_cmd.step);
// 节点 4:单元测试,是独立的一份编译产物。
const tests = b.addTest(.{ .root_module = exe.root_module });
const run_tests = b.addRunArtifact(tests);
const test_step = b.step("test", "运行单元测试");
test_step.dependOn(&run_tests.step);
// 节点 5:自定义聚合步骤。两个依赖互不依赖,runner 可以并行执行。
const check = b.step("check", "测试 + 安装一次跑完");
check.dependOn(&run_tests.step);
check.dependOn(&install.step);
}
② build.zig.zon —— 包清单
.{
.name = .ziglab,
.version = "0.1.0",
.fingerprint = 0xb73f3d540c43255f,
.minimum_zig_version = "0.17.1",
.dependencies = .{},
.paths = .{ "build.zig", "build.zig.zon", "src" },
}
0.17 必填字段
.fingerprint在 0.17 是必填的,且由工具链根据包名生成。新项目不要手编:删掉这一行运行一次zig build,编译器会在报错里给出建议值,填回去即可。.minimum_zig_version与.paths决定包哈希与依赖解析,别漏。
③ src/main.zig —— 带一个测试的程序
const std = @import("std");
const builtin = @import("builtin");
pub fn main(init: std.process.Init) !void {
var buf: [256]u8 = undefined;
var w = std.Io.File.stdout().writerStreaming(init.io, &buf);
const out = &w.interface;
try out.print("ziglab: arch={s} os={s} mode={t}\n", .{
@tagName(builtin.target.cpu.arch),
@tagName(builtin.target.os.tag),
builtin.optimize,
});
try out.flush();
}
test "parseInt" {
try std.testing.expectEqual(@as(u16, 8080), try std.fmt.parseInt(u16, "8080", 10));
}
0.17.1 实测通过
zig build run输出ziglab: arch=x86_64 os=windows mode=debug;zig build test、zig build check、zig build -p dist、zig build -Dtarget=x86_64-linux-gnu、zig build -Dtarget=aarch64-windows-gnu、zig build -Doptimize=fast全部返回 0。zig-out/bin与dist/bin各自得到可执行文件。
26.4 命令速查与跨平台编译
zig build # 默认 install,产物进 zig-out/bin
zig build run -- hello # 运行;-- 之后的参数由 addPassthruArgs 透传
zig build test # 编译并运行单元测试
zig build check # 自定义聚合步骤(test + install 并行)
zig build -p dist # 改安装前缀,产物进 dist/bin
zig build -Doptimize=fast # 0.17 的优化模式是小写 fast
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=aarch64-windows-gnu
zig build --list-steps # 列出所有顶层步骤
zig targets # 列出所有可用目标三元组
交叉编译不需要装目标系统的工具链:Zig 自带各目标的标准库与链接器后端,-Dtarget=<arch>-<os>-<abi> 即可。zig targets 可列出所有合法三元组。注意 -Doptimize 在 0.17 的合法值是小写 debug / safe / fast / small(对应 std.lang.Optimize),旧资料里的 ReleaseFast 等名称属于 0.16 及更早(见 12.1 第 5 条)。
install (default) Copy build artifacts to prefix path
uninstall Remove build artifacts from prefix path
run 编译并运行 ziglab
test 运行单元测试
check 测试 + 安装一次跑完
26.5 0.16 → 0.17 构建脚本迁移要点
| 0.16 及视频里的写法 | 0.17 写法 |
|---|---|
b.addExecutable(.{ .root_source_file, .target, .optimize }) | .root_module = b.createModule(.{ .root_source_file, .target, .optimize }) |
b.installArtifact(exe) | 仍可用;教学上更推荐显式 b.addInstallArtifact(exe, .{}) + dependOn |
b.args 透传运行参数 | run_cmd.addPassthruArgs() |
-Doptimize=ReleaseFast | -Doptimize=fast(或 --release=fast) |
b.build_root / pathFromRoot() | b.root 相关字段;自定义 makeFn 改为小程序 + addRunArtifact |
| ZLS 直接读 build.zig | 0.17.0 因 Build Server Protocol 迁移暂时不可用,先用 CLI 诊断过渡 |
设计上的一致性
构建系统也是 Zig 用 Zig 写的:
build.zig是普通 Zig 程序,节点是普通对象,依赖是普通方法调用。没有 CMake 那样的第二门 DSL,也不需要学一套新的表达式语法——这和第 10 章「用 Zig 写 Zig」、第 24 章「用库接口而非关键字」是同一种克制。
小结 把
build.zig当成「图的描述」而不是「脚本」:节点、依赖、缓存、安装前缀、目标三元组各司其职。0.17 的破坏性变更主要落在root_module与进程模型上,升级时先改构建脚本,再谈业务代码(呼应 12.2 的结论修正)。
PART III · 进阶专题 · 从「会写」到「会设计」
第三部分依据另外 6 讲视频:2 讲 Ziggurat 短课(编译期字符串映射、两种队列)与 4 场创始人 / 社区长演讲(面向数据设计、任务取消、无指针编程、内存布局)。这里不再逐个介绍 API,而是回答设计层面的问题:一张表放在编译期还是运行期、数据在内存里怎么摆、任务如何安全地被终止、以及为什么「布局确定性」本身就是语言特性。
第三部分导学:专题地图与材料说明
前两部分解决「看得懂 Zig」和「能负责一个模块」;这 6 讲把视角推到系统设计:同样的功能,换一种数据表示或取消协议,性能与正确性会差一个数量级。
学习目标
- 能把运行时的分派表、查找表、优先级判断尽可能前移到编译期,并说清边界
- 能解释缓存未命中为什么比指令数更决定吞吐量,并独立设计一次对照测量
- 能设计协作式取消协议,保证取消路径也归还资源、不吞掉取消信号
- 能用索引 / 世代句柄替代数据结构内部指针,并判断何时必须保留指针
- 能区分普通 struct、extern struct、packed struct 的布局保证,写出与线格式一致的解析代码
导学 3.1 与前两部分的关系:不是重复,是往下挖一层
6 讲里有 4 讲的主题和前面章节表面重叠(SoA、Async、SIMD、指针失效)。本部分不重复讲机制,而是补上「为什么这样设计」和「边界在哪」:
| 已有章节 | 本部分深化 | 多出来的那一层 |
|---|---|---|
| 第 21 章 MultiArrayList / SoA | 第 29 章 DoD 实战 | 从「用哪个容器」升级到「五个结构体瘦身技巧 + 缓存行成本模型 + 实测方法」 |
| 第 24 章 Group / Select / 取消 | 第 30 章 取消专题 | 从「0.17 API 怎么用」升级到「硬件中断 → EINTR → 取消模型 → 资源归还协议」 |
| 第 19 章 指针失效 / lockPointers | 第 31 章 无指针编程 | 从「避免悬垂」升级到「索引 + 世代句柄让整块数据可搬移、可序列化、可跨进程」 |
| 第 11 章 / 第 07 章 类型与布局 | 第 32 章 布局确定性 | 从「有这些类型」升级到「131071 种整数、三种 struct 布局规则、in-memory ≠ 线格式」 |
| 第 20 章 HashMap | 第 27 章 / 第 28 章 | 补上「不需要哈希表」与「不是线性表」的两种容器:编译期字符串表、堆 / 环形双端队列 |
导学 3.2 材料来源与局限(请先读)
这 6 讲同样来自 B 站 UP 主 myfreax 的合集《Zig 编程语言》(共 47 集),每讲一般含「中文配音 / 原声」两个分 P。我抓取了标题、简介、分 P 时长、合集目录与原始演讲出处;但 B 站这些视频均未挂载字幕轨,因此长演讲无法逐字转录。
- 短课 2 讲(各约 3.5 分钟):简介附带完整章节时间轴,知识点可逐节对齐,教材内容依据时间轴 + 0.17.1 标准库源码逐项复原。
- 长演讲 4 讲(10–94 分钟不等):依据是标题、简介给出的主题与要点、原始演讲出处,以及本机 0.17.1 源码与编译实测;按教材体例重构为可验证的知识结构,不是演讲逐字稿,也不冒充引用原话。
- 版本基线:两讲标注
0.16.0;本部分所有示例统一用 Zig 0.17.1 重写并编译运行,凡 0.16 / 0.17 差异都写进正文与附录 E。 - 数值来源:容量、大小、耗时、报错信息均来自本机实测;性能数字受机器与调度影响,应在自己机器上复测,不要把比值当成普适常数。
阅读约定
每章结构沿用第二部分:学习目标 → 原理 → 0.17.1 实测代码 → 陷阱清单 → 小结。标「0.17.1 实测通过」的代码块是完整独立程序,保存为
.zig后zig run 文件名.zig即可复现。6 讲的完整索引、时间轴与章节映射见附录 G,配套练习见附录 H。
导学 3.3 三条进阶路径
- 容器与编译期(约 1 小时):27 → 28 → 回看第 10、20、22 章。目标是把「运行时查表」和「运行时排序」尽可能变成编译期常量与专用结构。
- 性能工程(约 3 小时):29 → 31 → 32 → 回看第 21、25 章。目标是能对着
@sizeOf、缓存行和一段 benchmark 说出瓶颈在哪,而不是靠猜。 - 系统正确性(约 3 小时):30 → 回看第 24、16 章。目标是给每个可能长时间运行的操作写出取消点、清理路径与错误传播规则。
27 StaticStringMap:把字符串分派搬到编译期
对应视频《Zig StaticStringMap:将单词转换为值》(BV1bPno6bEX3,原视频 Ziggurat,约 3:34)。视频的六节是:匹配单词 → 编译时生成映射表 → 查找机制 → 大小写不敏感 → 最长匹配 → 枚举名快捷方式。
学习目标
- 说清 Zig 为什么不能对
[]const u8直接switch- 读懂
initComptime生成的两张静态表,以及查找的时间成本- 掌握大小写不敏感、最长前缀、枚举名快捷方式三种变体
- 判断什么时候该改用
HashMap而不是静态表
27.1 为什么字符串不能进 switch
Zig 的 switch 要求分支标签在编译期可判定且可穷尽,实际支持整数、枚举、标签联合的标签等值语义类型。[]const u8 是一个「指针 + 长度」的运行时切片,两段内容相同的字符串地址不同,编译器无法把它变成跳转表——所以 switch (method) { "GET" => ... } 根本不合法。
常见替代是 if 链,代价有三:比较次数随分支数线性增长、容易漏掉大小写 / 空白处理、把本可以编译期决定的分派推迟到每次请求。第 20 章的 StringHashMap 解决了查找复杂度,却引入了哈希计算、堆分配、键的所有权和初始化时机。如果键集合在编译期就固定(HTTP 方法、命令字、关键字、枚举名),这两条路都不是最优解。
27.2 编译期生成的两张表:按长度分桶 + 组内排序
0.17.1 的 lib/std/static_string_map.zig 里,initComptime 在 comptime 块中做三件事:
- 把
kvs_list按键长度升序、同长度字典序排序,生成静态keys/values数组(initSortedKVs)。 - 生成
len_indexes:长度 L 对应的第一个键的下标,同时记录min_len/max_len(initLenIndexes)。 - 用
@setEvalBranchQuota(10 * n * log2(n))给编译期求值扩容配额——这一行直接说明构建成本随n log n增长,是「编译期换运行期」的明码标价。
运行时 getIndex 因此只需要:长度越界直接返回 null → 用 len_indexes[str.len] 跳到桶起点 → 在同长度的键里线性比较,遇到长度变化即停。没有哈希、没有分配、没有初始化,也不需要在 main 里先 put 一轮。
27.3 四种变体:大小写、最长前缀、枚举名、静态集合
| 需求 | 写法(0.17.1) | 关键点 |
|---|---|---|
| 精确匹配 | std.StaticStringMap(V).initComptime(.{ .{"GET", .GET}, ... }) | 零分配;get / has / getIndex / keys / values |
| ASCII 大小写不敏感 | std.StaticStringMapWithEql(V, std.static_string_map.eqlAsciiIgnoreCase) | 替换相等函数;长度分桶仍成立,因为大小写不改变字节数 |
| 最长前缀匹配 | getLongestPrefix(s) | 从 max_len 向 min_len 逐个截前缀再查桶,开销是 O(长度跨度 × 同长度键数) |
| 枚举名当键(0.17 新增) | std.StaticStringMap(Method).initEnum() | 直接取 @typeInfo(V).@"enum".field_names 建表,0.16 需要手写 @tagName 映射 |
| 静态字符串集合 | std.StaticStringMap(void).initComptime(.{ .{"if"}, .{"else"} }) | V = void 时 KV 元组只写键,用 has() 判定 |
| 键在运行时才知道 | init(kvs_list, gpa) + deinit(self, gpa) | 同样排序分桶,但表在堆上;这时要自己管生命周期 |
下面这段程序把上述变体放在一起,全部是编译期表;注意 keys() 返回的顺序是排序后的顺序,而不是你写进去的顺序:
const std = @import("std");
const Method = enum { GET, POST, PUT, DELETE, HEAD };
// initComptime:编译期按键长度分桶 + 组内排序,运行时一张静态表,零分配。
const routes = std.StaticStringMap(Method).initComptime(.{
.{ "GET", .GET },
.{ "POST", .POST },
.{ "PUT", .PUT },
.{ "DELETE", .DELETE },
.{ "HEAD", .HEAD },
});
// 0.17 新增:值类型是 enum 时,直接用 tag 名当键,连表都不用手写。
const by_name = std.StaticStringMap(Method).initEnum();
// 自定义相等函数:ASCII 大小写不敏感。
const ci = std.StaticStringMapWithEql(u8, std.static_string_map.eqlAsciiIgnoreCase).initComptime(.{
.{ "GET", 1 },
.{ "POST", 2 },
.{ "PUT", 3 },
});
// 最长前缀:路由/协议解析里比 switch 更自然的写法。
const prefixes = std.StaticStringMap(u8).initComptime(.{
.{ "GET", 1 },
.{ "GET /", 2 },
.{ "GET /api", 3 },
});
pub fn main() !void {
std.debug.print("routes.get(POST) = {?}\n", .{routes.get("POST")});
std.debug.print("routes.get(patch) = {?}\n", .{routes.get("patch")});
std.debug.print("routes.getIndex(GET) = {?}\n", .{routes.getIndex("GET")});
std.debug.print("routes.keys() = ", .{});
for (routes.keys()) |k| std.debug.print("{s} ", .{k});
std.debug.print("\n", .{});
std.debug.print("by_name.get(DELETE) = {?}\n", .{by_name.get("DELETE")});
std.debug.print("ci.get(gEt) = {?}\n", .{ci.get("gEt")});
const hit = prefixes.getLongestPrefix("GET /api/v1/users").?;
std.debug.print("longest prefix = {s} -> value {d}\n", .{ hit.key, hit.value });
// 只用 void 值就是编译期字符串集合,等价于一个静态 set。
const keywords = std.StaticStringMap(void).initComptime(.{ .{"if"}, .{"else"}, .{"while"} });
std.debug.print("has(while)={} has(for)={}\n", .{ keywords.has("while"), keywords.has("for") });
}
0.17.1 实测通过
输出:
get(POST)=.POST、get(patch)=null、getIndex(GET)=0;keys()为GET PUT POST HEAD DELETE(3/3/4/4/6 字节,同长度按字典序);ci.get("gEt")=1;GET /api/v1/users的最长前缀是GET /api,命中值 3;void集合has("while")=true, has("for")=false。
27.4 边界与陷阱
| 陷阱 | 后果 | 对策 |
|---|---|---|
把动态键集合硬塞进 initComptime | 编译期配额暴涨、编译变慢,且新增键要重新编译 | 键来自配置 / 插件 / 用户输入时用 StringHashMap 或运行时 init(kvs, gpa) |
| 大量键长度完全相同 | 长度分桶失效,退化成同长度线性扫描 | 键多且长时改用哈希表;静态表适合几十个短键 |
自定义 eql 改变「长度」语义 | 长度分桶把正确匹配提前排除 | 相等函数必须保持「相等 ⇒ 长度相同」,例如忽略大小写可以,忽略空白不行 |
以为 getLongestPrefix 是 O(1) | 在长输入上反复查表变慢 | 源码明确标注是 O(N);热路径里先按业务规则截断输入 |
运行时 init 后忘记释放 | 泄漏(第 16 章的 SafeAllocator 会报出来) | 配对调用 deinit(map, gpa) |
小结 StaticStringMap 是第 10 章
comptime哲学的一个漂亮实例:把「一堆固定的字符串 → 值」从每次请求时的比较,变成编译期排好序的常量数据。它与 HashMap 不是替代关系,而是键集合是否编译期已知的分水岭。
28 PriorityQueue 与 Deque:两种「排队」
对应视频《Zig PriorityQueue and Deque: 两种队列》(BV1DAno6FENM,Ziggurat,约 3:29):最紧急的优先 → 最小或最大优先 → 结合额外数据比较 → 两端都可操作的队列 → 保留最后几项。
学习目标
- 读懂
PriorityQueue(T, Context, compareFn)三个参数各自的角色- 识别「优先级来自可变 Context」时堆不变量被破坏的场景,并给出修法
- 用
Deque.initBuffer在栈上实现零分配的滑动窗口- 在 ArrayList / Deque / PriorityQueue / PriorityDequeue 之间做正确选型
28.1 二叉堆、Context 与比较函数
PriorityQueue 底层是一个数组式二叉堆:push 尾部插入后 siftUp,pop 取根并用末元素补位再 siftDown,peek 只读 items[0]。复杂度:插入 / 弹出 O(log n),看最高优先级 O(1)。
三个类型参数分工明确:T 是元素;compareFn 是编译期确定的比较函数(返回 std.math.Order);Context 是运行时注入的比较状态,由 initContext(context) 传入。视频里「路径规划最近距离优先」就是典型用法:元素只存节点 id,距离放在外部数组里,比较时查表。
0.16 → 0.17
PriorityQueue自 0.16 起是非托管 API(push(gpa, x)、deinit(gpa)),Deque也是 0.16 引入的。我逐项比对了本机 0.16.0 与 0.17.1 的lib/std:StaticStringMap、PriorityQueue、Deque的导出与方法签名基本一致,所以这组的视频代码在 0.17 上大多可直接运行(新增能力是第 27 章的initEnum)。真正要小心的是更早的托管式写法——容器自己持有分配器、不需要传gpa——那套代码在 0.17 已不适用。另有PriorityDequeue,同时支持popMin/popMax。
28.2 动态优先级:最容易埋雷的一处
把距离放在 Context 指向的数组里非常方便,但堆在 push 时已经按当时的距离排好了;距离一变,数组顺序不再满足堆性质。update(elem, new_elem) 也救不了:它用 compareFn(new_elem, old_elem) 决定上浮还是下沉,而优先级在元素外部时两者比较结果恒为 .eq,函数直接返回,什么都不做。
下例把整个陷阱和正确修法都跑了一遍:
const std = @import("std");
const Task = struct { id: u8, label: []const u8 };
const Dist = [5]u32;
// 优先级不在元素里,而在 Context 指向的距离表里(Dijkstra 的松弛表)。
// 必须能区分不同元素:距离相等时用 id 打破平局,否则 update() 会认错人。
fn byDist(ctx: *const Dist, a: Task, b: Task) std.math.Order {
return switch (std.math.order(ctx[a.id], ctx[b.id])) {
.eq => std.math.order(a.id, b.id),
else => |o| o,
};
}
const Queue = std.PriorityQueue(Task, *const Dist, byDist);
fn fill(q: *Queue, gpa: std.mem.Allocator) !void {
try q.push(gpa, .{ .id = 0, .label = "A" });
try q.push(gpa, .{ .id = 1, .label = "B" });
try q.push(gpa, .{ .id = 2, .label = "C" });
try q.push(gpa, .{ .id = 3, .label = "D" });
try q.push(gpa, .{ .id = 4, .label = "E" });
}
pub fn main() !void {
const gpa = std.heap.page_allocator;
var dist: Dist = .{ 30, 10, 20, 5, 40 };
var q = Queue.initContext(&dist);
defer q.deinit(gpa);
try fill(&q, gpa);
std.debug.print("pop order:", .{});
while (q.pop()) |t| std.debug.print(" {s}({d})", .{ t.label, dist[t.id] });
std.debug.print("\n", .{});
try fill(&q, gpa);
std.debug.print("peek before = {s} ({d})\n", .{ q.peek().?.label, dist[q.peek().?.id] });
// 陷阱 1:改了 Context 里的距离,堆内部数组不会自己重排。
dist[2] = 1; // C 被松弛成最近的节点
std.debug.print("peek after mutating context = {s} ({d}) <- stale\n", .{
q.peek().?.label, dist[q.peek().?.id],
});
// 陷阱 2:优先级来自外部状态时,update() 也救不了——比较新旧元素得到 .eq,不会 sift。
try q.update(.{ .id = 2, .label = "C" }, .{ .id = 2, .label = "C" });
std.debug.print("peek after update = {s} ({d}) <- still stale\n", .{
q.peek().?.label, dist[q.peek().?.id],
});
// 正确做法:把优先级写进元素并用 update(),或状态变化后重建堆。
q.deinit(gpa);
q = Queue.initContext(&dist);
try fill(&q, gpa);
std.debug.print("peek after rebuild = {s} ({d})\n", .{
q.peek().?.label, dist[q.peek().?.id],
});
std.debug.print("count={d} capacity={d}\n", .{ q.count(), q.capacity() });
}
pop order: D(5) B(10) C(20) A(30) E(40)
peek before = D (5)
peek after mutating context = D (5) <- stale
peek after update = D (5) <- still stale
peek after rebuild = C (1)
count=5 capacity=8
0.17.1 实测输出解读
初始弹出顺序
D(5) B(10) C(20) A(30) E(40);把dist[2]从 20 松弛成 1 后,peek()仍是D(5),调用update()之后依旧是 D;只有重建堆之后peek()才变成C(1)。count=5 capacity=8也顺带展示了非托管队列自己管理容量增长。
由此得到两条工程规则:
- 优先级会变:把优先级字段写进元素(例如
Task{ id, cost }),每次变化调用update(old, new);此时compareFn必须能区分不同元素(距离相等时用 id 打破平局),否则update按.eq查找会认错人。 - 优先级在外部 Context 里:Context 视为只读;若外部状态确实会变,就重建堆,或者改用「插入新元素 + 惰性删除」的经典 Dijkstra 写法。
28.3 Deque:一个 head + len 的环形缓冲
std.Deque(T) 用一段连续缓冲区加 head(逻辑第一个元素的物理下标)和 len 表示队列;逻辑下标 i 映射到 (head + i) % buffer.len。两端 pushFront/pushBack/popFront/popBack 都是 O(1) 且不搬元素,这正是 ArrayList 做不到的——在数组头部插入要整体后移。
0.16 新增的 initBuffer(buffer: []T) 让它完全不需要分配器:把栈上数组交给它即可。源码明确警告:用 initBuffer 构造后,任何带 Allocator 参数的方法都是非法行为;必须改用 pushBackBounded / pushFrontBounded 等 Bounded 版本,容量不足时返回 error.OutOfMemory。
视频最后一节「保留最后几项」就是滑动窗口:满了先 popFront() 再 pushBackBounded()。下例还演示两端混用与迭代器:
const std = @import("std");
pub fn main() !void {
// 栈上环形缓冲:initBuffer 不碰分配器,容量就是数组长度。
var backing: [4]u32 = undefined;
var window = std.Deque(u32).initBuffer(&backing);
// 保留最后 4 项:满了就从另一端挤掉一个,典型的滑动窗口。
for (1..8) |i| {
window.pushBackBounded(@intCast(i)) catch {
_ = window.popFront();
try window.pushBackBounded(@intCast(i));
};
}
std.debug.print("last 4:", .{});
for (0..window.len) |i| std.debug.print(" {d}", .{window.at(i)});
std.debug.print("\n", .{});
// 两端都能 O(1) 进出:先腾一个位置,再从前端插入。
_ = window.popBack();
try window.pushFrontBounded(0);
std.debug.print("after popBack+pushFront:", .{});
for (0..window.len) |i| std.debug.print(" {d}", .{window.at(i)});
std.debug.print("\n", .{});
// 迭代器按逻辑顺序走,不受环形回绕影响。
var it = window.iterator();
std.debug.print("iterator:", .{});
while (it.next()) |v| std.debug.print(" {d}", .{v});
std.debug.print("\n", .{});
std.debug.print("popFront={d} popBack={d} len={d}\n", .{
window.popFront().?, window.popBack().?, window.len,
});
}
0.17.1 实测通过
输入 1…7 后窗口是
4 5 6 7;popBack再pushFrontBounded(0)得0 4 5 6;迭代器按逻辑顺序输出0 4 5 6(不受环形回绕影响);最后popFront=0 popBack=6 len=2。全程零堆分配。
28.4 四种线性容器怎么选
| 容器 | 擅长 | 代价 / 限制 |
|---|---|---|
ArrayList(T) | 尾部追加、随机访问、连续内存 | 头部插入 O(n);增长会搬移元素(第 19 章) |
Deque(T) | 两端 O(1) 进出、滑动窗口、BFS / 撤销栈 | 逻辑连续不等于物理连续;at() 需取模;扩容要处理回绕 |
PriorityQueue(T, C, f) | 每次取最小 / 最大 | 只能看一端;遍历顺序不是优先级顺序;popIndex 后堆会重排 |
PriorityDequeue(T, C, f) | 同时要 popMin 与 popMax(如双端堆) | 结构更复杂,单端需求别用它 |
陷阱清单
①
initBuffer的对象调用带gpa的方法 → 未定义行为;② 把iterator()的输出当成优先级顺序(源码明确说「不是优先级顺序,且堆一改就失效」);③compareFn返回.eq过于宽松,导致update定位错元素;④Deque扩容后元素指针失效,和 ArrayList 一样(见第 19 章的lockPointers)。
小结 两种「排队」对应两种顺序来源:优先级来自比较函数 + 状态,双端队列的次序来自插入方向。前者要格外小心状态可变,后者的价值在于把头部操作从 O(n) 变成 O(1),并且可以整块放在栈上。
29 面向数据设计实战:五个技巧与一次实测
对应视频《Zig 作者带你用面向数据设计 (DoD) 编程构建高性能应用》(BV1o7hx6yEL4,原演讲 Andrew Kelley A Practical Guide to Applying Data Oriented Design,2024-07-13,约 93 分钟)。核心命题:逻辑已经精简,程序仍慢,瓶颈往往不在指令数,而在内存怎么摆。
学习目标
- 用缓存行与「每次遍历触碰的字节数」解释 AoS 为什么慢
- 掌握五个结构体瘦身技巧,并知道各自省下的是什么
- 独立设计一次可复现的 AoS / SoA 对照测量
- 判断什么时候 DoD 重构不值得做
29.1 内存墙:慢的不是 CPU,是等数据
现代 CPU 一个周期能执行多条算术指令,而一次主存访问往往要几百个周期。缓存以 64 字节的缓存行为单位搬运:你只读 4 字节,硬件也会把相邻 64 字节一起取来。于是顺序遍历连续数组非常划算——取一次,用十六次;而「每个对象 112 字节、只用其中 4 字节」意味着大部分带宽和缓存容量被永远用不上的字段占掉,还可能因为指针追逐让预取器失效。
这正是 Andrew 在 Zig 编译器重构里反复强调的视角转换:不要先问「对象有哪些属性」,先问「最热的循环每次要读什么」。OOP 把属性绑在对象上,DoD 把访问模式绑在数据布局上。第 21 章讲了 MultiArrayList 这个工具,本章讲的是用它之前的判断过程。
29.2 五个立竿见影的技巧
| # | 技巧 | 做法 | 省下 / 换来的 | 本手册 |
|---|---|---|---|---|
| 1 | 用索引替代指针 | 节点里存 u32 下标而不是 *Node | 64 位指针 8 字节 → 4 字节;整块数据可搬移、可序列化、可跨进程 | 第 31 章 |
| 2 | 布尔值外置 | 把 bool 从对象里拿出来,用独立的位集(每对象 1 bit) | 结构体里一个 bool 常因对齐吃掉 4–8 字节;1 亿对象省下几百 MB | 本章 / 第 22 章 |
| 3 | SoA:一列一个数组 | MultiArrayList 或手写的 xs: []f32 | 只把热字段读进缓存;单字段向量化更容易(第 25 章) | 第 21 章 |
| 4 | 热 / 冷拆分 | 把 name、notes 这类冷字段移到旁路数组,按需加载 | 热循环的对象从 112 字节缩到十几字节,缓存行里全是有效数据 | 本章实测 |
| 5 | 上下文特定编码 | 用 u4/u12、位段、哨兵值、标签高位把状态挤进已有字段 | 不再为「是否为空」「属于哪类」多开一个字;Zig 的任意位宽整数让它是零成本抽象 | 第 32 章 |
与第 21 章的分工
第 21 章回答「
MultiArrayList的 API 怎么用、字段枚举为什么是编译期的」;本章回答「该不该改、先改哪一块、改完怎么量」。工具是布局,方法论是测量——没有测量就换 SoA,往往只是把复杂度搬了个地方。
29.3 一次可复现的对照测量
下例构造 100 万个对象,只做一件事:累加 x。AoS 版本每个元素含 id、标志、x/y、tag、24 字节 name、64 字节 notes;SoA 版本只留 []f32 x。两段循环的输入值、迭代次数、累加顺序完全一致,结果都被打印出来防止被优化掉,计时用 0.17 的 std.Io.Clock.awake(显式注入 init.io,与第 24 章的 Io 心智模型一致)。
const std = @import("std");
const N = 1_000_000;
// 胖结构体:冷数据、布尔标志、名字全都跟着热字段一起被搬进缓存。
const Fat = struct {
id: u64,
active: bool,
x: f32,
y: f32,
tag: u8,
name: [24]u8,
notes: [64]u8,
};
// 瘦身后的热结构体:只留遍历真正要用的字段。
const Hot = struct { id: u32, x: f32, y: f32, tag: u8 };
fn sumAos(items: []const Fat) f32 {
var s: f32 = 0;
for (items) |it| s += it.x;
return s;
}
fn sumSoa(xs: []const f32) f32 {
var s: f32 = 0;
for (xs) |x| s += x;
return s;
}
pub fn main(init: std.process.Init) !void {
const io = init.io;
const gpa = std.heap.page_allocator;
const aos = try gpa.alloc(Fat, N);
defer gpa.free(aos);
const xs = try gpa.alloc(f32, N);
defer gpa.free(xs);
@memset(std.mem.sliceAsBytes(aos), 0);
for (aos, 0..) |*p, i| {
p.x = @floatFromInt(i % 97);
xs[i] = p.x;
}
const t0 = std.Io.Clock.awake.now(io);
const s1 = sumAos(aos);
const t1 = std.Io.Clock.awake.now(io);
const s2 = sumSoa(xs);
const t2 = std.Io.Clock.awake.now(io);
const aos_us = t0.durationTo(t1).toMicroseconds();
const soa_us = t1.durationTo(t2).toMicroseconds();
std.debug.print("@sizeOf(Fat)={d} @sizeOf(Hot)={d} bytes\n", .{ @sizeOf(Fat), @sizeOf(Hot) });
std.debug.print("AoS bytes touched = {d} MB, SoA = {d} MB\n", .{
(@sizeOf(Fat) * N) / (1024 * 1024), (@sizeOf(f32) * N) / (1024 * 1024),
});
std.debug.print("AoS sum={d} {d}us | SoA sum={d} {d}us | ratio={d:.2}x\n", .{
s1, aos_us, s2, soa_us, @as(f64, @floatFromInt(aos_us)) / @as(f64, @floatFromInt(soa_us)),
});
}
@sizeOf(Fat)=112 @sizeOf(Hot)=16 bytes
AoS bytes touched = 106 MB, SoA = 3 MB
AoS sum=47677184 10261us | SoA sum=47677184 2436us | ratio=4.21x
0.17.1 实测结果
@sizeOf(Fat)=112、@sizeOf(Hot)=16;AoS 触碰约 106 MiB,SoA 约 3 MiB。本机 Debug 模式多次运行,AoS 在 10–16 ms、SoA 稳定在 2.3–2.4 ms,比值 4–7 倍。两次累加的和都是47677184,说明差异来自内存访问而非计算。请把比值当成「本机本配置下的观察」,换机器、换优化模式、换数据量都要重测(代码按 1024² 计算,输出里标注的 MB 实为 MiB)。
为什么 SoA 只是 4 倍而不是 35 倍?因为顺序访问下硬件预取会隐藏一部分延迟,且 Debug 模式的循环本身有安全检查开销。这恰好说明 DoD 是工程学而非玄学:收益取决于访问模式、对象大小、缓存容量和优化级别,必须用同一份数据、同一台机器量出来。
29.4 测量纪律与「不值得改」的信号
- 先量再改:先写对照程序,记录基线;只改一个变量(布局),其它全不动。
- 结果必须被消费:把和打印出来,否则优化器可能把整段循环删掉。
- 分别跑 Debug 与 ReleaseFast(0.17 是
-Doptimize=fast,见第 26 章);Debug 看安全开销,Release 看向量化收益。 - 控制缓存预热与样本量:跑到毫秒级以上,多跑几次取范围,不要拿单次最小值当结论。
- 量全链路:如果瓶颈在解析、I/O 或系统调用(第 25 章的 CSV 案例),把结构体缩小 10 倍也不会改变总耗时。
| 不值得做 DoD 重构的信号 | 原因 |
|---|---|
| 元素只有几百个,且整体已装进 L1/L2 | 缓存本来就命中,布局优化没有可省的带宽 |
| 每次遍历几乎要读全部字段 | SoA 只是把一次连续访问拆成几次,反而多了索引计算 |
| 访问以随机单点为主、且必须同时取多个字段 | SoA 会造成多次独立 cache miss |
| 数据结构频繁增删改、需要稳定地址 | 先解决所有权与失效(第 19、31 章),别急着改布局 |
小结 DoD 的五个技巧本质上是同一件事:让热循环读到的每个字节都有用。索引替指针解决「读什么」,布尔外置与上下文编码解决「读几位」,热冷拆分与 SoA 解决「一次搬多少」。而判断依据永远是一次控制变量的实测。
30 取消:并发里最痛的那一块
对应视频《Zig 之父 Andrew Kelley:拆解并发编程中最痛苦的难题——取消 / 终止任务》(BV1HbpC6QEBK,原演讲 Getting Canceled,Zig SHOWTIME 2026-10-13,约 94 分钟)。主题从单核的硬件定时器中断、缓存争用、阿姆达尔定律,一路走到 EINTR、musl 汇编里的 PC 处理,以及跨平台鲁棒的线程取消。
学习目标
- 用阿姆达尔定律解释「加核心为什么不线性加速」,并指出串行部分的来源
- 区分异步取消 / 延迟取消 / 协作取消,说明 EINTR 与取消点的关系
- 读懂 0.17
std.Io.Cancelable、checkCancel、recancel、CancelProtection与Group.cancel- 写出取消路径也归还资源、不吞信号的协议
30.1 从硬件定时器中断到阿姆达尔定律
「并发」最初并不是多核:单核 CPU 靠硬件定时器中断周期性把控制权交回内核,内核保存程序计数器与寄存器、换上另一个任务的上下文,于是多个任务看起来在同时前进。这套机制也是后来「取消」的物理根源——一个执行流可以被外部事件打断,被打断时它正停在某条指令边界上。
多核带来真并行,也带来两个上限:一是多个核心争用同一缓存行(false sharing 与缓存一致性流量),二是阿姆达尔定律。设可并行部分占比 p、核心数 N,加速比上限为:
S(N) = 1 / ( (1 - p) + p / N ) S(∞) = 1 / (1 - p)
| 可并行占比 p | N=2 | N=4 | N=8 | N=16 | N→∞ |
|---|---|---|---|---|---|
| 0.50 | 1.33× | 1.60× | 1.78× | 1.88× | 2.00× |
| 0.90 | 1.82× | 3.08× | 4.71× | 6.40× | 10.0× |
| 0.99 | 1.98× | 3.88× | 7.48× | 13.9× | 100× |
串行部分 1-p 里,除了算法本身的顺序依赖,还包括同步、资源初始化与清理、以及取消协调。所以「取消做得粗糙」不只是正确性问题,它会实打实地把并行加速比压下去。
30.2 三种取消模型、EINTR 与取消点
| 模型 | 语义 | 典型问题 |
|---|---|---|
| 异步 / 强制取消 | 在任意指令边界把线程掐断(如 pthread_cancel 的异步模式) | 可能停在持锁中途、分配了一半、写到一半;资源与不变量无法恢复 |
| 延迟取消 | 请求只置位,线程到达取消点(通常是阻塞的系统调用)时才退出 | 取消点太多/太少的取舍;纯计算任务可能长时间不响应 |
| 协作取消 | 任务自己定期检查显式请求,返回 error.Canceled | 需要每个长任务都写检查点,且不能吞掉错误;换来可预测的清理路径 |
演讲里最「底层」的一段是 EINTR:阻塞中的系统调用被信号打断后返回 EINTR,很多代码把它当成真实错误直接退出。正确做法要区分调用尚未产生副作用(可以重启)与已经读/写了一部分数据(必须把已完成的进度交还调用者)。musl libc 在汇编层保存和恢复程序计数器、处理信号掩码,正是为了让「被打断的那一刻」能被精确描述。Zig 标准库没有依赖某个完美底层原语,而是用显式取消点 + 可取消错误集把这件事统一到语言层面。
30.3 0.17 的落地:Cancelable、取消点与 Group.cancel
0.17.1 的 lib/std/Io.zig 把取消做成接口的一部分而不是散落的标志位:
| API / 字段 | 含义(依据 0.17.1 源码) |
|---|---|
std.Io.Cancelable = error{Canceled} | 所有可取消操作的统一错误集;函数签名里出现它,等于告诉调用者「我可能中途退出」 |
vtable.cancel / recancel / checkCancel | 发起请求、重新武装已消费的请求、主动查询请求 |
vtable.swapCancelProtection / CancelProtection | 临界区暂时屏蔽取消通知,出来后再观察 |
futexWait / futexWaitUncancelable | 同一个等待操作给出可取消与不可取消两个版本,避免「取消到一半的锁」 |
Future.cancel(io) | 等价于 await,但先发取消请求;任务在下一个取消点得到 error.Canceled |
Group.cancel(io) | 向组内所有成员传播取消,并保证所有任务都运行完、资源归还;幂等、非线程安全 |
源码注释里最容易被忽略的一句
Future.cancel的注释明确写道:一次取消请求只有下一个取消点会返回error.Canceled,后续取消点不会重复报告;因此「忽略error.Canceled通常是 bug」。要延后处理就用recancel或CancelProtection。这条规则决定了下面的代码为什么那样写。
先用一段纯逻辑把协作取消的状态机讲清楚——请求置位、单次消费、defer 归还、吞掉信号的后果,以及 recancel:
const std = @import("std");
const Canceled = error{Canceled};
// 一个最小的协作式取消令牌:请求只是「置位」,任务只在取消点观察它。
const Token = struct {
cancel_at: ?u32 = null,
armed: bool = true,
fn request(self: *Token, step: u32) void {
self.cancel_at = step;
}
fn check(self: *Token, step: u32) Canceled!void {
if (self.cancel_at) |n| {
// 一次请求只在「下一个」取消点生效;之后不再重复报 Canceled。
if (step >= n and self.armed) {
self.armed = false;
return error.Canceled;
}
}
}
fn recancel(self: *Token) void {
self.armed = true;
}
};
fn worker(token: *Token, held: *u8, steps: *u32) Canceled!void {
held.* += 1; // 借用资源
defer held.* -= 1; // 正常返回 / 取消返回,两条路径都归还
var i: u32 = 0;
while (i < 100) : (i += 1) {
try token.check(i); // 取消点
steps.* += 1;
}
}
pub fn main() !void {
var held: u8 = 0;
var steps: u32 = 0;
var normal: Token = .{};
if (worker(&normal, &held, &steps)) |_| {
std.debug.print("normal: steps={d} held={d}\n", .{ steps, held });
} else |e| {
std.debug.print("unexpected {s}\n", .{@errorName(e)});
}
var canceling: Token = .{};
canceling.request(10);
held = 0;
steps = 0;
if (worker(&canceling, &held, &steps)) |_| {
std.debug.print("no cancellation happened\n", .{});
} else |e| {
std.debug.print("canceled: {s} at step {d}, held={d} (defer ran)\n", .{
@errorName(e), steps, held,
});
}
// 吞掉 error.Canceled 是 bug:信号已被消费,后面的取消点不再触发。
var swallowed: Token = .{};
swallowed.request(10);
var observed: u32 = 0;
for (0..20) |i| {
swallowed.check(@intCast(i)) catch {};
observed += 1;
}
std.debug.print("swallowed: ran {d} steps (should have stopped at 10)\n", .{observed});
// recancel 把请求重新武装,交给下一个取消点。
swallowed.recancel();
if (swallowed.check(20)) |_| {
std.debug.print("recancel: missed\n", .{});
} else |e| {
std.debug.print("recancel: {s} at the next checkpoint\n", .{@errorName(e)});
}
}
normal: steps=100 held=0
canceled: Canceled at step 10, held=0 (defer ran)
swallowed: ran 20 steps (should have stopped at 10)
recancel: Canceled at the next checkpoint
再换成 0.17 真实的 std.Io:任务在循环里定期 checkCancel,主流程先让它跑一会儿再 group.cancel,并用 defer 在任务里放一个「清理已执行」的标记:
const std = @import("std");
// 任务在每个取消点主动检查请求;返回值必须允许 error.Canceled。
fn work(io: std.Io, progress: *std.atomic.Value(u32)) std.Io.Cancelable!void {
defer _ = progress.fetchAdd(1000, .monotonic); // 清理标记:取消也要执行
var i: u32 = 0;
while (i < 20_000_000) : (i += 1) {
if (i % 100_000 == 0) try std.Io.checkCancel(io);
_ = progress.fetchAdd(1, .monotonic);
}
}
pub fn main(init: std.process.Init) !void {
const io = init.io;
var progress: std.atomic.Value(u32) = .init(0);
var group: std.Io.Group = .init;
try group.concurrent(io, work, .{ io, &progress });
// 给任务一点时间跑过若干取消点,再发出取消请求。
try std.Io.sleep(io, .fromMilliseconds(3), .awake);
group.cancel(io); // 请求取消,并等待组内所有任务归还资源
const value = progress.load(.monotonic);
std.debug.print("progress after cancel = {d}\n", .{value});
std.debug.print("cleanup defer ran = {}\n", .{value >= 1000});
}
0.17.1 实测通过
纯逻辑版输出:
normal: steps=100 held=0;canceled: Canceled at step 10, held=0 (defer ran);吞掉错误后swallowed: ran 20 steps(本该在 10 停下);recancel之后下一个检查点重新报Canceled。真实 Io 版单次运行得到progress after cancel = 2101000、cleanup defer ran = true——任务做了一部分工作后被取消,清理照常执行(具体步数取决于机器调度)。
30.4 取消协议的正确性清单
| # | 规则 | 违反时的现象 |
|---|---|---|
| 1 | 每个可能长时间运行的操作都要有取消点,且返回值允许 error.Canceled | 关闭服务时卡死,只能强杀进程 |
| 2 | 用 defer / errdefer 归还资源,两条返回路径共用一套清理 | 锁未释放、临时文件残留、连接泄漏(第 9、16 章) |
| 3 | 不要吞掉 error.Canceled;确实要延后就用 recancel | 取消信号被消费后任务一路跑到底 |
| 4 | 取消操作要幂等:Group.cancel 可重复调用,自定义清理也不能重复释放 | 双重释放、计数器减成负数 |
| 5 | 不可打断的临界区用 CancelProtection,出来后立刻检查 | 数据结构停在半更新状态 |
| 6 | 区分「还没开始」与「已经做了一部分」,返回已完成的进度 | 重启请求时重复消费 / 丢数据,就是 EINTR 的老问题 |
| 7 | 取消要能传播:父任务取消时子任务与 Group 成员都收到 | 后台任务变成孤儿,进程无法干净退出 |
小结 取消之所以是「并发中最痛苦的难题」,是因为它同时要求及时(取消点足够密)、安全(资源必须归还)、可预测(状态不能停在半途)。Zig 0.17 的选择是把取消做成
Io接口里的显式能力:Cancelable是错误集,取消点是代码里的显式检查,defer是清理的保证。和第 24 章的显式 Io 一样——不靠运行时魔法,靠签名和协议说话。
31 无指针数据结构:索引、句柄与可重定位内存
对应视频《Zig 创始人 Andrew Kelley:为什么我不建议数据结构里继续用指针(无指针编程)》(BV1ykhx6tEjf,约 10 分钟);同时是第 29 章「技巧 1」的展开。该视频 B 站简介为空,本章依据演讲主题、Zig 0.17.1 源码与编译实测重构。
学习目标
- 列出在数据结构内部保存指针的四个具体代价
- 用
u32索引 + sentinel 实现可增长的链表 / 树节点- 用世代句柄(generational handle)防止槽位复用后的 ABA 问题
- 判断哪些场景必须保留真实指针
31.1 指针在数据结构内部的四个代价
| 代价 | 具体表现 | 关联章节 |
|---|---|---|
| 体积 | 64 位平台一个指针 8 字节;struct { i32, *Node } 因对齐实际 16 字节,而索引版只要 8 字节 | 第 29、32 章 |
| 失效 | 容器增长会搬移元素,所有指向元素的指针瞬间悬垂;删除后地址可能被复用 | 第 19 章 |
| 不可搬移 / 不可序列化 | 一块含指针的内存不能 memcpy 到别处、写进文件、发给 GPU 或另一个进程——地址在新环境里没有意义 | 第 29 章 |
| 缓存与所有权 | 顺着指针跳转是随机访问,预取器帮不上忙;同时「谁拥有这块内存」在类型里完全看不出来 | 第 04 章 |
Zig 没有 GC,也不会替你延长对象寿命,所以「存指针」比在有 GC 的语言里更需要承担后果。Andrew 的建议不是「永远别用指针」,而是:在数据结构内部表达关系时,优先用整数索引;指针只用于短命的借用与外部接口。
31.2 索引 + sentinel:可搬移的链表与槽表
把 next: *Node 换成 next: u32,用一个保留值(这里是 maxInt(u32))表示空。节点数组可以自由增长、整体 memcpy、按字节写盘,索引值不会因为搬家而改变。下例把链表、槽表、世代句柄放在一个程序里:
const std = @import("std");
// 索引代替指针:节点里存的是数组下标,不是地址。
const none = std.math.maxInt(u32);
const Node = struct { value: i32, next: u32 };
// 同样的链表,用真实指针表达链接关系。
const PtrNode = struct { value: i32, next: ?*PtrNode };
// 世代句柄:删除复用槽位后,旧句柄因为 generation 过期而失效(防 ABA)。
const Handle = packed struct { index: u20, generation: u12 };
const Slot = struct { value: i32, generation: u12 = 0, occupied: bool = false };
const Store = struct {
slots: std.ArrayList(Slot) = .empty,
fn deinit(self: *Store, gpa: std.mem.Allocator) void {
self.slots.deinit(gpa);
}
fn insert(self: *Store, gpa: std.mem.Allocator, value: i32) !Handle {
for (self.slots.items, 0..) |*slot, i| {
if (!slot.occupied) {
slot.* = .{ .value = value, .generation = slot.generation +% 1, .occupied = true };
return .{ .index = @intCast(i), .generation = slot.generation };
}
}
try self.slots.append(gpa, .{ .value = value, .occupied = true });
return .{ .index = @intCast(self.slots.items.len - 1), .generation = 0 };
}
fn get(self: *const Store, h: Handle) ?i32 {
if (h.index >= self.slots.items.len) return null;
const slot = self.slots.items[h.index];
if (!slot.occupied or slot.generation != h.generation) return null;
return slot.value;
}
fn remove(self: *Store, h: Handle) bool {
if (h.index >= self.slots.items.len) return false;
const slot = &self.slots.items[h.index];
if (!slot.occupied or slot.generation != h.generation) return false;
slot.occupied = false;
return true;
}
};
pub fn main() !void {
const gpa = std.heap.page_allocator;
var store: Store = .{};
defer store.deinit(gpa);
const h1 = try store.insert(gpa, 42);
std.debug.print("h1 = index {d} gen {d} -> {?}\n", .{ h1.index, h1.generation, store.get(h1) });
// 强制 ArrayList 多次扩容搬移:索引不变,指针早就悬垂了。
for (0..1000) |i| _ = try store.insert(gpa, @intCast(i));
std.debug.print("after 1000 inserts (slots.len={d}): h1 -> {?}\n", .{
store.slots.items.len, store.get(h1),
});
// 索引即链接:next 是 u32,整块数据可以直接 memcpy / 写盘 / 发给 GPU。
const nodes = [_]Node{
.{ .value = 10, .next = 1 },
.{ .value = 20, .next = 2 },
.{ .value = 30, .next = none },
};
const bytes = std.mem.asBytes(&nodes);
std.debug.print("3 nodes = {d} bytes | @sizeOf(Node)={d} vs pointer node={d}, @sizeOf(*Node)={d}\n", .{
bytes.len, @sizeOf(Node), @sizeOf(PtrNode), @sizeOf(*Node),
});
var cursor: u32 = 0;
while (cursor != none) : (cursor = nodes[cursor].next) {
std.debug.print("node[{d}]={d} ", .{ cursor, nodes[cursor].value });
}
std.debug.print("\n", .{});
// 删除后复用同一槽位,旧句柄失效。
std.debug.print("remove(h1)={}\n", .{store.remove(h1)});
const h2 = try store.insert(gpa, 99);
std.debug.print("h2 = index {d} gen {d} -> {?}; stale h1 -> {?}\n", .{
h2.index, h2.generation, store.get(h2), store.get(h1),
});
}
h1 = index 0 gen 0 -> 42
after 1000 inserts (slots.len=1001): h1 -> 42
3 nodes = 24 bytes | @sizeOf(Node)=8 vs pointer node=16, @sizeOf(*Node)=8
node[0]=10 node[1]=20 node[2]=30
remove(h1)=true
h2 = index 0 gen 1 -> 99; stale h1 -> null
0.17.1 实测输出解读
@sizeOf(Node)=8,指针版节点16字节(指针本身 8 字节);3 个节点共 24 字节,可直接std.mem.asBytes取字节视图。连续插入 1000 次让ArrayList多次扩容搬移后,最早的句柄h1依然读到42——同样的代码若保存*Slot早就悬垂了。
31.3 世代句柄:解决槽位复用的 ABA
纯索引有一个漏洞:删除槽位 0 后又插入新对象,旧索引 0 会「意外地」指向新对象(ABA 问题)。解决办法是把句柄拆成两段:index 定位槽位,generation 记录这是第几代 occupant。每次复用槽位就递增 generation,读取时两者必须同时匹配。
示例里 Handle = packed struct { index: u20, generation: u12 }:20 位索引支持约 100 万个槽位,12 位世代支持 4096 次复用,整个句柄仍然是一个 u32。这正是第 32 章「任意位宽整数 + packed struct」的用武之地。实测:h1 = index 0 gen 0,删除并复用后 h2 = index 0 gen 1 -> 99,而旧的 h1 -> null。
| 设计参数 | 取值影响 | 风险 |
|---|---|---|
| index 位宽 | 决定最大槽位数;u20 ≈ 1M,u32 ≈ 4G | 溢出时 @intCast 会 panic(Debug)或出错,需显式检查 |
| generation 位宽 | 决定同一槽位可安全复用多少次 | 回绕后旧句柄可能重新变「有效」;热槽位用 u32 或永不复用 |
| 空闲槽管理 | 线性扫描 O(n) 或另建 free list(也是索引) | 示例为了可读性用线性扫描,生产代码用空闲索引栈 |
| 哨兵 / 空值 | maxInt(u32) 或 0 保留给「无」 | 别把合法索引 0 当成空,除非全体下标从 1 开始 |
31.4 什么时候还是要用指针
- 外部所有权 / C API:操作系统、第三方库、
extern函数要的就是地址,无法用索引替代。 - 短命借用:函数参数里的
*T/[]T表达「我只在这次调用里看一眼」,调用结束即失效,正是 Zig 的惯用法。 - 地址必须稳定:某些 OS 对象(线程栈、mmap 区域、DMA 缓冲)要求物理/虚拟地址不变。
- 异构数据:标签联合、虚函数表、
*anyopaque这类需要运行时多态的地方,索引表反而更绕。
陷阱清单
① 索引存进了容器,却又长期保存
&items[i]的指针;② 忘记ArrayList增长/删除会让索引对应的元素内容变化(swapRemove会把末元素换过来),索引并非「对象身份」;③ 世代溢出回绕;④ 把索引当成跨进程的全局 ID——它是相对于某个容器实例的,序列化时必须连容器一起存。
小结 无指针编程换来三样东西:更小的节点、不会失效的引用、以及整块内存可以自由搬移和持久化。代价是要自己维护索引空间与世代。判断标准很简单:**这个引用要活过一次容器扩容吗?要离开当前进程吗?**两个问题有一个回答「是」,就该用索引而不是指针。
32 内存布局:Zig 比 C 多给了什么
对应视频《Zig 内存布局优于 C》(BV1mmxc6JEqV,原视频 Code Guild,2026-10-29,约 9:47):数学原理 → 对齐规则 → 调试 → 完全控制(IPv4)→ C 位域问题 → C23 → 为什么有 131071 种类型。
学习目标
- 解释 131071 这个数字的来源,以及
i0为什么不算- 区分普通 struct / extern struct / packed struct 的布局保证
- 说清 packed struct「字段无空洞」与「整体大小等于位宽」不是一回事
- 写出 in-memory 布局与网络线格式之间正确的转换代码
32.1 131071 种整数类型:不是炫技,是位级控制
C 只提供 8/16/32/64 位等少数宽度,遇到 3 位标志、12 位片偏移、20 位索引只能手写 mask / shift。Zig 允许任意位宽:u0 到 u65535 共 65536 种无符号类型,i1 到 i65535 共 65535 种有符号类型,合计 131071。
为什么有符号少一种?本机 0.17.1 实测:@bitSizeOf(u0) = 0 成立(唯一值就是 0),而写 i0 编译器直接报 signed integer cannot have bit width 0——零位补码整数没有符号位,不构成合法类型。@bitSizeOf(u65535) = 65535 也验证了这个上限。
这些类型不是给业务变量用的,而是给 packed struct、位集、硬件寄存器和协议字段用的:编译器照常做编译期与运行期溢出检查,赋值 u4 一个 16 在 Debug 下会 panic,而不是悄悄截断。这是「安全与控制并存」的具体含义。
32.2 三种 struct,三种完全不同的保证
| 写法 | 布局保证 | 用途 | 0.17.1 实测(a:u8, b:u64, c:u16) |
|---|---|---|---|
struct | 不保证字段顺序,编译器可重排以最小化 padding | 纯 Zig 内部数据;用字段名访问 | size=16 align=8,offsets a=10 b=0 c=8 |
extern struct | 按声明顺序 + C ABI 对齐规则 | 与 C 库互操作、共享内存 | size=24 align=8,offsets a=0 b=8 c=16 |
packed struct | 字段按位紧邻,可指定 backing 整数 | 协议位域、硬件寄存器、紧凑编码 | @bitOffsetOf 连续;见下节边界 |
普通 struct 的 16 字节对比 extern struct 的 24 字节,是「Zig 布局优于 C」最实在的一层:C 必须遵守声明顺序,于是 a 后面塞 7 字节 padding;Zig 把 b 放到偏移 0,a/c 挤进尾部,省下 8 字节。代价是你不能用 @offsetOf 的结果推断内存格式,也不能把普通 struct 直接 @bitCast 成字节数组做持久化(第 31 章的索引数组恰恰是安全的,因为它没有 padding)。
32.3 关键修正:packed 保证「字段间无空洞」,不保证「整体恰好等于位宽」
视频强调「内存无 Padding、精确到每一个 Bit」,这话对字段之间成立,但容易让人误解成「160 位的报头就占 20 字节」。0.17.1 实测不是这样。下面这个探针把不同位宽的结果摆在一起:
const std = @import("std");
const P8 = packed struct { a: u4, b: u4 };
const P16 = packed struct { a: u4, b: u4, c: u8 };
const P20 = packed struct { a: u20 };
const P64 = packed struct { a: u32, b: u32 };
const P128 = packed struct { a: u64, b: u64 };
const P160 = packed struct { a: u32, b: u32, c: u32, d: u32, e: u32 };
const P160Fixed = packed struct(u160) { a: u32, b: u32, c: u32, d: u32, e: u32 };
const Ipv4 = packed struct(u160) {
version: u4,
ihl: u4,
dscp: u6,
ecn: u2,
total_length: u16,
identification: u16,
flags: u3,
fragment_offset: u13,
ttl: u8,
protocol: u8,
checksum: u16,
src: u32,
dst: u32,
};
pub fn main() !void {
std.debug.print("bits=8 size={d} align={d}\n", .{ @sizeOf(P8), @alignOf(P8) });
std.debug.print("bits=16 size={d} align={d}\n", .{ @sizeOf(P16), @alignOf(P16) });
std.debug.print("bits=20 size={d} align={d} bitSize={d}\n", .{ @sizeOf(P20), @alignOf(P20), @bitSizeOf(P20) });
std.debug.print("bits=64 size={d} align={d}\n", .{ @sizeOf(P64), @alignOf(P64) });
std.debug.print("bits=128 size={d} align={d}\n", .{ @sizeOf(P128), @alignOf(P128) });
std.debug.print("bits=160 auto size={d} align={d}\n", .{ @sizeOf(P160), @alignOf(P160) });
std.debug.print("bits=160 fixed size={d} align={d} bitSize={d}\n", .{
@sizeOf(P160Fixed), @alignOf(P160Fixed), @bitSizeOf(P160Fixed),
});
std.debug.print("Ipv4(u160) size={d} align={d} bitOffset(dst)={d}\n", .{
@sizeOf(Ipv4), @alignOf(Ipv4), @bitOffsetOf(Ipv4, "dst"),
});
var h: Ipv4 = .{
.version = 4, .ihl = 5, .dscp = 0, .ecn = 0,
.total_length = std.mem.readInt(u16, &[_]u8{ 0x00, 0x34 }, .big),
.identification = 0x1234, .flags = 0, .fragment_offset = 0,
.ttl = 64, .protocol = 6, .checksum = 0,
.src = 0xC0A80101, .dst = 0x08080808,
};
const raw = std.mem.asBytes(&h);
std.debug.print("raw[0..4] = {x:0>2} {x:0>2} {x:0>2} {x:0>2}\n", .{
raw[0], raw[1], raw[2], raw[3],
});
h.ecn = 3;
std.debug.print("after ecn=3, raw[1] = {x:0>2}\n", .{std.mem.asBytes(&h)[1]});
// 位域取指针:只有落在可寻址边界上的字段才允许。
const p_total = &h.total_length;
std.debug.print("&h.total_length = {d}\n", .{p_total.*});
}
bits=8 size=1 align=1
bits=16 size=2 align=2
bits=20 size=4 align=4 bitSize=20
bits=64 size=8 align=8
bits=128 size=16 align=16
bits=160 auto size=32 align=16
bits=160 fixed size=32 align=16 bitSize=160
Ipv4(u160) size=32 align=16 bitOffset(dst)=128
raw[0..4] = 54 00 34 00
after ecn=3, raw[1] = c0
&h.total_length = 52
0.17.1 实测修正
160 位的
packed struct:bitSize=160,但size=32 align=16;显式写成packed struct(u160)也一样是 32 字节。字段位偏移(src=96、dst=128)连续,说明浪费来自尾部 backing 整数的存储与对齐,不是字段之间的 padding。所以「位精确」应理解为:字段位置确定且紧邻,而对象大小由 backing 整数决定。
另一个 0.17 细节:packed 位域可以取指针,但类型不是普通指针。实测把 &h.total_length 赋给 *align(1) u16 会报错,编译器给出的实际类型是 *align(16:16:20) u16——一个携带宿主大小与位偏移的「位指针」,不能随便传给期待普通指针的 C 函数。此外 0.17 的 @bitCast 已改为逻辑位语义(见附录 E),跨多字节重解释必须实测,不能照抄旧代码。
32.4 IPv4 报头:in-memory 布局 ≠ 线格式
把一个 20 字节 IPv4 报头写成 packed struct,字段声明可以完全照抄 RFC:version:u4, ihl:u4, dscp:u6, ecn:u2, total_length:u16, ...。但网络字节序是大端,本机 x86 是小端,实测内存前四字节是 54 00 34 00,而线上应该是 45 00 00 34。下例把两者都做出来:
const std = @import("std");
// 普通 struct:Zig 允许自由重排字段以消除 padding(布局不由源码顺序保证)。
const Naive = struct { a: u8, b: u64, c: u16 };
// extern struct:按 C ABI 声明顺序排布,用于和 C 互操作。
const Extern = extern struct { a: u8, b: u64, c: u16 };
// packed struct:字段按位紧邻;显式指定 backing 整数,便于核对边界。
const Ipv4Header = packed struct(u160) {
version: u4,
ihl: u4,
dscp: u6,
ecn: u2,
total_length: u16,
identification: u16,
flags: u3,
fragment_offset: u13,
ttl: u8,
protocol: u8,
checksum: u16,
src: u32,
dst: u32,
};
pub fn main() !void {
std.debug.print("Naive size={d} align={d} offsets a={d} b={d} c={d}\n", .{
@sizeOf(Naive), @alignOf(Naive), @offsetOf(Naive, "a"), @offsetOf(Naive, "b"), @offsetOf(Naive, "c"),
});
std.debug.print("Extern size={d} align={d} offsets a={d} b={d} c={d}\n", .{
@sizeOf(Extern), @alignOf(Extern), @offsetOf(Extern, "a"), @offsetOf(Extern, "b"), @offsetOf(Extern, "c"),
});
var h: Ipv4Header = .{
.version = 4,
.ihl = 5,
.dscp = 0,
.ecn = 0,
// 网络字节序是大端;赋值前把「线格式」的 00 34 转成主机整数 52。
.total_length = std.mem.readInt(u16, &[_]u8{ 0x00, 0x34 }, .big),
.identification = 0x1234,
.flags = 0,
.fragment_offset = 0,
.ttl = 64,
.protocol = 6,
.checksum = 0,
.src = 0xC0A80101,
.dst = 0x08080808,
};
std.debug.print("Ipv4Header bitSize={d} size={d} align={d} bitOffset(src)={d} dst={d}\n", .{
@bitSizeOf(Ipv4Header), @sizeOf(Ipv4Header), @alignOf(Ipv4Header),
@bitOffsetOf(Ipv4Header, "src"), @bitOffsetOf(Ipv4Header, "dst"),
});
var raw = std.mem.asBytes(&h);
std.debug.print("in-memory bytes = {x:0>2} {x:0>2} {x:0>2} {x:0>2} | version={d} ihl={d} total_length={d}\n", .{
raw[0], raw[1], raw[2], raw[3], h.version, h.ihl, h.total_length,
});
h.ecn = 3; // 直接改位域,不需要手写 mask / shift
raw = std.mem.asBytes(&h);
std.debug.print("after ecn=3, byte1 = {x:0>2} (bit fields really are bits)\n", .{raw[1]});
// 位域也能取指针,但类型是携带位偏移的「位指针」*align(16:16:20) u16,
// 不是普通的 *align(1) u16;两者之间不能随便赋值。
const p_total = &h.total_length;
std.debug.print("&h.total_length = {d}\n", .{p_total.*});
// 关键:in-memory 布局 ≠ 线格式。要精确 20 字节的大端报头,显式写字节缓冲。
var wire: [20]u8 = @splat(0);
wire[0] = (4 << 4) | 5;
std.mem.writeInt(u16, wire[2..4], @intCast(h.total_length), .big);
wire[8] = h.ttl;
wire[9] = h.protocol;
std.debug.print("wire bytes = {x:0>2} {x:0>2} {x:0>2} {x:0>2}, size={d}\n", .{
wire[0], wire[1], wire[2], wire[3], wire.len,
});
// 任意位宽整数:u0..u65535 共 65536 种,i1..i65535 共 65535 种,合计 131071。
// i0 不存在(编译器报 signed integer cannot have bit width 0),这正是 65535 而非 65536 的原因。
std.debug.print("bitSizeOf: u0={d} i1={d} u20={d} u65535={d} | types = {d}\n", .{
@bitSizeOf(u0), @bitSizeOf(i1), @bitSizeOf(u20), @bitSizeOf(u65535), 65536 + 65535,
});
}
Naive size=16 align=8 offsets a=10 b=0 c=8
Extern size=24 align=8 offsets a=0 b=8 c=16
Ipv4Header bitSize=160 size=32 align=16 bitOffset(src)=96 dst=128
in-memory bytes = 54 00 34 00 | version=4 ihl=5 total_length=52
after ecn=3, byte1 = c0 (bit fields really are bits)
&h.total_length = 52
wire bytes = 45 00 00 34, size=20
bitSizeOf: u0=0 i1=1 u20=20 u65535=65535 | types = 131071
| 对比项 | Zig | C |
|---|---|---|
| 位域宽度 | u1..u65535,编译期确定 | 只能用 int/unsigned 加 :N;宽度受底层类型限制 |
| 位域布局 | @bitOffsetOf 给出确定偏移 | 分配顺序、跨存储单元行为、字节序由实现定义 |
| 取地址 | 可以,得到携带位偏移的位指针 | 位域不能取地址 |
| 溢出检查 | 编译期 + 运行期安全构建会报错 | 静默截断 |
| 线格式控制 | 仍须显式 readInt/writeInt(..., .big) | 同样须 htons/ntohs,且位域不能直接映射 |
所以「Zig 内存布局优于 C」更准确的说法是:C 把一部分布局选择留给了编译器实现,Zig 让程序员显式选择并能在编译期验证。它并没有免除字节序转换,也没有让 packed struct 自动变成线格式。
32.5 决策清单
- 纯内部数据 → 普通
struct,别假设字段顺序,别拿它当字节流。 - 要与 C / 共享内存对接 →
extern struct,字段顺序和 padding 都按 ABI 来,用@offsetOf核对。 - 要位域、寄存器、紧凑编码 →
packed struct,用@bitOffsetOf与@bitSizeOf核对,位宽用任意整数。 - 要写网络/磁盘格式 → 显式字节缓冲 +
readInt/writeInt(.big 或 .little);packed struct 只当逻辑视图。 - 要跨版本持久化的布局 → 在测试里断言
@sizeOf/@offsetOf,编译器或目标平台一变就能立刻发现。
小结 本章把「布局」从一个模糊的编译器话题变成三份明确的契约:普通 struct 换空间、extern struct 换兼容性、packed struct 换位级确定性。配合任意位宽整数与
@sizeOf/@alignOf/@offsetOf/@bitOffsetOf四个编译期查询,Zig 让「我的数据到底长什么样」成为可测量、可断言、可写进测试的事实——这正是第 29 章 DoD 与第 31 章无指针设计能成立的地基。
附录 A 问答环节精要
| 问题 | 回答要点 |
|---|---|
| 能在一个程序里用多个 allocator 吗? | 能。同一个函数可用不同 allocator 调用多次;短命 CLI 常用 arena,长生命周期的服务按操作分别挑。 |
| 能像运行时反射那样动态查类型吗? | 基本不能。Zig 是编译型语言,运行时最多拿到指针;可以用 @fieldParentPtr 之类的惯用法自己搭 vtable,但没有动态转型、没有继承、没有 mixin / role,也不打算加。 |
| 和 C 集成怎么样? | 0.17 已移除 @cImport(见 12.1 第 4 条),改用外部 translate-c 包 / b.addTranslateC;Zig 本身还是 C/C++ 编译器与交叉编译器,SQLite 这类 C 库可以直接用。 |
| 从 Python / Perl 调 Zig 呢? | 走 FFI。动态语言的参数/结果包装开销会吃掉小调用的收益,适合把重计算整体丢给 Zig 再取回结果。 |
| 能自定义错误吗? | 能。return error.XXX 即用即定义,无需注册;!T 让编译器推导错误集合,也可显式写 error{...}!T。 |
| 安全性如何? | Zig 内置 fuzzer;编译模式决定安全检查是否保留(.debug / .safe 保留,.fast / .small 移除),演讲还提到社区关于 Fil-C 的讨论。 |
| 构建系统难不难? | 小项目很简单,复杂需求文档也够用;但 0.17 重构了构建进程模型,旧 build.zig 需要迁移。 |
| 有 1.0 吗?有 REPL 吗? | 都还没有。最大的一次变化是 0.16 引入 std.Io;0.17 对应用代码改动不大,但构建脚本是破坏性的。 |
过时提醒 · 结论修正
问答里「0.17 变化不大」「新版有 translator C 层」「release fast / debug 模式」三处,按 0.17 事实应分别补上:build.zig 破坏性迁移、
@cImport已彻底移除、优化模式改用小写.fast/.debug/.safe/.small。
附录 B 全部示例索引与运行方式
每段代码都是完整独立程序(含 @import("std") 与 main),把代码块保存为 .zig 文件即可运行:
zig run 01_hello.zig # 需要 init.io 的新入口
zig run 10_naive.zig # 手写配置解析
zig run 08_comptime.zig # comptime 通用解析
zig run 04_allocator.zig # 三种 allocator
zig test leak_test.zig # 泄漏检测(会打印 error log)
| 示例 | 对应章节 | 关键知识点 | 0.17.1 实测输出 |
|---|---|---|---|
| 01_hello | 00 | main(init)、std.Io.Writer、flush() | Hello, Zig 0.17! / 1 + 2 = 3 |
| 10_naive | 03 | 手写 if 链、parseInt / parseFloat / stringToEnum | port=9000 workers=8 timeout=1.5 log=warn tls=true |
| 04_allocator | 04 | .empty + append(gpa, x)、SafeAllocator、arena、FBA | 三种分配器各 2 adults |
| leak_test | 04 | std.testing.allocator 泄漏报告 | 1 errors were logged. |
| 02_optional | 05 | ?T、orelse 四种用法、if 捕获 | found: Grace (37) 等 5 行 |
| 03_errors | 06 | !T、try、穷尽 catch ... switch | port("8080") = 8080 等 |
| 05_tagged_union | 07 | union(enum)、点号推断、@tagName、{t} | tag = transfer, level = info |
| 06_multi_for | 08 | 多序列 for、0.. 无界 range | 三行 0: Ada is 36 等 |
| 07_defer | 09 | defer / errdefer、LIFO | success path → cleanup on error only |
| 08_comptime | 10 | comptime type、@typeInfo 平行数组、inline for、@field | Server / Client 两行 + rejected: UnknownKey |
| 09_simd | 11 | @Vector、@reduce | { 11, 22, 33, 44 } / 110 |
此外 verify/legacy/ 下的 8 个「过时写法」探针文件,在 0.17.1 上分别产生了 12.1 表中列出的真实报错。
附录 C 参考来源
- B 站视频《Zig:从设计哲学到核心特性的深度解析》BV1qB4p6fE7g,UP 主 myfreax,2026-11-08。
- 原始演讲 Zig: From Beginner to Slightly Less Beginner,Sawyer X,Code Maven,2026-10-29;本手册依据其完整英文转录(含问答)与公开演讲笔记整理。
- Zig 0.17.0 Release Notes(语言变更、标准库弃用、构建系统重构)。
- Zig 0.17.0 官方文档(Hello World、
main(init: std.process.Init))。 - Zig Guide Live · What Changed in Zig 0.17 与 Migrate from an Older Zig(旧→新对照)。
- 本机 Zig 0.17.1 编译器与
lib/std标准库源码:用于逐段编译验证与 API 核对。 - Zig 0.17 Upgrade Guide、ReasonCore 0.17 解读(构建系统与 ZLS 现状的交叉核对)。
- B 站 UP 主 myfreax 合集《Zig 编程语言》中的 12 讲视频(去重后),标题、分 P、章节时间轴与原始演讲出处见附录 D;本手册第二部分即依据这些视频按教材体例重写。
- B 站 UP 主 myfreax 合集《Zig 编程语言》中第三部分的 6 讲视频(无重复),标题、分 P、简介要点、章节时间轴与原始演讲出处见附录 G;这些视频未挂载字幕轨,第三部分系按教材体例重构而非逐字转录。
整理说明:视频中的观点、比喻与示例思路归原作者 Sawyer X 及 Code Maven 所有;代码片段为本手册按 Zig 0.17 规范重新编写并逐段实测,不保证与幻灯片逐字一致。Zig 尚未发布 1.0,后续版本仍可能调整 API,请以所用版本的官方文档为准。
整理日期:2026-11-15 · 同日两次扩充:12 讲(第二部分 + 附录 D/E/F)、6 讲(第三部分 + 附录 G/H) · 校对版本:Zig 0.17.1
附录 D 视频课程索引与章节映射
用户提供的链接共 13 条,去重后为 12 讲(BV13axQ6YEUi 出现两次)。全部来自 B 站 UP 主 myfreax 的合集《Zig 编程语言》,每个视频通常含「中文配音 / 原声」两个分 P,下表时长按中文配音单 P 计。视频章节时间轴按原简介保留,便于对照回看。第二批 6 讲进阶专题另见附录 G。
| # | 视频(B 站) | 单 P 时长 | 视频章节时间轴 | 对应手册章节 |
|---|---|---|---|---|
| 1 | BV1nhHA6NE4i Zig 内存分配:Allocator 分配器的本质与核心心智模型 | 4:482 P | 00:00 内存的来源00:27 阅读函数签名01:06 什么是分配器01:53 alloc、free、create 和 destroy02:27 更换分配器03:13 当内存耗尽时03:46 0.16 版本新增:init.gpa 和 init.arena04:27 下期预告 | 第 15 章Allocator 心智模型 |
| 2 | BV1eDnd6ME4X Zig DebugAllocator: 捕获泄漏和双重释放 (0.16.0) | 4:092 P | 00:00 为什么内存错误难以察觉00:37 配置设置01:16 阅读泄漏报告01:55 双重释放02:33 故意耗尽内存03:08 调试构建与发布构建03:48 接下来 | 第 16 章安全分配器 / 泄漏报告 |
| 3 | BV14Tno64EwS Zig ArenaAllocator:一次性释放所有内存 (0.16.0) | 4:092 P | 00:00 上次回顾:DebugAllocator00:29 大量小内存分配00:51 一次性全部释放01:28 过早释放02:09 复用同一个竞技场02:37 你已经拥有的竞技场03:09 何时使用它03:47 下期预告 | 第 17 章Arena 与批量释放 |
| 4 | BV1mNno6ZEGy Zig FixedBufferAllocator 与 MemoryPool (0.16.0) | 4:072 P | 00:00 上次回顾:ArenaAllocator00:24 两种内存形态00:45 你拥有的缓冲区01:23 大量同类型对象02:05 不可增长的池02:31 将它们堆叠03:11 选择哪个分配器?03:45 下期预告 | 第 18 章FBA + MemoryPool |
| 5 | BV1mMno6dE5i Zig ArrayList: 会增长的列表 (0.16.0) | 3:352 P | 00:00 当你不知道有多少时00:28 列表的完整生命周期01:05 它是如何增长的01:41 增长可能会移动数据02:13 移除元素02:45 构建字符串03:17 下一集预告 | 第 19 章ArrayList 增长 |
| 6 | BV1bcno6hEQx Zig HashMap 及其相关功能:通过键查找 (0.16.0) | 3:022 P | 00:00 快速查找00:21 Put 和 Get00:59 使用 get or put 进行计数01:32 谁拥有这些键?02:05 当顺序很重要时02:40 接下来 | 第 20 章HashMap 与键所有权 |
| 7 | BV1QFno6wELX Zig MultiArrayList: one array per field (0.16.0) | 4:062 P | 00:00 字段存储在哪里00:47 按名称访问字段01:28 没有填充浪费的空间02:02 同时处理多个字段02:35 支持标签联合类型03:06 固定大小的空间03:36 接下来 | 第 21 章MultiArrayList / SoA |
| 8 | BV18Fno6wE4T Zig EnumArray, EnumMap 和 EnumSet:以枚举为键的集合 (0.16.0) | 3:032 P | 00:00 手动按枚举计数00:36 每个标签都有值01:06 当某些标签为空时01:35 存在或不在的标志位02:17 该选哪一个02:44 接下来 | 第 22 章枚举集合 |
| 9 | BV1WCWx6GEtV Zig Async 的故事 | 7:222 P | 简介未列章节时间轴 | 第 24 章Async 演进史 |
| 10 | BV1PGxy6PE3E Zig 创始人深度解释 Async I/O 与并发编程 | 57:552 P | 00:00 介绍01:34 基础设置03:24 异步基础07:21 并发操作10:38 错误处理16:02 资源取消25:56 返回资源31:25 并发限制39:10 问答与进阶主题 | 第 24 章Async I/O 与并发 |
| 11 | BV13axQ6YEUi 从 20 分钟到 7 秒:Zig + SIMD 构建极致性能的 CSV 流式解析器 | 39:532 P | 00:00 构建新库的动机02:07 CSV 解析的设计目标05:26 解析器实现细节10:12 性能与 SIMD 基础15:01 向量化与研究18:24 向量化的分隔符搜索24:52 基准测试结果31:45 问答与讨论 | 第 25 章SIMD CSV 解析 |
| 12 | BV1PDYy6XEeP 彻底搞懂 Zig 构建系统:DAG 构建图与跨平台编译实战 | 10:102 P | 00:00 BlahBlah00:34 Intro01:35 Kemeet language server (kls) vs Zig language server (zls)02:30 zig build vs build-exe vs build-lib vs build-obj03:33 Creating your first build.zig file04:07 Understanding the Build function05:21 zig-cache folder explained06:07 DAG Model: How Zig executes build steps07:28 zig-out folder explained07:35 The prefix flag -p07:42 How to change the output file name?07:46 How to change the output path/dir?07:51 Customizing targets and optimization modes09:06 How to add the run step to the zig build system?09:32 Another zls issue09:37 How to add the test step to the zig build system?09:41 hmm…09:52 SECRET GIFT | 第 26 章构建系统 DAG |
下表按原始演讲 / 系列给出出处,便于追到一手材料:
| 系列 / 演讲 | 覆盖视频 | 原始出处 |
|---|---|---|
| Ziggurat《Zig 数据结构与分配器》系列(0.16.0) | 第 1–8 讲 | YouTube 同名频道,2026-10-12 ~ 10-21 发布,每集约 4–8 分钟 |
| Zigtoberfest 2025 · Zig’s New Async I/O | 第 9 讲(BV1PGxy6PE3E) | Andrew Kelley 与 Zig Core Team 对谈,2025-10-29,约 116 分钟 |
| The Story of Zig’s Async | 第 10 讲(BV1WCWx6GEtV) | prof. Orion Vale,2026-01-29,约 15 分钟 |
| Zigtoberfest 2026 · Pushing CSV to the Limits | 第 11 讲(BV13axQ6YEUi) | Peyman Mortazavi,2026-10-10,约 80 分钟 |
| Code Guild · Zig replaced cmake and make with pure Zig! ep4 | 第 12 讲(BV1PDYy6XEeP) | 2026-02-15,约 20 分钟 |
与第一部分的关系
合集第 44 集《Zig:从设计哲学到核心特性的深度解析》(BV1qB4p6fE7g)是第一部分的唯一依据;本附录 12 讲是第二部分的依据。两者同属一个合集,但视角互补:前者讲「为什么」,后者讲「怎么选、怎么写、怎么调优」。
附录 D.1 推荐回看顺序
- 先建立心智模型:Allocator 心智模型 → DebugAllocator → Arena → FBA/Pool(第 1–4 讲,约 30 分钟,一口气看完)。
- 再过数据结构:ArrayList → HashMap → MultiArrayList → Enum 集合(第 5–8 讲,约 26 分钟),边看边把第 19–22 章的代码跑一遍。
- 最后啃长视频:Async 的故事(15 分钟)先看,再进 116 分钟的创始人深解;CSV 与构建系统两讲按兴趣选看,建议开着编译器对照。
附录 E 本部分 0.16 → 0.17 API 迁移速查
12 讲中 8 讲基于 0.16.0 录制。下表只列本部分实际用到的差异,完整清单见第 12 章。所有「0.17 事实」均在本机 lib/std 源码与 0.17.1 编译器上核对过。
| 主题 | 0.16 / 视频 | 0.17 事实 | 影响 |
|---|---|---|---|
| 调试分配器 | std.heap.DebugAllocator(.{}) | std.heap.SafeAllocator.init(backing, .{});DebugAllocator 是弃用别名 | 旧名能编译、无警告;新代码别再用 |
| 泄漏返回值 | deinit() 返回 Check.ok/.leak | 返回 usize 泄漏个数;deinitLog(false) 可关日志 | 判断条件从枚举比较改成 == 0 |
| 内存预算 / OOM | DebugAllocatorConfig.enable_memory_limit + requested_memory_limit | SafeAllocator.Options 无这两个字段;用 std.testing.FailingAllocator 注入 | 视频里的预算写法直接编译失败 |
| 对象池 | MemoryPool(T) 非托管,另有 Deprecated 的 Managed 包装与 toManaged | 只剩非托管:.empty + create(gpa) + deinit(gpa) | 照抄 init(gpa) / create() 会失败 |
| ArrayHashMap | std.StringArrayHashMapUnmanaged 等别名(0.16 已弃用) | 继续弃用;推荐 std.array_hash_map.String(V) / .Auto(K,V) | 编译无警告,属于「静默埋雷」类 |
| ArrayList | 0.16 已是非托管(.empty + append(gpa,x)) | 0.17 保持一致,新增 lockPointers/unlockPointers | 本讲代码按 0.17 写即可,差异最小 |
| 枚举集合 | std.EnumArray/EnumMap/EnumSet | 名称与语义不变 | 无需迁移 |
| 优化模式 | std.builtin.OptimizeMode、.ReleaseFast | std.lang.Optimize、.debug/.safe/.fast/.small;-Doptimize=fast | 构建脚本与 CI 参数都要改 |
| 构建脚本 | addExecutable(.{ .root_source_file, .target, .optimize }) | .root_module = b.createModule(.{...}) | 0.16 的 build.zig 在 0.17 先于业务代码报错 |
| 运行参数透传 | b.args | run_cmd.addPassthruArgs() | 字段已移除 |
| 包清单 | .fingerprint 可选 | 0.17 必填;删除后由 zig build 给出建议值 | 新项目初始化时会卡住一次 |
| 显式 I/O | std.Io、std.process.Init(init.io/gpa/arena) | 三者保持不变;环境变量/参数收进 init.minimal | 写法稳定,注意精确字段路径 |
@bitCast | 按物理位重解释 | 改为逻辑位语义,array/vector 相关代码可能静默出错 | 第 25 章掩码代码必须实测,不能照抄旧写法 |
std.fmt.bufPrint | 常用 | 推荐 std.mem.print(旧名仍是弃用别名) | 第 20 章示例已用新名 |
| 静态字符串表 | initComptime、StaticStringMapWithEql 均可用;枚举名映射需手写 @tagName 表 | 0.17 新增 initEnum();另有运行时 init(kvs, gpa) / deinit(self, gpa) | 第 27 章示例按 0.17 写;照抄 0.16 手写枚举表属于多余劳动 |
| 队列容器 | 0.16 起非托管化:PriorityQueue.push(gpa, x)、Deque.initBuffer | 0.17.1 完全一致;PriorityDequeue 仍提供 popMin/popMax | 第三部分是少数「视频代码可直接用」的一组;更早的托管式写法在 0.17 已不适用 |
| 取消接口 | error.Canceled 散落在各异步 API | 统一为 std.Io.Cancelable;新增 checkCancel / recancel / swapCancelProtection 与 Group.cancel | 第 30 章代码用 0.17 接口;忽略 error.Canceled 会让取消信号被消费 |
packed struct | 常被描述为「零 padding、精确到 bit」 | 字段位偏移连续,但对象大小取决于 backing 整数:160 位实测 size=32 align=16;位域指针是带位偏移的特殊指针 | 第 32 章已用探针实测修正,别把内存布局直接当线格式 |
版本使用建议
别用「0.16 视频 + 0.17 编译器」直接对敲。正确顺序是:先看视频建立概念 → 到本手册对应章节拿 0.17 写法 → 用
zig run复现输出 → 再回到附录 E 查差异原因。这样学到的东西不会因为一次版本升级全部作废。
附录 F 综合实验与自测(附参考答案)
第一部分的第 13 章考语言特性,本附录考工程决策。建议先动手改代码,再看答案要点;带 ★ 的是需要真的编译/测量才能答好的题。
附录 F.1 实验题
- 写一个函数
parseTags(gpa, text) ![][]const u8,把逗号分隔的字符串切成切片数组。要求:不复制每个字段、中途失败不泄漏。 - ★ 把第 19 章
06_array_list_growth.zig里的lockPointers()之后加一次append,记录 0.17.1 的实际行为,并解释为什么这个断言比「靠代码审查」可靠。 - 一个 HTTP 服务每轮请求要解析 JSON、构造临时字符串、拼响应。请给出 allocator 组合与
reset的位置,并说明哪些数据不能放进请求 arena。 - ★ 用
std.testing.FailingAllocator把fail_index从 0 扫到 8,验证第 16 章loadConfig在每个注入点都不泄漏。你怎么自动判断「没泄漏」? - 把第 18 章的
MemoryPool换成growable = false的Extra并预热 2 个槽位,创建第 3 个对象会发生什么? - 词频统计里键来自
std.mem.print(&tmp, ...)生成的字符串。解释为什么直接put是错的,并写出覆盖put失败的完整释放代码。 - ★ 把第 21 章的
Particle从ArrayList换成MultiArrayList,元素量放大到 100 万,只累加x,比较两种布局的耗时并说明差异来自哪里。 - 一个功能开关系统有 12 个开关,需要频繁做「并集 / 交集 / 是否包含」。选哪个容器?为什么不用
HashMap? - ★ 在第 24 章
11_io_group.zig基础上,把一个任务改成返回error.Canceled,观察group.await(io)的行为;再用defer在任务里打印一条清理日志,确认取消路径是否执行。 - 第 25 章的
scanChunk把LANES从 32 改成 64 需要改哪几处?提示:掩码类型、@ctz结果类型、补位逻辑。 - ★ 给第 26 章的构建脚本再加一个
lint步骤,让它与test并行执行且不依赖install;用zig build --list-steps验证。 - 综合题:设计一个「读取 2 GB CSV → 统计每列非空值个数 → 输出报告」的程序。请一次性写出:分配器策略、容器选择、I/O 方式、是否使用 SIMD、构建脚本需要哪些步骤,以及每处选择对应本手册哪一章。
附录 F.2 参考答案要点
- 用
std.mem.splitScalar迭代,把每段切片append(gpa, part)进ArrayList([]const u8);errdefer list.deinit(gpa)覆盖失败;最后toOwnedSlice(gpa)。字段本身借用text,所以还要保证text活得比结果久。 - 上锁后触发失效的操作会直接断言(0.17 的
lockPointers就是为此加的)。它把「未来某天有人加了 append 导致悬空」变成「加的当天就崩给你看」,属于把运行期 UB 前移到可诊断失败。 - 请求 arena 建在循环外,每轮开头
reset(.retain_capacity);JSON 临时对象、响应字符串都挂上去。不能放进去的:跨请求缓存、长连接会话状态、要写进全局日志队列的内容——这些必须dupe到init.gpa或长命分配器。 - 用
SafeAllocator作为底层,每次注入后断言deinit() == 0;或统计FailingAllocator的allocations与deallocations是否相等。不要只看zig test退出码(12.4)。 - 第三个
create返回error.OutOfMemory,因为不可增长的池只能从预热槽位取;这正是把「内存上限」变成可测试约束的做法。 - 缓冲区在函数返回后失效,表里留的是悬空切片。写法:
const key = try gpa.dupe(u8, dynamic); errdefer gpa.free(key); try map.put(gpa, key, v); defer gpa.free(key);;容器deinit不会替你释放键。 - SoA 只需连续读
x通道,AoS 每 12 字节里只用 4 字节且带填充;差距主要来自 cache line 利用率与内存带宽。若循环同时读全部字段,差距会明显缩小甚至反转。 EnumSet:位图,交集 / 并集 / 包含都是位运算,零分配、零哈希、类型安全;HashMap 在这里纯属浪费。- 任务返回
Canceled是取消传播边界;await会等待所有任务并反映取消。defer写在任务内部,正常返回、报错、取消三条路径都会执行,这正是「资源归还」不依赖 group 生命周期的原因。 - 掩码类型从
u32改u64、向量长度 64、@Vector(64, u1);@ctz结果仍可转usize;补位数组[64]u8,并注意第二块之后base的偏移。 - 新建
b.step("lint", ...)与一个b.addRunArtifact(...)(或b.addSystemCommand),只dependOn对应节点、不dependOn(b.getInstallStep());--list-steps应能看到lint且执行顺序与test无强制先后。 - 参考组合:
init.io+ 固定缓冲流式读(25.2)、@Vector分隔符扫描(25.3)、按列计数用EnumArray或固定数组(22 章,列数编译期/运行期已知时)、只在读满一块时分配且用 FBA(18 章)、结果报告用 array arena +ArrayList(u8)(17+19 章)、build.zig含 install/run/test/bench 四步(26 章)、CI 用SafeAllocator+ 失败注入验证错误路径(16 章)。关键不是「全用最快的」,而是说清每处内存归谁、上限多少。
交付检查表
完成本部分后,你应该能对着一段陌生 Zig 代码回答:谁分配?谁释放?上限多少?数据怎么摆?会不会搬移?失败与取消时资源怎么收?构建时生成了哪几个产物?——能答全这七问,就从「看得懂语法」走到「能负责一个模块」了。
附录 G 第三部分视频索引与章节映射
第二批链接共 6 条,无重复,全部来自 B 站 UP 主 myfreax 的合集《Zig 编程语言》(共 47 集)。加上手册第一部分(1 讲)与第二部分(12 讲,第一批 13 条链接去重后),本手册共覆盖 19 讲。下表时长按「中文配音」单 P 计;章节时间轴按原简介保留,未列时间轴的讲次改用主题要点。
| # | 视频(B 站) | 单 P 时长 | 视频章节时间轴 / 主题要点 | 对应手册章节 |
|---|---|---|---|---|
| 1 | BV1bPno6bEX3 Zig StaticStringMap:将单词转换为值 (0.16.0) | 3:342 P | 00:00 匹配单词00:37 编译时生成的映射表01:11 查找机制01:48 大小写不敏感02:17 最长匹配02:49 枚举名称的快捷方式03:16 下期预告 | 第 27 章编译期字符串分派 |
| 2 | BV1DAno6FENM Zig PriorityQueue and Deque: 两种队列 (0.16.0) | 3:292 P | 00:00 接下来要讲的内容00:35 最紧急的优先01:09 最小或最大优先01:40 结合额外数据比较02:12 两端都可操作的队列02:41 保留最后几项03:09 下期预告 | 第 28 章堆与环形双端队列 |
| 3 | BV1o7hx6yEL4 Zig 作者带你用面向数据设计 (DoD)编程构建高性能应用 | 46:402 P | 简介未列时间轴;要点:CPU 与内存墙、缓存未命中、索引替指针、布尔外置、SoA、上下文特定编码 | 第 29 章五个瘦身技巧 + 实测 |
| 4 | BV1HbpC6QEBK Zig 之父 Andrew Kelley:拆解并发编程中最痛苦的难题–取消 / 终止任务 | 47:102 P | 简介未列时间轴;要点:定时器中断、缓存争用、Amdahl 定律、EINTR、musl 信号处理、线程取消 | 第 30 章取消协议与资源归还 |
| 5 | BV1ykhx6tEjf Zig 创始人 Andrew Kelley:为什么我不建议数据结构里继续用指针(无指针编程) | 10:012 P | 简介为空;主题依据标题与演讲者:数据结构内部不再存放指针 | 第 31 章索引 / 世代句柄 |
| 6 | BV1mmxc6JEqV Zig 内存布局优于 C | 9:472 P | 00:00 简介00:35 数学原理01:24 对齐规则02:08 SerpApi03:15 调试04:01 完全控制(内存布局 & IPv4)05:22 C语言怎么样?(位域问题)07:27 C2308:08 为什么有 131,071 种类型?09:30 再见 | 第 32 章位宽 / packed / 线格式 |
附录 G.1 原始演讲 / 视频出处
| 讲 | 原视频 / 原作者 | 发布时间 |
|---|---|---|
| 27 StaticStringMap | Zig StaticStringMap: turning words into values · Ziggurat | 2026-10-21 |
| 28 PriorityQueue & Deque | Zig PriorityQueue and Deque: two kinds of line · Ziggurat | 2026-10-21 |
| 29 DoD 实战 | A Practical Guide to Applying Data Oriented Design · Andrew Kelley / ChimiChanga | 2024-07-13 |
| 30 取消 / 终止任务 | Getting Canceled · Andrew Kelley / Zig SHOWTIME | 2026-10-13 |
| 31 无指针编程 | Andrew Kelley 演讲(B 站简介为空,未给出原视频链接) | 2026-09-23 上传 |
| 32 内存布局优于 C | Zig Memory Layout is Better Than C · Code Guild | 2026-10-29 |
附录 G.2 推荐回看顺序
- 先补两块容器短板:第 27、28 讲各 3 分半,配合第 27、28 章代码一起看,成本最低、收获最直接。
- 再走性能线:第 29 讲(93 分钟,可分段)→ 第 31 讲(10 分钟)→ 第 32 讲(约 10 分钟)。建议按 29 → 31 → 32 的顺序,因为索引、位宽、布局是同一个故事的三层。
- 最后啃取消:第 30 讲 94 分钟,建议先读完第 30.3 节的标准库 API 表再回看,重点听 EINTR 与资源归还那一段。
- 对照阅读:第 29 讲与第 21 章、第 30 讲与第 24 章、第 31 讲与第 19 章成对看,能最清楚地看出「机制」与「设计」的差别。
材料局限(诚实说明)
这 6 讲在 B 站均未挂载字幕轨,无法取得逐字转录。短课依据简介里的完整章节时间轴逐节复原;长演讲依据标题、简介要点、原始演讲出处,结合本机
lib/std源码与 0.17.1 编译实测,按教材体例重构为可验证的知识结构,不是演讲逐字稿,也未虚构原话。所有代码块都是本手册为教学独立编写并实测的完整程序,不是视频里代码的抄录。
与附录 D 的关系
附录 D 收录第一、二部分的 13 条链接(去重 12 讲),本附录收录第三部分的 6 讲。两批视频同属一个 47 集合集,但视角不同:D 偏「机制与操作」,G 偏「设计与边界」。完整合集目录可在 B 站 UP 主 myfreax 的空间查看。
附录 H 第三部分实验与自测(附参考答案要点)
附录 F 考工程决策,本附录考设计与验证:能不能把一个模糊的性能/正确性主张,变成可编译、可测量的断言。带 ★ 的题必须真的编译或测量。
附录 H.1 实验题
- 给第 27 章的映射表加 10 个长度都是 4 的键,用
comptime断言keys()的顺序,并解释此时get()的最坏比较次数。 - ★ 把第 28 章
byDist里的 id 平局判断去掉,构造两个距离相同的元素,观察update()实际改到了哪一个,并说明源码里哪一行导致了这个结果。 - 用
Deque.initBuffer实现容量 8 的撤销栈:前端插入、满了丢弃最旧一条。为什么这里不能用ArrayList? - ★ 把第 29 章的 benchmark 改成同时累加
x与y,记录比值变化;再用-Doptimize=fast跑一次,解释两次结果的差别。 - ★ 在第 30 章
19_io_cancel.zig的任务里把checkCancel的错误catch {}吞掉,观察group.cancel之后任务是否跑完;再用recancel或把错误继续try出去修复。 - 给第 31 章的
Store加一个空闲索引栈(也是u32数组)取代线性扫描,说明插入复杂度变化;再把generation改成u8并循环复用同一槽位 300 次,会发生什么? - ★ 把第 32 章的
Ipv4Header删掉src/dst换成 96 位版本,记录@sizeOf/@alignOf;另写一个函数,从[20]u8线格式里用readInt取出 version、ihl、total_length、protocol。 - 综合题:设计一个「每秒处理百万条日志、可随时优雅停止」的 Zig 程序。一次性写出:数据布局(29/31 章)、容器选择(27/28/20 章)、取消协议(30/24 章)、线格式处理(32 章)、以及构建与压测步骤(26 章),并指出每处选择对应哪一章。
附录 H.2 参考答案要点
keys()按「长度升序 + 同长度字典序」排列,可用comptime { for (map.keys(), 0..) ... }断言。长度桶退化为 10 个同长键,最坏要比较 10 次字符串;键多且长度集中时应改用StringHashMap。update()用compareFn(context, item, elem) == .eq线性查找下标,去掉 id 平局后所有同距离元素都「相等」,它会命中第一个而非目标元素。修法:比较函数必须构成严格弱序且能区分身份(距离 + id),或让优先级成为元素字段。- 前端插入 + 容量固定 + 丢弃最旧,正是
Deque的 O(1) 两端操作;ArrayList头部插入是 O(n) 搬移。注意initBuffer只能用Bounded系列方法,满时先popBack()(或popFront(),取决于哪端是「最旧」)再插入。 - 同时读两个字段时 AoS 的有效字节比例翻倍,差距会缩小;SoA 需要两个数组、两次遍历或一次同时遍历两个数组。
-Doptimize=fast下 SoA 可能被向量化,差距重新拉大,而 AoS 因跨步访问难以向量化。结论必须写清优化模式与机器,不能只报一个倍数。 - 吞掉
error.Canceled后请求已被消费,后续checkCancel不会再报(对应 0.17 源码注释),任务一路跑到 2000 万次循环,取消形同虚设。正确做法是把错误继续向上传播,或在确实需要延后的临界区后调用std.Io.recancel(io);defer清理仍会执行,但「及时停止」已丢失。 - 空闲索引栈把插入从 O(n) 扫描降到 O(1) 弹栈,删除时把索引压回。
u8世代 256 次后回绕到 0,第 257 次复用会让最早的旧句柄重新变成「有效」——这就是 ABA 复现;生产代码用更宽的世代或永不复用槽位。 - 96 位版本的
@sizeOf会落到 16 字节 / align 16(对照附录探针表 128 位 → 16 字节)。线格式解析:version = wire[0] >> 4、ihl = wire[0] & 0x0f、total_length = std.mem.readInt(u16, wire[2..4], .big)、protocol = wire[9];不要直接把[20]u8@bitCast成 packed struct,那是内存布局而不是协议布局。 - 参考组合:日志字段按访问频率做热/冷拆分,热字段用
MultiArrayList或独立数组(29);会话/规则之间用u32索引 + 世代句柄(31);固定命令字用StaticStringMap在编译期分派(27);待处理队列用Deque或PriorityQueue(28);每个工作循环设取消点、defer归还缓冲、Group.cancel保证优雅停止(30/24);输入线格式用字节缓冲 +readInt(.big)(32);build.zig含 install / test / bench 步骤,用 FailingAllocator 验证 OOM 路径(26/16)。关键不是「全用最快的」,而是每处选择都能说出代价与验证方式。
第三部分的交付检查表
读完并能做完这 8 题,你应该能回答:这张表能不能在编译期定下来?这段循环每次真正读了多少字节?这个引用能不能活过一次扩容?任务被取消时谁还拿着资源?我写的字节流在另一台机器上还是同一个意思?——这五问,正好对应 27/28、29、31、30、32 五组章节。
Zig 0.17 完整学习手册 · 依据 B 站《Zig 编程语言》合集 19 讲整理 · 全部代码经 Zig 0.17.1 实测 · 2026-11-15
1190



被折叠的 条评论
为什么被折叠?



