Zig 设计哲学与核心特性 · 0.17 学习手册

Zig跨平台固件构建工具链设计与实践 在嵌入式与IoT开发中,跨平台固件构建面临环境不一致、依赖复杂、配置难复现等核心挑战。Zig凭借零运行时依赖、编译期代码执行和原生C ABI兼容三大特性,成为轻量级自研工具链(如zkc类方案)的首选底层引擎。其静态单文件分发能力显著降低CI/CD部署成本,而@embedFile、@compileLog等机制将配置逻辑前移至编译阶段,提升类型安全与构建确定性。典型应用场景包括高校教学固件流水线、医疗设备多板卡适配、工业传感器OTA升级等对可审计性与交付轻量化有强需求的工程实践。 阅读详情

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 集
分 PP1 中文配音 / 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 的观点,保留其原意

目录

第一部分 · 设计哲学与核心特性

第二部分 · 专题深化(12 讲)

第三部分 · 进阶专题(6 讲)

附录


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 要点:

  1. main(init: std.process.Init) 是新入口。init.io 把「可能阻塞的操作」显式交给调用者,和 Allocator 是同一种设计;init.gpa、init.arena、init.environ、init.args 也在其中。
  2. Writer 带缓冲区,缓冲区由你提供,因此没有隐式分配;写完必须 flush()。
  3. 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]运行时 / GCGC
Perlgrep { $_->{age} >= 18 } @users运行时引用计数
Goappend(adults, u)运行时GC
Rustusers.iter().filter(...).collect()全局堆所有权 / Drop
Cmalloc + 自己 realloc + 检查返回值你你
Zigtry 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
类型标记?!
就地兜底orelsecatch
向上冒泡无(要么给值,要么处理)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 特色:

  1. 点号推断:写 .{ .transfer = ... }、.card 分支、p == .transfer,都不用重复 Payment. 前缀;Rust 得写全 Payment::Card。
  2. @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 实测结果
