跳转到内容
语言参考Zig 0.17.0官方原文

错误集合类型

错误集合类似于 enum。不过,在整个编译过程中,每个错误名称都会被分配一个大于 0 的无符号整数。允许多次声明同一个错误名称,它们会被分配相同的整数值。

错误集合类型默认使用 u16;如果用命令行参数 --error-limit [num] 指定不同错误值的最大数量,就会改用位数最少、足以表示所有错误值的整数类型。

可以将错误从子集强制转换到超集:

test_coerce_error_subset_to_superset.zig
const std = @import("std");
const FileOpenError = error{
AccessDenied,
OutOfMemory,
FileNotFound,
};
const AllocationError = error{
OutOfMemory,
};
test "coerce subset to superset" {
const err = foo(AllocationError.OutOfMemory);
try std.testing.expectEqual(FileOpenError.OutOfMemory, err);
}
fn foo(err: AllocationError) FileOpenError {
return err;
}
命令行
$ zig test test_coerce_error_subset_to_superset.zig
1/1 test_coerce_error_subset_to_superset.test.coerce subset to superset...OK
All 1 tests passed.

但是不能将错误从超集强制转换到子集:

test_coerce_error_superset_to_subset.zig
const FileOpenError = error{
AccessDenied,
OutOfMemory,
FileNotFound,
};
const AllocationError = error{
OutOfMemory,
};
test "coerce superset to subset" {
foo(FileOpenError.OutOfMemory) catch {};
}
fn foo(err: FileOpenError) AllocationError {
return err;
}
命令行
$ zig test test_coerce_error_superset_to_subset.zig
/home/andy/src/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: error: expected type 'error{OutOfMemory}', found 'error{AccessDenied,FileNotFound,OutOfMemory}'
return err;
^~~
/home/andy/src/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: note: 'error.AccessDenied' not a member of destination error set
/home/andy/src/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: note: 'error.FileNotFound' not a member of destination error set
/home/andy/src/zig/doc/langref/test_coerce_error_superset_to_subset.zig:15:28: note: function return type declared here
fn foo(err: FileOpenError) AllocationError {
^~~~~~~~~~~~~~~
referenced by:
test.coerce superset to subset: /home/andy/src/zig/doc/langref/test_coerce_error_superset_to_subset.zig:12:8

只有 1 个值的错误集合,有一种写法可以同时声明并取出该值:

single_value_error_set_shortcut.zig
const err = error.FileNotFound;

这等价于:

single_value_error_set.zig
const err = (error{FileNotFound}).FileNotFound;

使用推导错误集合时,这种写法很有用。

全局错误集合

anyerror 指的是全局错误集合,包含整个编译单元中的所有错误,也就是其他所有错误集合的并集。

可以将任意错误集合强制转换到全局错误集合,也可以将全局错误集合中的错误显式转换到非全局集合。后者会插入语言级断言,确保该错误值确实属于目标错误集合。

通常应避免使用全局错误集合,因为它使编译器无法在编译时确定可能出现的错误。编译时已知的错误集合有利于生成文档和有帮助的错误信息,例如提示 switch 遗漏了某个可能的错误值。

错误联合类型

错误集合类型和普通类型可以通过二元运算符 ! 组合为错误联合类型。通常,错误联合类型比单独的错误集合类型更常用。

下面的函数把字符串解析成 64 位整数:

error_union_parsing_u64.zig
const std = @import("std");
const maxInt = std.math.maxInt;
pub fn parseU64(buf: []const u8, radix: u8) !u64 {
var x: u64 = 0;
for (buf) |c| {
const digit = charToDigit(c);
if (digit >= radix) {
return error.InvalidChar;
}
// x *= radix
var ov = @mulWithOverflow(x, radix);
if (ov[1] != 0) return error.OverFlow;
// x += digit
ov = @addWithOverflow(ov[0], digit);
if (ov[1] != 0) return error.OverFlow;
x = ov[0];
}
return x;
}
fn charToDigit(c: u8) u8 {
return switch (c) {
'0'...'9' => c - '0',
'A'...'Z' => c - 'A' + 10,
'a'...'z' => c - 'a' + 10,
else => maxInt(u8),
};
}
test "parse u64" {
const result = try parseU64("1234", 10);
try std.testing.expectEqual(1234, result);
}
命令行
$ zig test error_union_parsing_u64.zig
1/1 error_union_parsing_u64.test.parse u64...OK
All 1 tests passed.

注意返回类型是 !u64,表示函数要么返回无符号 64 位整数,要么返回错误。我们省略了 ! 左侧的错误集合,因此错误集合是推导出来的。

函数定义中,有些 return 语句返回错误,底部的 return 语句则返回 u64。这两种类型都能强制转换为 anyerror!u64。

这个函数的用法取决于你想做什么,可能是以下几种情况:

  • 返回错误时提供一个默认值。
  • 返回错误时,从当前函数返回同一个错误。
  • 完全确定不会返回错误,因此希望无条件解包。
  • 针对每一种可能的错误采取不同操作。

catch

如果希望提供默认值,可以使用二元运算符 catch:

catch.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) void {
const number = parseU64(str, 10) catch 13;
_ = number; // ...
}

