docs(course): 适配 Zig 0.16 课程代码示例 API 变更

- 使用 Io.Threaded API 重构 echo_tcp_server 示例
- 更新 @EnumLiteral、@struct 等内建函数调用
- 修复 std.time.timestamp() 被移除的兼容性问题
- 更新 MemoryPool 初始化和 captureStdOut() 调用方式

Author: jinzhongjia

build/0.16.zig

@@ -33,7 +33,6 @@ pub fn build(b: *Build) void {
             // get the entry name, entry can be file or directory
             const output_name = std.mem.trimRight(u8, entry.name, ".zig");
             if (entry.kind == .file) {
-
                 // connect path
                 const path = std.fs.path.join(b.allocator, &[_][]const u8{ relative_path, entry.name }) catch |err| {
                     log.err("fmt path for examples failed, err is {}", .{err});

course/code/16/build_system/externalfile/build.zig

@@ -36,7 +36,7 @@ pub fn build(b: *std.Build) !void {
 
     // 尝试运行命令并捕获标准输出
     // 也可以使用 captureStdErr 来捕获标准错误输出
-    const output = run_sys_cmd.captureStdOut();
+    const output = run_sys_cmd.captureStdOut(.{});
 
     // 添加一个匿名的依赖
     exe.root_module.addAnonymousImport("hello", .{ .root_source_file = output });

course/code/16/build_system/options/build.zig

@@ -17,8 +17,9 @@ pub fn build(b: *std.Build) void {
         }),
     });
 
-    // 通过标准库获取时间戳
-    const timestamp = std.time.timestamp();
+    // 获取一个简单的时间值用于演示 options 功能
+    // 注意：Zig 0.16 移除了 std.time.timestamp()，这里使用示例值
+    const timestamp: i64 = 1700000000; // 示例时间戳
 
     // 创建一个 options
     const options = b.addOptions();

course/code/16/echo_tcp_server.zig

@@ -1,180 +1,80 @@
 const std = @import("std");
 const builtin = @import("builtin");
-const net = std.net;
-const windows = std.os.windows;
-const linux = std.os.linux;
-
-// POLLIN, POLLERR, POLLHUP, POLLNVAL 均是 poll 的事件
-
-/// windows context 定义
-const windows_context = struct {
-    const POLLIN: i16 = 0x0100;
-    const POLLERR: i16 = 0x0001;
-    const POLLHUP: i16 = 0x0002;
-    const POLLNVAL: i16 = 0x0004;
-    const INVALID_SOCKET = windows.ws2_32.INVALID_SOCKET;
-};
-
-/// linux context 定义
-const linux_context = struct {
-    const POLLIN: i16 = 0x0001;
-    const POLLERR: i16 = 0x0008;
-    const POLLHUP: i16 = 0x0010;
-    const POLLNVAL: i16 = 0x0020;
-    const INVALID_SOCKET = -1;
-};
-
-/// macOS context 定义
-const macos_context = struct {
-    const POLLIN: i16 = 0x0001;
-    const POLLERR: i16 = 0x0008;
-    const POLLHUP: i16 = 0x0010;
-    const POLLNVAL: i16 = 0x0020;
-    const INVALID_SOCKET = -1;
-};
-
-const context = switch (builtin.os.tag) {
-    .windows => windows_context,
-    .linux => linux_context,
-    .macos => macos_context,
-    else => @compileError("unsupported os"),
-};
+const Io = std.Io;
+const net = Io.net;
 
 pub fn main() !void {
     // #region listen
-    // 解析地址
-    const port = 8080;
-    const address = try net.Address.parseIp4("127.0.0.1", port);
+    // 初始化 Threaded I/O 后端（单线程模式）
+    var threaded: Io.Threaded = .init_single_threaded;
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    // 解析地址并监听
+    const port: u16 = 8080;
+    const address: net.IpAddress = .{ .ip4 = .loopback(port) };
+
     // 初始化一个server，这里就包含了 socket() 和 bind() 两个过程
-    var server = try address.listen(.{});
-    defer server.deinit();
+    var server = try address.listen(io, .{ .reuse_address = true });
+    defer server.deinit(io);
     // #endregion listen
 
-    // #region data
-    // 定义最大连接数
-    const max_sockets = 1000;
-    // buffer 用于存储 client 发过来的数据
-    var buf: [1024]u8 = std.mem.zeroes([1024]u8);
-    // 存储 accept 拿到的 connections
-    var connections: [max_sockets]?net.Server.Connection = undefined;
-    // sockfds 用于存储 pollfd, 用于传递给 poll 函数
-    var sockfds: [max_sockets]if (builtin.os.tag == .windows)
-        windows.ws2_32.pollfd
-    else
-        std.posix.pollfd = undefined;
-    // #endregion data
-    for (0..max_sockets) |i| {
-        sockfds[i].fd = context.INVALID_SOCKET;
-        sockfds[i].events = context.POLLIN;
-        connections[i] = null;
-    }
-    sockfds[0].fd = server.stream.handle;
-
     std.log.info("start listening at {d}...", .{port});
 
-    // 无限循环，等待客户端连接或者已连接的客户端发送数据
+    // 无限循环，等待客户端连接
     while (true) {
-        // 调用 poll，nums 是返回的事件数量
-        var nums = if (builtin.os.tag == .windows) windows.poll(&sockfds, max_sockets, -1) else try std.posix.poll(&sockfds, -1);
-        if (nums == 0) {
-            continue;
-        }
-        // 如果返回的事件数量小于0，说明出错了
-        // 仅仅在 windows 下会出现这种情况
-        if (nums < 0) {
-            @panic("An error occurred in poll");
-        }
-
-        // NOTE: 值得注意的是，我们使用的模型是先处理已连接的客户端，再处理新连接的客户端
+        // #region new-connection
+        // 等待新的连接
+        std.log.info("waiting for client...", .{});
+        const stream = try server.accept(io);
+        std.log.info("new client connected!", .{});
+        // #endregion new-connection
 
         // #region exist-connections
-        // 遍历所有的连接，处理事件
-        for (1..max_sockets) |i| {
-            // 这里的 nums 是 poll 返回的事件数量
-            // 在windows下，WSApoll允许返回0，未超时且没有套接字处于指定的状态
-            if (nums == 0) {
+        // 处理客户端数据（简化版本：一次处理一个客户端）
+        // 初始化读写缓冲区
+        var read_buffer: [4096]u8 = undefined;
+        var write_buffer: [4096]u8 = undefined;
+        var reader = stream.reader(io, &read_buffer);
+        var writer = stream.writer(io, &write_buffer);
+
+        while (true) {
+            // 读取客户端发送的数据
+            // 使用 peekGreedy(1) 获取至少 1 字节，返回所有可用数据
+            const data = reader.interface.peekGreedy(1) catch |err| {
+                if (err == error.EndOfStream) {
+                    std.log.info("client disconnected", .{});
+                    break;
+                }
+                if (reader.err) |read_err| {
+                    std.log.err("read error: {}", .{read_err});
+                }
                 break;
-            }
-            const sockfd = sockfds[i];
-
-            // 检查是否是无效的 socket
-            if (sockfd.fd == context.INVALID_SOCKET) {
-                continue;
-            }
-
-            // 由于 windows 针对无效的socket也会触发POLLNVAL
-            // 当前 sock 有 IO 事件时，处理完后将 nums 减一
-            defer if (sockfd.revents != 0) {
-                nums -= 1;
             };
 
-            // 检查是否是 POLLIN 事件，即是否有数据可读
-            if (sockfd.revents & (context.POLLIN) != 0) {
-                const c = connections[i];
-                if (c) |connection| {
-                    const len = try connection.stream.read(&buf);
-                    // 如果连接已经断开，那么关闭连接
-                    // 这是因为如果已经 close 的连接，读取的时候会返回0
-                    if (len == 0) {
-                        // 但为了保险起见，我们还是调用 close
-                        // 因为有可能是连接没有断开，但是出现了错误
-                        connection.stream.close();
-                        // 将 pollfd 和 connection 置为无效
-                        sockfds[i].fd = context.INVALID_SOCKET;
-                        std.log.info("client from {any} close!", .{
-                            connection.address,
-                        });
-                        connections[i] = null;
-                    } else {
-                        // 如果读取到了数据，那么将数据写回去
-                        // 但仅仅这样写一次并不安全
-                        // 最优解应该是使用for循环检测写入的数据大小是否等于buf长度
-                        // 如果不等于就继续写入
-                        // 这是因为 TCP 是一个面向流的协议
-                        // 它并不保证一次 write 调用能够发送所有的数据
-                        // 作为示例，我们不检查是否全部写入
-                        _ = try connection.stream.write(buf[0..len]);
-                    }
-                }
-            }
-            // 检查是否是 POLLNVAL | POLLERR | POLLHUP 事件，即是否有错误发生，或者连接断开
-            else if ((sockfd.revents &
-                (context.POLLNVAL | context.POLLERR | context.POLLHUP)) != 0)
-            {
-                // 将 pollfd 和 connection 置为无效
-                sockfds[i].fd = context.INVALID_SOCKET;
-                connections[i] = null;
-                std.log.info("client {} close", .{i});
+            if (data.len == 0) {
+                std.log.info("client disconnected", .{});
+                break;
             }
-        }
-        // #endregion exist-connections
 
-        // #region new-connection
-        // 检查是否有新的连接
-        // 这里的 sockfds[0] 是 server 的 pollfd
-        // 这里的 nums 检查可有可无，因为我们只关心是否有新的连接，POLLIN 就足够了
-        if (sockfds[0].revents & context.POLLIN != 0 and nums > 0) {
-            std.log.info("new client", .{});
-            // 如果有新的连接，那么调用 accept
-            const client = try server.accept();
-            for (1..max_sockets) |i| {
-                // 找到一个空的 pollfd，将新的连接放进去
-                if (sockfds[i].fd == context.INVALID_SOCKET) {
-                    sockfds[i].fd = client.stream.handle;
-                    connections[i] = client;
-                    std.log.info("new client {} comes", .{i});
-                    break;
-                }
-                // 如果没有找到空的 pollfd，那么说明连接数已经达到了最大值
-                if (i == max_sockets - 1) {
-                    @panic("too many clients");
+            // 消费已读取的数据
+            reader.interface.toss(data.len);
+
+            // 将数据写回给客户端（echo）
+            writer.interface.writeAll(data) catch |err| {
+                std.log.err("write error: {}", .{err});
+                if (writer.err) |write_err| {
+                    std.log.err("underlying error: {}", .{write_err});
                 }
-            }
+                break;
+            };
+            writer.interface.flush() catch |err| {
+                std.log.err("flush error: {}", .{err});
+                break;
+            };
         }
-        // #endregion new-connection
-    }
 
-    if (builtin.os.tag == .windows) {
-        try windows.ws2_32.WSACleanup();
+        stream.close(io);
+        // #endregion exist-connections
     }
 }

course/code/16/enum.zig

@@ -147,12 +147,12 @@ const EnumLiteral_ = struct {
     const std = @import("std");
     pub fn main() !void {
         // #region enum_literal
-        // 使用内建函数 @Type 构造出一个 EnumLiteral 类型
-        // 这是目前官方文档中的使用方案
-        const EnumLiteral: type = @Type(.enum_literal);
+        // 使用内建函数 @EnumLiteral 构造出一个 EnumLiteral 类型
+        // Zig 0.16 使用 @EnumLiteral() 替代 @Type(.enum_literal)
+        const EnumLiteralType: type = @EnumLiteral();
 
-        // 定义一个常量 enum_literal，它的类型为 EnumLiteral，并赋值为 “.kkk”
-        const enum_literal: EnumLiteral = .kkk;
+        // 定义一个常量 enum_literal，它的类型为 EnumLiteral，并赋值为 ".kkk"
+        const enum_literal: EnumLiteralType = .kkk;
 
         // 使用内建函数 @tagName 获取 enum_literal 的 tag name，并进行打印
         std.debug.print("enum_literal is {s}", .{@tagName(enum_literal)});

course/code/16/memory_manager.zig

@@ -208,18 +208,19 @@ const MemoryPool = struct {
 
     pub fn main() !void {
         // 此处为了演示，直接使用page allocator
-        var pool = std.heap.MemoryPool(u32).init(std.heap.page_allocator);
-        defer pool.deinit();
+        // Zig 0.16 中 MemoryPool 使用 .empty 常量初始化
+        var pool: std.heap.MemoryPool(u32) = .empty;
+        defer pool.deinit(std.heap.page_allocator);
 
         // 连续申请三个对象
-        const p1 = try pool.create();
-        const p2 = try pool.create();
-        const p3 = try pool.create();
+        const p1 = try pool.create(std.heap.page_allocator);
+        const p2 = try pool.create(std.heap.page_allocator);
+        const p3 = try pool.create(std.heap.page_allocator);
 
         // 回收p2
         pool.destroy(p2);
         // 再申请一个新的对象
-        const p4 = try pool.create();
+        const p4 = try pool.create(std.heap.page_allocator);
 
         // 注意，此时p2和p4指向同一块内存
         _ = p1;

course/code/16/reflection.zig

@@ -106,17 +106,23 @@ const TypeInfo3 = struct {
 
     fn ExternAlignOne(comptime T: type) type {
         // 获得类型信息，并断言为Struct.
-        comptime var struct_info = @typeInfo(T).@"struct";
-        // 将内存布局改为 extern
-        struct_info.layout = .@"extern";
-        // 复制字段信息（原为只读切片，故需复制）
-        comptime var new_fields = struct_info.fields[0..struct_info.fields.len].*;
-        // 修改每个字段对齐为1
-        inline for (&new_fields) |*f| f.alignment = 1;
-        // 替换字段定义
-        struct_info.fields = &new_fields;
-        // 重新构造类型
-        return @Type(.{ .@"struct" = struct_info });
+        const struct_info = @typeInfo(T).@"struct";
+        // 准备字段名称
+        comptime var field_names: [struct_info.fields.len][]const u8 = undefined;
+        comptime var field_types: [struct_info.fields.len]type = undefined;
+        comptime var field_attrs: [struct_info.fields.len]std.builtin.Type.StructField.Attributes = undefined;
+
+        inline for (struct_info.fields, 0..) |field, i| {
+            field_names[i] = field.name;
+            field_types[i] = field.type;
+            // 设置对齐为 1，其他属性使用默认值
+            field_attrs[i] = .{
+                .@"align" = 1,
+            };
+        }
+
+        // 使用 @Struct 构造新类型（extern 布局，对齐为 1）
+        return @Struct(.@"extern", null, &field_names, &field_types, &field_attrs);
     }
 
     const MyStruct = struct {
@@ -244,22 +250,14 @@ const Type = struct {
     // #region Type
     const std = @import("std");
 
-    const T = @Type(.{
-        .@"struct" = .{
-            .layout = .auto,
-            .fields = &.{
-                .{
-                    .alignment = 8,
-                    .name = "b",
-                    .type = u32,
-                    .is_comptime = false,
-                    .default_value_ptr = null,
-                },
-            },
-            .decls = &.{},
-            .is_tuple = false,
-        },
-    });
+    // Zig 0.16 使用 @Struct 替代 @Type
+    const T = @Struct(
+        .auto, // layout
+        null, // BackingInt
+        &.{"b"}, // field_names
+        &.{u32}, // field_types
+        &.{.{ .@"align" = 8 }}, // field_attrs
+    );
 
     pub fn main() void {
         const D = T{