1GPA、std.heap.GeneralPurposeAllocator改叫 std.heap.SafeAllocator,构造为 .init(backing, .{})error: struct 'heap' has no member named 'GeneralPurposeAllocator'
2ArrayList(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_attrserror: no field named 'fields' in struct 'lang.Type.Struct'
4问答里「以前可以直接 import C」@cImport / @cInclude / @cDefine / @cUndef 全部移除,改用外部 translate-c 包或 b.addTranslateCerror: invalid builtin function: '@cImport'
5ReleaseFast / Debug 等构建模式叫法std.lang.Optimize:.debug / .safe / .fast / .small;读 builtin.optimizeerror: 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'
7errdefer |err|捕获移除,改 catch |err| { ...; return err; }error: expected block or expression, found '|'
8"-" ** 5const 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.
11main() !void + std.debug.print仍然合法,官方 0.17 文档仍在用;只是新代码推荐 main(init: std.process.Init)编译通过

12.2 0.16 → 0.17 的破坏性变更(查漏用)

语言层

  • 移除数组重复 **、void{}(改用 {})、errdefer |err|、i0(改 u0)、internal / link_once linkage。
  • @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、.ReleaseFaststd.lang.Optimize、.fast
builtin.mode / builtin.os.tagbuiltin.optimize / builtin.target.os.tag
std.gpustd.spirv(无别名)
info.fields[i].name / .typeinfo.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.dupeZstd.mem.printSentinel / gpa.dupeSentinel
DebugAllocator(.{})SafeAllocator;deinit() 返回泄漏数而非 .ok / .leak
std.heap.stackFallbackstd.heap.BufferFirstAllocator(无别名)
ArrayList.getLast() / getLastOrNull()last()(返回 ?T)
bit_set.initEmpty() / initFull().empty / .full;StaticBitSet → std.bit_set.Static
std.ascii.indexOfIgnoreCasestd.ascii.findIgnoreCase
std.Io.File.OpenFlags / CreateFlagsstd.Io.Dir.OpenFileOptions / CreateFileOptions
std.mem.writePackedIntNativestd.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 升级操作清单

  1. 先跑 zig fmt(或 zig fmt --upgrade),它会修掉一大部分机械重命名。
  2. 改 build.zig:b.args → addPassthruArgs()、路径字段 → b.root、自定义 makeFn → 外部小程序;检查 CI 脚本里的旧 flag。
  3. 全局搜索:@cImport、**、errdefer |、void{}、i0、.fields[、@bitCast、containsAtLeastScalar、GeneralPurposeAllocator、std.io。
  4. 把弃用别名批量替换成 12.2 的新名字。
  5. 若依赖 ZLS(编辑器补全/跳转),0.17.0 上暂不可用,先用「命令行诊断 + zig fmt + 语法高亮」过渡,等 ZLS 支持 Build Server Protocol 后再升级编辑器链。

13 练习与自测

先自己答,再对要点。带星号的是版本陷阱题。

  1. A = B + C 在 Zig 里为什么没有歧义?至少说出三种其他语言可能隐藏的行为。
  2. !u16 和 ?u16 分别解决什么问题?各自配套哪些关键字?
  3. 把第 04 章的 findAdults 从 SafeAllocator 换成 ArenaAllocator,需要改动几处代码?
  4. 0.17 为什么把 allocator 从 ArrayList 里拿出来,改成每次调用都传?
  5. 写一个 parsePort,要求 port=0 返回自定义错误,并用穷尽 switch 处理所有错误。
    • 0.17 里怎么取结构体的字段名与字段类型?为什么幻灯片里的 .fields 不行?
  6. inline for 和普通 for 有什么不同?为什么 @field 的字段名必须是编译期已知?
  7. 标签联合比「数据 + kind 变量」好在哪?@tagName 能省掉什么?
  8. 三名字两年龄一起 for,0.17 会怎样?C / Python / Rust 分别会怎样?
  9. defer / errdefer 与 Go 的 defer 在作用域上有什么差别?
    • 说出五个 0.17 已移除或改名的写法,并给出新写法。
    • 哪几类过时写法编译器不会给任何提示?升级项目时怎么排查?
  10. std.debug.print 和 std.Io.Writer 各适合什么场景?为什么 writer 需要 flush()?
  11. @Vector 为什么说是「SIMD 只是一种类型」?@splat 替代了什么旧语法?

答案要点

  1. 没有运算符重载、没有属性 getter、没有 magic 回调、没有异常跳转、没有按上下文改变的操作;「看起来不像函数调用,就不会调用函数」。
  2. !T 是错误联合,配 try / catch / error;?T 是可选值,配 orelse / if (x) |v| / null。
  3. 一处都不用改函数本身,只需在调用处换 allocator 参数;这正是演讲的核心论点。
  4. 让每一次可能分配内存的调用都在代码里可见,符合「没有隐式分配」,也便于同一容器混用不同分配策略。
  5. 见第 06 章;漏掉 error.Overflow 或 error.InvalidCharacter 任一分支都会编译失败。
  6. const info = @typeInfo(T).@"struct"; 后用 info.field_names / info.field_types 平行数组,inline for 同时迭代;0.17 移除了 .fields。
  7. inline for 编译期展开,循环变量是 comptime;@field 要求字段名编译期已知,因此必须展开。
  8. tag 由编译器维护,新增变体会触发穷尽检查;@tagName 可直接取标签名,不必为每个分支再写一遍字符串。
  9. 0.17 编译期已知长度就编译失败,运行期才知道则 panic;C 越界读垃圾,Python/Rust zip 静默截断。
  10. Zig 是当前作用域,Go 是整个函数;errdefer 只在错误返回路径执行。
  11. 见 12.1 表格,任取五条(GPA、ArrayList.init、.fields、@cImport、std.io、**、errdefer |err|、.Debug 等)。
  12. 弃用别名(bufPrint / indexOfScalar / DebugAllocator…)与静默行为变化(@bitCast、containsAtLeastScalar 参数顺序、测试泄漏只记日志);靠全局搜索 + 12.5 清单人工审查。
  13. std.debug.print 用于诊断、不需要 io;正式输出走 std.Io.Writer,缓冲区由调用者提供,所以必须 flush()。
  14. @Vector(4, u32) 直接相加即一条 SIMD 指令;@splat 取代了被移除的 ** 数组重复语法。

14 延伸资源

资源地址说明
官方学习页ziglang.org/learn演讲首推入口
Zig 0.17.0 语言参考ziglang.org/documentation/0.17.0篇幅不大,一天能读完
0.17.0 Release Notesziglang.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 Zig0.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 站)本手册章节要回答的核心问题
1Allocator 的本质与核心心智模型15为什么看函数签名就能知道它是否分配内存?
2DebugAllocator:捕获泄漏和双重释放16怎么让内存错误在开发期自己跳出来?
3ArenaAllocator:一次性释放所有内存17大量小对象同生共死时,能否不逐个 free?
4FixedBufferAllocator 与 MemoryPool18内存上限已知、或对象反复生灭时怎么做到零堆开销?
5ArrayList:会增长的列表19增长时数据会搬家吗?指针什么时候失效?
6HashMap 及其相关功能20谁拥有 key 指向的内存?什么时候要保序?
7MultiArrayList:one array per field21为什么换一种内存布局就能快?
8EnumArray / EnumMap / EnumSet22键是编译期已知的枚举时,能不能完全不分配?
—(前 8 讲综合)23把分配器与容器组合成一张可执行的选型决策树
9–10Async 的故事 / 创始人深解 Async I/O24为什么 Zig 删掉了 async 关键字,又把 I/O 变成参数?
11Zig + SIMD 极致性能 CSV 解析器25零分配流式 + 向量化如何把 20 分钟压到 7 秒?
12构建系统:DAG 与跨平台编译26build.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切片 []Tconst xs = try gpa.alloc(u8, n); defer gpa.free(xs);free 时长度必须与 alloc 一致
create / destroy单个 Tconst 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 调试期如何暴露
内存泄漏 leakRSS 缓慢上涨,几小时后才 OOMSafeAllocator.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 = 1deinit() 的返回值;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 或外部 APISoA 天然是连续数组,可直接喂给 @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]VN × 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 成本模型速查

操作ArrayListArrayHashMapHashMapMultiArrayListEnum*
追加 / 插入摊还 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.Allocatorstd.Io
本质ptr + vtable(alloc/resize/remap/free)userdata + vtable(文件、网络、时间、async/concurrent/await/cancel、锁、队列…)
从哪来调用者传入 gpa / arena / FBA0.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.asyncIo.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 零分配流式的三个不变量

  1. 缓冲区固定:一次读一个 chunk(如 32/64 字节的若干倍),无论文件多大,RSS 恒定。
  2. 状态跨 chunk 保留:引号状态、当前字段起点、上一块末尾的转义符都要显式存成几个标量,不能靠「再读一遍」。
  3. 字段不复制:字段以 []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 到 u3232 个布尔压成 32 个位,第 i 位为 1 表示第 i 字节是分隔符