此代码中,number 等于成功解析字符串得到的值,或者默认值 13。二元 catch 运算符右侧的类型,必须匹配错误联合解包后的类型,或者为 noreturn 类型。

如果希望先执行一些逻辑,再通过 catch 提供默认值,可以将 catch 与具名块结合:

handle_error_with_catch_block.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) void {
const number = parseU64(str, 10) catch blk: {
// 执行操作
break :blk 13;
};
_ = number; // number 现已初始化
}

try

假设遇到错误时希望直接返回该错误,否则继续执行函数逻辑:

catch_err_return.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) !void {
const number = parseU64(str, 10) catch |err| return err;
_ = number; // ...
}

这种情况有一个简写,即 try 表达式:

try.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) !void {
const number = try parseU64(str, 10);
_ = number; // ...
}

try 对错误联合表达式求值。如果是错误,就从当前函数返回同一个错误;否则表达式的结果为解包后的值。

也许你完全确定某个表达式绝不会产生错误,此时可以这样写:

const number = parseU64("1234", 10) catch unreachable;

这里可以确定 "1234" 一定能成功解析,因此把 unreachable 值放在右侧。unreachable 会引发带安全检查的非法行为,所以在 debug 和 safe 模式下,安全检查默认会触发 panic。这样在调试应用时,如果这里确实出现意外错误,应用就会相应崩溃。

如果希望为每种情况采取不同操作,可以结合 if 和 switch 表达式:

handle_all_error_scenarios.zig
fn doAThing(str: []u8) void {
if (parseU64(str, 10)) |number| {
doSomethingWithNumber(number);
} else |err| switch (err) {
error.Overflow => {
// 处理溢出……
},
// 保证不会发生 InvalidChar(如果发生,则在调试模式崩溃)
error.InvalidChar => unreachable,
}
}

最后,也可能只想处理部分错误。此时可以在 else 分支捕获尚未处理的错误,此处得到的错误集合范围更窄:

handle_some_error_scenarios.zig
fn doAnotherThing(str: []u8) error{InvalidChar}!void {
if (parseU64(str, 10)) |number| {
doSomethingWithNumber(number);
} else |err| switch (err) {
error.Overflow => {
// 处理溢出……
},
else => |leftover_err| return leftover_err,
}
}

必须使用变量捕获语法。如果不需要该变量,可以用 _ 捕获,以避免 switch。

handle_no_error_scenarios.zig
fn doADifferentThing(str: []u8) void {
if (parseU64(str, 10)) |number| {
doSomethingWithNumber(number);
} else |_| {
// 按需处理
}
}

errdefer

错误处理的另一个组成部分是 defer 语句。除无条件的 defer 外,Zig 还提供 errdefer:当且仅当函数经由当前块返回错误时,才会在退出该块的路径上执行延迟表达式。

示例:

errdefer_example.zig
fn createFoo(param: i32) !Foo {
const foo = try tryToAllocateFoo();
// 现在已经分配 foo;函数失败时需要释放它。
// 但函数成功时希望将其返回。
errdefer deallocateFoo(foo);
const tmp_buf = allocateTmpBuffer() orelse return error.OutOfMemory;
// tmp_buf 是真正的临时资源,必须在此块退出作用域前
// 将其清理
defer deallocateTmpBuffer(tmp_buf);
if (param > 1337) return error.InvalidParam;
// 此处函数成功返回,因此不会运行 errdefer。
// 但 defer 会运行!
return foo;
}

这样,无须通过冗长代码和额外思考来确认覆盖了每条退出路径,就能实现健壮的错误处理。释放代码始终紧邻分配代码之后。

关于错误处理,还有几点补充:

  • 这些原语已经足够有表达力,完全可以把“未检查错误”直接做成编译错误。如果确实想忽略错误,可以加上 catch unreachable;一旦你的假设有误,它还会在 debug 和 safe 模式下让程序崩溃。
  • 由于 Zig 理解错误类型,它可以预先为分支设置偏好,倾向于错误不发生的路径。这提供了一点其他语言未必具备的优化收益。

另见:

使用二元运算符 ! 创建错误联合。可以通过编译时反射访问错误联合的子类型:

test_error_union.zig
const expectEqual = @import("std").testing.expectEqual;
test "error union" {
var foo: anyerror!i32 = undefined;
// 从错误联合的子类型强制转换:
foo = 1234;
// 从错误集合强制转换:
foo = error.SomeError;
// 使用编译时反射访问错误联合的载荷类型:
try comptime expectEqual(i32, @typeInfo(@TypeOf(foo)).error_union.payload);
// 使用编译时反射访问错误联合的错误集合类型:
try comptime expectEqual(anyerror, @typeInfo(@TypeOf(foo)).error_union.error_set);
}
命令行
$ zig test test_error_union.zig
1/1 test_error_union.test.error union...OK
All 1 tests passed.

合并错误集合

使用 || 运算符合并两个错误集合。结果包含两个集合中的所有错误。左侧文档注释会覆盖右侧文档注释。本例中,C.PathNotFound 的文档注释为 A doc comment。

当函数根据编译时分支返回不同错误集合时,这尤其有用。例如,Zig 标准库使用 LinuxFileOpenError || WindowsFileOpenError 表示打开文件时的错误集合。

test_merging_error_sets.zig
const A = error{
NotDir,
/// A 的文档注释
PathNotFound,
};
const B = error{
OutOfMemory,
/// B 的文档注释
PathNotFound,
};
const C = A || B;
fn foo() C!void {
return error.NotDir;
}
test "merge error sets" {
if (foo()) {
@panic("unexpected");
} else |err| switch (err) {
error.OutOfMemory => @panic("unexpected"),
error.PathNotFound => @panic("unexpected"),
error.NotDir => {},
}
}
命令行
$ zig test test_merging_error_sets.zig
1/1 test_merging_error_sets.test.merge error sets...OK
All 1 tests passed.

推导错误集合

Zig 中许多函数可能返回错误,因此支持推导错误集合。要推导函数的错误集合,在其返回类型前添加 ! 运算符,例如 !T:

test_inferred_error_sets.zig
// 使用推导错误集合
pub fn add_inferred(comptime T: type, a: T, b: T) !T {
const ov = @addWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
// 使用显式错误集合
pub fn add_explicit(comptime T: type, a: T, b: T) Error!T {
const ov = @addWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
const Error = error{
Overflow,
};
const std = @import("std");
test "inferred error set" {
if (add_inferred(u8, 255, 1)) |_| unreachable else |err| switch (err) {
error.Overflow => {}, // 正确
}
}
命令行
$ zig test test_inferred_error_sets.zig
1/1 test_inferred_error_sets.test.inferred error set...OK
All 1 tests passed.

使用推导错误集合的函数会成为泛型函数,因此某些操作会更棘手,例如获取函数指针,或让错误集合在不同构建目标间保持一致。此外,推导错误集合不兼容递归。

这些情况下建议显式指定错误集合。通常可以先使用空错误集合,再依据编译错误提示逐步补全。

未来的 Zig 版本可能克服这些限制。

错误返回追踪

错误返回追踪会显示代码中将错误返回给调用者的所有位置。这样就可以广泛使用 try,即使错误最终一直传播出应用,也仍能知道发生了什么。

error_return_trace.zig
pub fn main() !void {
try foo(12);
}
fn foo(x: i32) !void {
if (x >= 5) {
try bar();
} else {
try bang2();
}
}
fn bar() !void {
if (baz()) {
try quux();
} else |err| switch (err) {
error.FileNotFound => try hello(),
}
}
fn baz() !void {
try bang1();
}
fn quux() !void {
try bang2();
}
fn hello() !void {
try bang2();
}
fn bang1() !void {
return error.FileNotFound;
}
fn bang2() !void {
return error.PermissionDenied;
}
命令行
$ zig build-exe error_return_trace.zig
$ ./error_return_trace
error: PermissionDenied
/home/andy/src/zig/doc/langref/error_return_trace.zig:34:5: 0x11e0c2c in bang1 (error_return_trace.zig)
return error.FileNotFound;
^
/home/andy/src/zig/doc/langref/error_return_trace.zig:22:5: 0x11e0c87 in baz (error_return_trace.zig)
try bang1();
^
/home/andy/src/zig/doc/langref/error_return_trace.zig:38:5: 0x11e0ccc in bang2 (error_return_trace.zig)
return error.PermissionDenied;
^
/home/andy/src/zig/doc/langref/error_return_trace.zig:30:5: 0x11e0da7 in hello (error_return_trace.zig)
try bang2();
^
/home/andy/src/zig/doc/langref/error_return_trace.zig:17:31: 0x11e0eb5 in bar (error_return_trace.zig)
error.FileNotFound => try hello(),
^
/home/andy/src/zig/doc/langref/error_return_trace.zig:7:9: 0x11e0f95 in foo (error_return_trace.zig)
try bar();
^
/home/andy/src/zig/doc/langref/error_return_trace.zig:2:5: 0x11e109c in main (error_return_trace.zig)
try foo(12);
^

仔细观察此示例,这并不是栈追踪。

可以看到,最终向上传播的错误为 PermissionDenied,但最初引发这一过程的错误是 FileNotFound。bar 函数处理了原始错误码,随后从 switch 语句返回另一个错误。错误返回追踪清楚地展示了这一点,而栈追踪看起来则是这样:

stack_trace.zig
pub fn main() void {
foo(12);
}
fn foo(x: i32) void {
if (x >= 5) {
bar();
} else {
bang2();
}
}
fn bar() void {
if (baz()) {
quux();
} else {
hello();
}
}
fn baz() bool {
return bang1();
}
fn quux() void {
bang2();
}
fn hello() void {
bang2();
}
fn bang1() bool {
return false;
}
fn bang2() void {
@panic("PermissionDenied");
}
命令行
$ zig build-exe stack_trace.zig
$ ./stack_trace
thread 704969 panic: PermissionDenied
/home/andy/src/zig/doc/langref/stack_trace.zig:38:5: 0x11e1f2a in bang2 (stack_trace.zig)
@panic("PermissionDenied");
^
/home/andy/src/zig/doc/langref/stack_trace.zig:30:10: 0x11e1fac in hello (stack_trace.zig)
bang2();
^
/home/andy/src/zig/doc/langref/stack_trace.zig:17:14: 0x11e1f63 in bar (stack_trace.zig)
hello();
^
/home/andy/src/zig/doc/langref/stack_trace.zig:7:12: 0x11e1948 in foo (stack_trace.zig)
bar();
^
/home/andy/src/zig/doc/langref/stack_trace.zig:2:8: 0x11e18b1 in main (stack_trace.zig)
foo(12);
^
/home/andy/src/zig/lib/std/start.zig:788:64: 0x11e11db in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/andy/src/zig/lib/std/start.zig:248:5: 0x11e0c11 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

这里的栈追踪没有解释 bar 中的控制流如何到达 hello() 调用。要查清这一点,需要开启调试器或为应用添加更多观测手段。错误返回追踪则精确展示了错误的传播过程。

这个调试功能让快速迭代更轻松,写出的代码也能稳妥处理各种错误情况。也就是说,Zig 开发者为了提高开发速度,会自然而然地写出正确、健壮的代码。

错误返回追踪在 debug 构建中默认启用,在 fast、safe 和 small 构建中默认关闭。

可以通过以下几种方式触发错误返回追踪功能:

  • 从 main 返回错误
  • 错误传播至 catch unreachable,且没有覆盖默认 panic 处理器
  • 使用 errorReturnTrace 访问当前返回追踪,可通过 std.debug.dumpErrorReturnTrace 打印。构建时未启用错误返回追踪支持,该函数返回编译时已知的 null。

实现细节

分析性能成本时,需要区分两种情况:

  • 没有返回错误时
  • 返回错误时

没有返回错误时,只需一次内存写入,而且只发生在调用图中第一个调用可能失败函数的不可失败函数中,也就是返回 void 的函数调用返回 error 的函数时。这次写入用于在栈内存中初始化以下结构体:

stack_trace_struct.zig
pub const StackTrace = struct {
index: usize,
instruction_addresses: [N]usize,
};

这里的 N 是通过调用图分析确定的最大函数调用深度。递归会被忽略,并按 2 层计算。

每个可能返回错误的函数都通过隐藏参数接收指向 StackTrace 的指针。该参数始终位于首位,因此很可能一直保存在寄存器中。

无错误路径的全部开销仅此而已,性能成本几乎为零。

生成返回错误的函数代码时,Zig 会在 return 语句之前生成对以下函数的调用,但仅针对返回错误的 return 语句:

zig_return_error_fn.zig
// 在 LLVM IR 中标记为“no-inline”
fn __zig_return_error(stack_trace: *StackTrace) void {
stack_trace.instruction_addresses[stack_trace.index] = @returnAddress();
stack_trace.index = (stack_trace.index + 1) % N;
}

成本是两次数学运算,以及若干内存读取和写入。访问的内存范围有限,在错误向上传播期间应当一直留在缓存中。

至于代码体积成本,return 之前多一次函数调用不算什么。即便如此,我仍有一项计划,把对 __zig_return_error 的调用改成尾调用,让代码体积成本真正降为零。未启用错误返回追踪时的 return 语句,启用后可以变成一条跳转指令。