3. 迭代命中位@ctz(mask) + mask &= mask - 1CTZ 找最低位的 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、分配次数改流式、去掉逐行对象;收益通常最大
2cache miss / 内存带宽SoA 布局(第 21 章)、减少复制、对齐缓冲
3branch-misses向量比较 + 位掩码,把控制流变成数据
4IPC、指令数最后才考虑 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.zig0.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. 容器与编译期(约 1 小时):27 → 28 → 回看第 10、20、22 章。目标是把「运行时查表」和「运行时排序」尽可能变成编译期常量与专用结构。
  2. 性能工程(约 3 小时):29 → 31 → 32 → 回看第 21、25 章。目标是能对着 @sizeOf、缓存行和一段 benchmark 说出瓶颈在哪,而不是靠猜。
  3. 系统正确性(约 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 块中做三件事:

  1. 把 kvs_list 按键长度升序、同长度字典序排序,生成静态 keys / values 数组(initSortedKVs)。
  2. 生成 len_indexes:长度 L 对应的第一个键的下标,同时记录 min_len / max_len(initLenIndexes)。
  3. 用 @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 下标而不是 *Node64 位指针 8 字节 → 4 字节;整块数据可搬移、可序列化、可跨进程第 31 章
2布尔值外置把 bool 从对象里拿出来,用独立的位集(每对象 1 bit)结构体里一个 bool 常因对齐吃掉 4–8 字节;1 亿对象省下几百 MB本章 / 第 22 章
3SoA:一列一个数组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 测量纪律与「不值得改」的信号

  1. 先量再改:先写对照程序,记录基线;只改一个变量(布局),其它全不动。
  2. 结果必须被消费:把和打印出来,否则优化器可能把整段循环删掉。
  3. 分别跑 Debug 与 ReleaseFast(0.17 是 -Doptimize=fast,见第 26 章);Debug 看安全开销,Release 看向量化收益。
  4. 控制缓存预热与样本量:跑到毫秒级以上,多跑几次取范围,不要拿单次最小值当结论。
  5. 量全链路:如果瓶颈在解析、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)
可并行占比 pN=2N=4N=8N=16N→∞
0.501.33×1.60×1.78×1.88×2.00×
0.901.82×3.08×4.71×6.40×10.0×
0.991.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
对比项ZigC
位域宽度u1..u65535,编译期确定只能用 int/unsigned 加 :N;宽度受底层类型限制
位域布局@bitOffsetOf 给出确定偏移分配顺序、跨存储单元行为、字节序由实现定义
取地址可以,得到携带位偏移的位指针位域不能取地址
溢出检查编译期 + 运行期安全构建会报错静默截断
线格式控制仍须显式 readInt/writeInt(..., .big)同样须 htons/ntohs,且位域不能直接映射

所以「Zig 内存布局优于 C」更准确的说法是:C 把一部分布局选择留给了编译器实现,Zig 让程序员显式选择并能在编译期验证。它并没有免除字节序转换,也没有让 packed struct 自动变成线格式。

32.5 决策清单

  1. 纯内部数据 → 普通 struct,别假设字段顺序,别拿它当字节流。
  2. 要与 C / 共享内存对接 → extern struct,字段顺序和 padding 都按 ABI 来,用 @offsetOf 核对。
  3. 要位域、寄存器、紧凑编码 → packed struct,用 @bitOffsetOf 与 @bitSizeOf 核对,位宽用任意整数。
  4. 要写网络/磁盘格式 → 显式字节缓冲 + readInt/writeInt(.big 或 .little);packed struct 只当逻辑视图。
  5. 要跨版本持久化的布局 → 在测试里断言 @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_hello00main(init)、std.Io.Writer、flush()Hello, Zig 0.17! / 1 + 2 = 3
10_naive03手写 if 链、parseInt / parseFloat / stringToEnumport=9000 workers=8 timeout=1.5 log=warn tls=true
04_allocator04.empty + append(gpa, x)、SafeAllocator、arena、FBA三种分配器各 2 adults
leak_test04std.testing.allocator 泄漏报告1 errors were logged.
02_optional05?T、orelse 四种用法、if 捕获found: Grace (37) 等 5 行
03_errors06!T、try、穷尽 catch ... switchport("8080") = 8080 等
05_tagged_union07union(enum)、点号推断、@tagName、{t}tag = transfer, level = info
06_multi_for08多序列 for、0.. 无界 range三行 0: Ada is 36 等
07_defer09defer / errdefer、LIFOsuccess path → cleanup on error only
08_comptime10comptime type、@typeInfo 平行数组、inline for、@fieldServer / Client 两行 + rejected: UnknownKey
09_simd11@Vector、@reduce{ 11, 22, 33, 44 } / 110

此外 verify/legacy/ 下的 8 个「过时写法」探针文件,在 0.17.1 上分别产生了 12.1 表中列出的真实报错。


附录 C 参考来源

  1. B 站视频《Zig:从设计哲学到核心特性的深度解析》BV1qB4p6fE7g,UP 主 myfreax,2026-11-08。
  2. 原始演讲 Zig: From Beginner to Slightly Less Beginner,Sawyer X,Code Maven,2026-10-29;本手册依据其完整英文转录(含问答)与公开演讲笔记整理。
  3. Zig 0.17.0 Release Notes(语言变更、标准库弃用、构建系统重构)。
  4. Zig 0.17.0 官方文档(Hello World、main(init: std.process.Init))。
  5. Zig Guide Live · What Changed in Zig 0.17 与 Migrate from an Older Zig(旧→新对照)。
  6. 本机 Zig 0.17.1 编译器与 lib/std 标准库源码:用于逐段编译验证与 API 核对。
  7. Zig 0.17 Upgrade Guide、ReasonCore 0.17 解读(构建系统与 ZLS 现状的交叉核对)。
  8. B 站 UP 主 myfreax 合集《Zig 编程语言》中的 12 讲视频(去重后),标题、分 P、章节时间轴与原始演讲出处见附录 D;本手册第二部分即依据这些视频按教材体例重写。
  9. 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 时长视频章节时间轴对应手册章节
1BV1nhHA6NE4i
Zig 内存分配:Allocator 分配器的本质与核心心智模型
4:48
2 P
00:00 内存的来源
00:27 阅读函数签名
01:06 什么是分配器
01:53 alloc、free、create 和 destroy
02:27 更换分配器
03:13 当内存耗尽时
03:46 0.16 版本新增:init.gpa 和 init.arena
04:27 下期预告
第 15 章
Allocator 心智模型
2BV1eDnd6ME4X
Zig DebugAllocator: 捕获泄漏和双重释放 (0.16.0)
4:09
2 P
00:00 为什么内存错误难以察觉
00:37 配置设置
01:16 阅读泄漏报告
01:55 双重释放
02:33 故意耗尽内存
03:08 调试构建与发布构建
03:48 接下来
第 16 章
安全分配器 / 泄漏报告
3BV14Tno64EwS
Zig ArenaAllocator:一次性释放所有内存 (0.16.0)
4:09
2 P
00:00 上次回顾:DebugAllocator
00:29 大量小内存分配
00:51 一次性全部释放
01:28 过早释放
02:09 复用同一个竞技场
02:37 你已经拥有的竞技场
03:09 何时使用它
03:47 下期预告
第 17 章
Arena 与批量释放
4BV1mNno6ZEGy
Zig FixedBufferAllocator 与 MemoryPool (0.16.0)
4:07
2 P
00:00 上次回顾:ArenaAllocator
00:24 两种内存形态
00:45 你拥有的缓冲区
01:23 大量同类型对象
02:05 不可增长的池
02:31 将它们堆叠
03:11 选择哪个分配器?
03:45 下期预告
第 18 章
FBA + MemoryPool
5BV1mMno6dE5i
Zig ArrayList: 会增长的列表 (0.16.0)
3:35
2 P
00:00 当你不知道有多少时
00:28 列表的完整生命周期
01:05 它是如何增长的
01:41 增长可能会移动数据
02:13 移除元素
02:45 构建字符串
03:17 下一集预告
第 19 章
ArrayList 增长
6BV1bcno6hEQx
Zig HashMap 及其相关功能:通过键查找 (0.16.0)
3:02
2 P
00:00 快速查找
00:21 Put 和 Get
00:59 使用 get or put 进行计数
01:32 谁拥有这些键?
02:05 当顺序很重要时
02:40 接下来
第 20 章
HashMap 与键所有权
7BV1QFno6wELX
Zig MultiArrayList: one array per field (0.16.0)
4:06
2 P
00:00 字段存储在哪里
00:47 按名称访问字段
01:28 没有填充浪费的空间
02:02 同时处理多个字段
02:35 支持标签联合类型
03:06 固定大小的空间
03:36 接下来
第 21 章
MultiArrayList / SoA
8BV18Fno6wE4T
Zig EnumArray, EnumMap 和 EnumSet:以枚举为键的集合 (0.16.0)
3:03
2 P
00:00 手动按枚举计数
00:36 每个标签都有值
01:06 当某些标签为空时
01:35 存在或不在的标志位
02:17 该选哪一个
02:44 接下来
第 22 章
枚举集合
9BV1WCWx6GEtV
Zig Async 的故事
7:22
2 P
简介未列章节时间轴第 24 章
Async 演进史
10BV1PGxy6PE3E
Zig 创始人深度解释 Async I/O 与并发编程
57:55
2 P
00:00 介绍
01:34 基础设置
03:24 异步基础
07:21 并发操作
10:38 错误处理
16:02 资源取消
25:56 返回资源
31:25 并发限制
39:10 问答与进阶主题
第 24 章
Async I/O 与并发
11BV13axQ6YEUi
从 20 分钟到 7 秒:Zig + SIMD 构建极致性能的 CSV 流式解析器
39:53
2 P
00:00 构建新库的动机
02:07 CSV 解析的设计目标
05:26 解析器实现细节
10:12 性能与 SIMD 基础
15:01 向量化与研究
18:24 向量化的分隔符搜索
24:52 基准测试结果
31:45 问答与讨论
第 25 章
SIMD CSV 解析
12BV1PDYy6XEeP
彻底搞懂 Zig 构建系统:DAG 构建图与跨平台编译实战
10:10
2 P
00:00 BlahBlah
00:34 Intro
01:35 Kemeet language server (kls) vs Zig language server (zls)
02:30 zig build vs build-exe vs build-lib vs build-obj
03:33 Creating your first build.zig file
04:07 Understanding the Build function
05:21 zig-cache folder explained
06:07 DAG Model: How Zig executes build steps
07:28 zig-out folder explained
07:35 The prefix flag -p
07:42 How to change the output file name?
07:46 How to change the output path/dir?
07:51 Customizing targets and optimization modes
09:06 How to add the run step to the zig build system?
09:32 Another zls issue
09: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 推荐回看顺序

  1. 先建立心智模型:Allocator 心智模型 → DebugAllocator → Arena → FBA/Pool(第 1–4 讲,约 30 分钟,一口气看完)。
  2. 再过数据结构:ArrayList → HashMap → MultiArrayList → Enum 集合(第 5–8 讲,约 26 分钟),边看边把第 19–22 章的代码跑一遍。
  3. 最后啃长视频: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
内存预算 / OOMDebugAllocatorConfig.enable_memory_limit + requested_memory_limitSafeAllocator.Options 无这两个字段;用 std.testing.FailingAllocator 注入视频里的预算写法直接编译失败
对象池MemoryPool(T) 非托管,另有 Deprecated 的 Managed 包装与 toManaged只剩非托管:.empty + create(gpa) + deinit(gpa)照抄 init(gpa) / create() 会失败
ArrayHashMapstd.StringArrayHashMapUnmanaged 等别名(0.16 已弃用)继续弃用;推荐 std.array_hash_map.String(V) / .Auto(K,V)编译无警告,属于「静默埋雷」类
ArrayList0.16 已是非托管(.empty + append(gpa,x))0.17 保持一致,新增 lockPointers/unlockPointers本讲代码按 0.17 写即可,差异最小
枚举集合std.EnumArray/EnumMap/EnumSet名称与语义不变无需迁移
优化模式std.builtin.OptimizeMode、.ReleaseFaststd.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.argsrun_cmd.addPassthruArgs()字段已移除
包清单.fingerprint 可选0.17 必填;删除后由 zig build 给出建议值新项目初始化时会卡住一次
显式 I/Ostd.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.initBuffer0.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 实验题

  1. 写一个函数 parseTags(gpa, text) ![][]const u8,把逗号分隔的字符串切成切片数组。要求:不复制每个字段、中途失败不泄漏。
  2. ★ 把第 19 章 06_array_list_growth.zig 里的 lockPointers() 之后加一次 append,记录 0.17.1 的实际行为,并解释为什么这个断言比「靠代码审查」可靠。
  3. 一个 HTTP 服务每轮请求要解析 JSON、构造临时字符串、拼响应。请给出 allocator 组合与 reset 的位置,并说明哪些数据不能放进请求 arena。
  4. ★ 用 std.testing.FailingAllocator 把 fail_index 从 0 扫到 8,验证第 16 章 loadConfig 在每个注入点都不泄漏。你怎么自动判断「没泄漏」?
  5. 把第 18 章的 MemoryPool 换成 growable = false 的 Extra 并预热 2 个槽位,创建第 3 个对象会发生什么?
  6. 词频统计里键来自 std.mem.print(&tmp, ...) 生成的字符串。解释为什么直接 put 是错的,并写出覆盖 put 失败的完整释放代码。
  7. ★ 把第 21 章的 Particle 从 ArrayList 换成 MultiArrayList,元素量放大到 100 万,只累加 x,比较两种布局的耗时并说明差异来自哪里。
  8. 一个功能开关系统有 12 个开关,需要频繁做「并集 / 交集 / 是否包含」。选哪个容器?为什么不用 HashMap?
  9. ★ 在第 24 章 11_io_group.zig 基础上,把一个任务改成返回 error.Canceled,观察 group.await(io) 的行为;再用 defer 在任务里打印一条清理日志,确认取消路径是否执行。
  10. 第 25 章的 scanChunk 把 LANES 从 32 改成 64 需要改哪几处?提示:掩码类型、@ctz 结果类型、补位逻辑。
  11. ★ 给第 26 章的构建脚本再加一个 lint 步骤,让它与 test 并行执行且不依赖 install;用 zig build --list-steps 验证。
  12. 综合题:设计一个「读取 2 GB CSV → 统计每列非空值个数 → 输出报告」的程序。请一次性写出:分配器策略、容器选择、I/O 方式、是否使用 SIMD、构建脚本需要哪些步骤,以及每处选择对应本手册哪一章。

附录 F.2 参考答案要点

  1. 用 std.mem.splitScalar 迭代,把每段切片 append(gpa, part) 进 ArrayList([]const u8);errdefer list.deinit(gpa) 覆盖失败;最后 toOwnedSlice(gpa)。字段本身借用 text,所以还要保证 text 活得比结果久。
  2. 上锁后触发失效的操作会直接断言(0.17 的 lockPointers 就是为此加的)。它把「未来某天有人加了 append 导致悬空」变成「加的当天就崩给你看」,属于把运行期 UB 前移到可诊断失败。
  3. 请求 arena 建在循环外,每轮开头 reset(.retain_capacity);JSON 临时对象、响应字符串都挂上去。不能放进去的:跨请求缓存、长连接会话状态、要写进全局日志队列的内容——这些必须 dupe 到 init.gpa 或长命分配器。
  4. 用 SafeAllocator 作为底层,每次注入后断言 deinit() == 0;或统计 FailingAllocator 的 allocations 与 deallocations 是否相等。不要只看 zig test 退出码(12.4)。
  5. 第三个 create 返回 error.OutOfMemory,因为不可增长的池只能从预热槽位取;这正是把「内存上限」变成可测试约束的做法。
  6. 缓冲区在函数返回后失效,表里留的是悬空切片。写法:const key = try gpa.dupe(u8, dynamic); errdefer gpa.free(key); try map.put(gpa, key, v); defer gpa.free(key);;容器 deinit 不会替你释放键。
  7. SoA 只需连续读 x 通道,AoS 每 12 字节里只用 4 字节且带填充;差距主要来自 cache line 利用率与内存带宽。若循环同时读全部字段,差距会明显缩小甚至反转。
  8. EnumSet:位图,交集 / 并集 / 包含都是位运算,零分配、零哈希、类型安全;HashMap 在这里纯属浪费。
  9. 任务返回 Canceled 是取消传播边界;await 会等待所有任务并反映取消。defer 写在任务内部,正常返回、报错、取消三条路径都会执行,这正是「资源归还」不依赖 group 生命周期的原因。
  10. 掩码类型从 u32 改 u64、向量长度 64、@Vector(64, u1);@ctz 结果仍可转 usize;补位数组 [64]u8,并注意第二块之后 base 的偏移。
  11. 新建 b.step("lint", ...) 与一个 b.addRunArtifact(...)(或 b.addSystemCommand),只 dependOn 对应节点、不 dependOn(b.getInstallStep());--list-steps 应能看到 lint 且执行顺序与 test 无强制先后。
  12. 参考组合: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 时长视频章节时间轴 / 主题要点对应手册章节
1BV1bPno6bEX3
Zig StaticStringMap:将单词转换为值 (0.16.0)
3:34
2 P
00:00 匹配单词
00:37 编译时生成的映射表
01:11 查找机制
01:48 大小写不敏感
02:17 最长匹配
02:49 枚举名称的快捷方式
03:16 下期预告
第 27 章
编译期字符串分派
2BV1DAno6FENM
Zig PriorityQueue and Deque: 两种队列 (0.16.0)
3:29
2 P
00:00 接下来要讲的内容
00:35 最紧急的优先
01:09 最小或最大优先
01:40 结合额外数据比较
02:12 两端都可操作的队列
02:41 保留最后几项
03:09 下期预告
第 28 章
堆与环形双端队列
3BV1o7hx6yEL4
Zig 作者带你用面向数据设计 (DoD)编程构建高性能应用
46:40
2 P
简介未列时间轴;要点:CPU 与内存墙、缓存未命中、索引替指针、布尔外置、SoA、上下文特定编码第 29 章
五个瘦身技巧 + 实测
4BV1HbpC6QEBK
Zig 之父 Andrew Kelley:拆解并发编程中最痛苦的难题–取消 / 终止任务
47:10
2 P
简介未列时间轴;要点:定时器中断、缓存争用、Amdahl 定律、EINTR、musl 信号处理、线程取消第 30 章
取消协议与资源归还
5BV1ykhx6tEjf
Zig 创始人 Andrew Kelley:为什么我不建议数据结构里继续用指针(无指针编程)
10:01
2 P
简介为空;主题依据标题与演讲者:数据结构内部不再存放指针第 31 章
索引 / 世代句柄
6BV1mmxc6JEqV
Zig 内存布局优于 C
9:47
2 P
00:00 简介
00:35 数学原理
01:24 对齐规则
02:08 SerpApi
03:15 调试
04:01 完全控制(内存布局 & IPv4)
05:22 C语言怎么样?(位域问题)
07:27 C23
08:08 为什么有 131,071 种类型?
09:30 再见
第 32 章
位宽 / packed / 线格式

附录 G.1 原始演讲 / 视频出处

讲原视频 / 原作者发布时间
27 StaticStringMapZig StaticStringMap: turning words into values · Ziggurat2026-10-21
28 PriorityQueue & DequeZig PriorityQueue and Deque: two kinds of line · Ziggurat2026-10-21
29 DoD 实战A Practical Guide to Applying Data Oriented Design · Andrew Kelley / ChimiChanga2024-07-13
30 取消 / 终止任务Getting Canceled · Andrew Kelley / Zig SHOWTIME2026-10-13
31 无指针编程Andrew Kelley 演讲(B 站简介为空,未给出原视频链接)2026-09-23 上传
32 内存布局优于 CZig Memory Layout is Better Than C · Code Guild2026-10-29

附录 G.2 推荐回看顺序

  1. 先补两块容器短板:第 27、28 讲各 3 分半,配合第 27、28 章代码一起看,成本最低、收获最直接。
  2. 再走性能线:第 29 讲(93 分钟,可分段)→ 第 31 讲(10 分钟)→ 第 32 讲(约 10 分钟)。建议按 29 → 31 → 32 的顺序,因为索引、位宽、布局是同一个故事的三层。
  3. 最后啃取消:第 30 讲 94 分钟,建议先读完第 30.3 节的标准库 API 表再回看,重点听 EINTR 与资源归还那一段。
  4. 对照阅读:第 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 实验题

  1. 给第 27 章的映射表加 10 个长度都是 4 的键,用 comptime 断言 keys() 的顺序,并解释此时 get() 的最坏比较次数。
  2. ★ 把第 28 章 byDist 里的 id 平局判断去掉,构造两个距离相同的元素,观察 update() 实际改到了哪一个,并说明源码里哪一行导致了这个结果。
  3. 用 Deque.initBuffer 实现容量 8 的撤销栈:前端插入、满了丢弃最旧一条。为什么这里不能用 ArrayList?
  4. ★ 把第 29 章的 benchmark 改成同时累加 x 与 y,记录比值变化;再用 -Doptimize=fast 跑一次,解释两次结果的差别。
  5. ★ 在第 30 章 19_io_cancel.zig 的任务里把 checkCancel 的错误 catch {} 吞掉,观察 group.cancel 之后任务是否跑完;再用 recancel 或把错误继续 try 出去修复。
  6. 给第 31 章的 Store 加一个空闲索引栈(也是 u32 数组)取代线性扫描,说明插入复杂度变化;再把 generation 改成 u8 并循环复用同一槽位 300 次,会发生什么?
  7. ★ 把第 32 章的 Ipv4Header 删掉 src/dst 换成 96 位版本,记录 @sizeOf / @alignOf;另写一个函数,从 [20]u8 线格式里用 readInt 取出 version、ihl、total_length、protocol。
  8. 综合题:设计一个「每秒处理百万条日志、可随时优雅停止」的 Zig 程序。一次性写出:数据布局(29/31 章)、容器选择(27/28/20 章)、取消协议(30/24 章)、线格式处理(32 章)、以及构建与压测步骤(26 章),并指出每处选择对应哪一章。

附录 H.2 参考答案要点

  1. keys() 按「长度升序 + 同长度字典序」排列,可用 comptime { for (map.keys(), 0..) ... } 断言。长度桶退化为 10 个同长键,最坏要比较 10 次字符串;键多且长度集中时应改用 StringHashMap。
  2. update() 用 compareFn(context, item, elem) == .eq 线性查找下标,去掉 id 平局后所有同距离元素都「相等」,它会命中第一个而非目标元素。修法:比较函数必须构成严格弱序且能区分身份(距离 + id),或让优先级成为元素字段。
  3. 前端插入 + 容量固定 + 丢弃最旧,正是 Deque 的 O(1) 两端操作;ArrayList 头部插入是 O(n) 搬移。注意 initBuffer 只能用 Bounded 系列方法,满时先 popBack()(或 popFront(),取决于哪端是「最旧」)再插入。
  4. 同时读两个字段时 AoS 的有效字节比例翻倍,差距会缩小;SoA 需要两个数组、两次遍历或一次同时遍历两个数组。-Doptimize=fast 下 SoA 可能被向量化,差距重新拉大,而 AoS 因跨步访问难以向量化。结论必须写清优化模式与机器,不能只报一个倍数。
  5. 吞掉 error.Canceled 后请求已被消费,后续 checkCancel 不会再报(对应 0.17 源码注释),任务一路跑到 2000 万次循环,取消形同虚设。正确做法是把错误继续向上传播,或在确实需要延后的临界区后调用 std.Io.recancel(io);defer 清理仍会执行,但「及时停止」已丢失。
  6. 空闲索引栈把插入从 O(n) 扫描降到 O(1) 弹栈,删除时把索引压回。u8 世代 256 次后回绕到 0,第 257 次复用会让最早的旧句柄重新变成「有效」——这就是 ABA 复现;生产代码用更宽的世代或永不复用槽位。
  7. 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,那是内存布局而不是协议布局。
  8. 参考组合:日志字段按访问频率做热/冷拆分,热字段用 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

PNX2015 MPEG视频解码器硬件架构深度解析与设计实践 视频解码是多媒体处理的核心技术,其本质是将压缩编码后的视频数据流还原为原始像素序列的过程。其原理基于离散余弦变换、量化和熵编码等数学方法,通过去除空间和时间冗余实现高效压缩。在嵌入式系统中,硬件解码器通过专用流水线架构,以远高于软件解码的能效比实现实时解码,技术价值在于显著降低CPU负载与系统功耗。典型的应用场景包括数字电视、机顶盒、DVD播放器等消费电子设备。本文以飞利浦PNX2015媒体处理器中的MPEG解码器为案例,深入剖析其**变长解码器**和**运动补偿**等关键模块的硬件实现细节、数据流设计与软 阅读详情

相关推荐

【信息科学与工程学】【物理/化学科学和工程技术】知识体系06 材料力学(1)

材料力学的高级理论和现代发展,涵盖非线性材料本构、塑性理论、复合材料力学、断裂力学、板壳理论、数值方法、实验技术和跨尺度多物理场耦合。这些内容代表了材料力学从经典理论到现代发展的前沿,为复杂工程问题的分析和解决提供了更强大的工具。每个领域都有其深厚的理论基础和广泛的应用背景,实际研究中往往需要根据具体问题选择和组合适当的理论和方法。

weixin_49199313的博客 1190

Claude Mythos Preview:AI安全能力阶跃与漏洞挖掘范式变革

AI安全模型正从专用工具迈向通用系统思维引擎,其核心在于对软件系统‘设计契约’的建模与反向推理能力。不同于传统模糊测试或规则匹配,新一代模型如Claude Mythos通过融合源码、协议规范与全生命周期审计数据,实现跨语言、跨架构的零日漏洞发现与利用链自动生成。这种能力本质是将安全分析升维为约束满足问题求解,显著压缩红蓝对抗周期,并推动DevSecOps从‘响应式修复’转向‘契约驱动防御’。在SWE-bench Pro 77.8%与CVE-2026–4747等实证中,它已展现出穿透时间壁垒与抽象语法树(AS

banshen0201的博客 347

chrome-win64-159.0.8145.0(Canary).zip

内容概要:Chrome for Testing 官方 chrome 159.0.8145.0 win64 平台(金丝雀版通道),原版未修改,附来源说明。 适合人群:Windows 64 位 上的自动化测试工程师、爬虫开发者、CI 环境搭建者。 使用场景及目标:①Chrome for Testing 官方浏览器本体,供自动化测试使用;②与同版本 chromedriver 配套;③CI/容器环境的浏览器运行时。 其他说明:Chrome for Testing 为 Google 官方发布、允许自由分发的文件;本资源为第三方整理的下载便利服务。

OpenCode Skills系统:可审计、沙箱化、语义驱动的编码自动化范式

Skills是现代IDE中新兴的声明式自动化范式,它超越传统插件模型,以YAML元数据定义触发逻辑、权限边界与执行契约,依托三层沙箱(元数据沙箱、运行时沙箱、上下文感知沙箱)保障安全与稳定性。其核心价值在于将开发者重复操作提炼为可读、可审、可版本控制的‘人类语言自动化’,天然支持审计与协作;技术上深度融合Git语义上下文、离线NLP意图识别及联邦学习式行为适应,广泛应用于CI/CD提效、跨仓库PR关联、合规提交强制、技术文档自动生成等工程场景。本文深入解析Skills设计哲学、执行模型与生产级避坑实践。

weixin_30875157的博客 307

chrome-headless-shell-win64-157.0.8103.38(Stable).zip

Chrome for Testing 官方指定版本的 Chrome 浏览器、ChromeDriver 与 Headless Shell 压缩包,适用于 Selenium、Playwright 等自动化测试环境搭建,覆盖 Windows、macOS、Linux 多平台,解压即可使用,无需额外安装或配置。

chrome-win32-159.0.8150.0(Canary).zip

内容概要:Chrome for Testing 官方 chrome 159.0.8150.0 win32 平台(金丝雀版通道),原版未修改,附来源说明。 适合人群:Windows 32 位 上的自动化测试工程师、爬虫开发者、CI 环境搭建者。 使用场景及目标:①Chrome for Testing 官方浏览器本体,供自动化测试使用;②与同版本 chromedriver 配套;③CI/容器环境的浏览器运行时。 其他说明:Chrome for Testing 为 Google 官方发布、允许自由分发的文件;本资源为第三方整理的下载便利服务。

Bun 与 Node.js 运行时本质差异解析:引擎重构而非简单替代

JavaScript 运行时是现代前端与后端开发的底层基石,其性能、兼容性与生态适配能力直接影响工程效率。Node.js 基于 V8 + libuv 构建,强调稳定性与生态广度;Bun 则以 Zig 重写运行时内核,采用 JSC 分支引擎、自研 I/O 调度器与纯 ESM 模块系统,实现启动速度提升 3 倍、内存峰值降低 25% 等硬指标突破。这种差异并非版本迭代,而是对‘运行时’概念的范式重构——它舍弃了 Node.js 的兼容包袱,换取极致 I/O 效率与构建性能,天然适配 TypeScript 原生执

weixin_33853827的博客 362

chromedriver-win32-160.0.8164.0(Canary).zip

chromedriver-win32-160.0.8164.0(Canary).zip

LLVM项目深度解析:编译器基础设施操作系统架构与实战

LLVM是一种面向现代软件工程的模块化编译器基础设施,其核心是统一、可验证、架构无关的LLVM IR中间表示。它通过前端-IR-优化-后端四层抽象实现跨语言、跨硬件的代码生成能力,支撑Rust、Swift、CUDA、WebAssembly等关键技术栈。凭借TableGen驱动的声明式后端、LTO链接时优化、bitcode可重链接特性及lld等高性能工具链,LLVM已成为芯片适配、编程语言实现和系统级性能优化的事实标准。本文聚焦llvm-project的工业级架构设计、IR本质、定制化工具链构建与真实场景排坑

weixin_33851604的博客 196

化工MES-石化盈科信息技术有限责任公司.pptx

化工MES-石化盈科信息技术有限责任公司.pptx

健康管理服务运营方案.pptx

健康管理服务运营方案.pptx

Jace开源教程:一种约束驱动的工程化教学范式

在软件工程教育中,'可复现性'与'契约式设计'正成为衡量技术教程质量的核心指标。本文围绕Jace这一轻量级开源实践体系,解析其如何通过编译期约束(如C++20 concepts)、文档即代码机制、可控失控实验等手段,构建面向工业级代码素养的训练路径。它不聚焦于某类框架使用,而是系统传授接口设计原则、状态机验证方法和跨平台构建治理——尤其适合嵌入式、边缘AI及实时系统方向的开发者建立对内存布局、原子操作、静态断言等底层工程要素的直觉。教程强调‘透明到枯燥’的设计哲学,将调试过程转化为对预设契约的持续校验。

weixin_34101229的博客 285

钢铁行业工业互联网安全解决方案.pptx

钢铁行业工业互联网安全解决方案.pptx

【FDE知识库】(1):AI 编程时代开发语言选型分析,云使用go,企业用java,算法python,底层c

AI 编程时代,开发语言选型需综合考量AI适配度、编译速度、跨平台与学习成本。Python以海量语料和即时执行成首选,适用于AI/ML与原型开发;TypeScript凭借类型系统与秒级构建,成为前端及应用层主流;Go以极速编译与统一风格,契合AI代理高效迭代需求。Rust/C++虽性能强,但编译慢、学习成本高,不适于快速试错。综合推荐:优先选Python、TypeScript、Go,兼顾效率与生态,实现最优AI协作体验。

freewebsys的专栏 763

集团S&OP供应链计划管理蓝图规划方案(供应链二).pptx

集团S&OP供应链计划管理蓝图规划方案(供应链二).pptx

互联网 医联体信息化建设和实施解决方案.pptx

互联网 医联体信息化建设和实施解决方案.pptx

TVJ1120资源及合并指令

内容概要:本文提供了TVJ1120.apk拆分文件的下载链接及合并方法,包含两个分卷文件(part1和part2)的CSDN下载地址,并给出在Windows系统下使用copy命令将两个分卷合并为完整APK文件的具体指令。同时提供使用certutil工具对合并后的TVJ1120.apk进行SHA256哈希值校验的命令,以确保文件完整性与安全性。; 适合人群:具备基本计算机操作能力,熟悉命令行工具使用的开发者或技术人员;需要下载并验证安卓应用文件完整性的用户。; 使用场景及目标:①用于从分卷压缩或拆分的APK文件中恢复完整的安装包;②通过哈希校验确保下载的APK文件未被篡改或损坏,保障应用安全性和可用性;③适用于软件分发、移动应用测试、逆向分析等技术场景。; 阅读建议:在操作前确认已下载全部分卷文件,并在相同目录下执行合并命令;建议严格比对生成的SHA256值与官方提供的校验值,防止运行不安全的应用程序。

CD-HIT的使用

继续我的生信笔记系列。从某网站的附带文献中读到该工具,搜索了一下,发现网上的大佬们都在讲如何用它去冗余,相对官方页面的介绍而言很是片面,于是刚好有聚类的需求的我准备对其全体功能做做实验,学习一下由李伟忠博士在伯纳姆研究所(现为桑福德伯纳姆医学研究所)亚当·戈兹克博士的实验室开发的牛工具。 首先是官方介绍: CD-HIT是一个非常广泛使用的程序,用于蛋白质或核苷酸序列的聚类和比较。最初由李伟忠博士在伯纳姆研究所(现为桑福德伯纳姆医学研究所)亚当·戈兹克博士的实验室开发,CD-HIT速度非常快,可以处理非常

一名学术waste的note pro 1万+
上一篇: Zig 核心语法学习手册【0.17版本】
下一篇: Zig 学习材料 · 任务取消与线程底层
rustroom
博客等级 码龄12年 2198粉丝 471原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值
⌂ 换网址