{#header_open|undefined#}

{#header_close#}

{#header_open|catch#}

{#header_close#}

{#header_open|try#}

{#header_close#}

the {#link|if#} and {#link|switch#} expression:

{#header_open|errdefer#}

In addition to an unconditional {#link|defer#}, Zig has <code>errdefer</code>,

{#header_close#}

<p>

Error Return Traces show all the points in the code that an error was returned to the calling function. This makes it practical to use {#link|try#} everywhere and then still be able to know what happened if an error ends up bubbling all the way out of your application.

</p>

{#code_begin|exe_err#}

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(),

else => try another(),

}

}

fn baz() !void {

try bang1();

}

fn quux() !void {

try bang2();

}

fn hello() !void {

try bang2();

}

fn another() !void {

try bang1();

}

fn bang1() !void {

return error.FileNotFound;

}

fn bang2() !void {

return error.PermissionDenied;

}

{#code_end#}

<p>

Look closely at this example. This is no stack trace.

</p>

<p>

You can see that the final error bubbled up was <code>PermissionDenied</code>,

but the original error that started this whole thing was <code>FileNotFound</code>. In the <code>bar</code> function, the code handles the original error code,

and then returns another one, from the switch statement. Error Return Traces make this clear, whereas a stack trace would look like this:

</p>

{#code_begin|exe_err#}

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");

}

{#code_end#}

<p>

Here, the stack trace does not explain how the control

flow in <code>bar</code> got to the <code>hello()</code> call.

One would have to open a debugger or further instrument the application

in order to find out. The error return trace, on the other hand,

shows exactly how the error bubbled up.

</p>

<p>

This debugging feature makes it easier to iterate quickly on code that

robustly handles all error conditions. This means that Zig developers

will naturally find themselves writing correct, robust code in order

to increase their development pace.

</p>

<p>

Error Return Traces are enabled by default in {#link|Debug#} and {#link|ReleaseSafe#} builds and disabled by default in {#link|ReleaseFast#} and {#link|ReleaseSmall#} builds.

</p>

<p>

There are a few ways to activate this error return tracing feature:

</p>

<ul>

<li>Return an error from main</li>

<li>An error makes its way to <code>catch unreachable</code> and you have not overridden the default panic handler</li>

<li>Use {#link|errorReturnTrace#} to access the current return trace. You can use <code>std.debug.dumpStackTrace</code> to print it. This function returns comptime-known {#link|null#} when building without error return tracing support.</li>

</ul>

{#header_open|Implementation Details#}

<p>

To analyze performance cost, there are two cases:

</p>

<ul>

<li>when no errors are returned</li>

<li>when returning errors</li>

</ul>

<p>

For the case when no errors are returned, the cost is a single memory write operation, only in the first non-failable function in the call graph that calls a failable function, i.e. when a function returning <code>void</code> calls a function returning <code>error</code>.

This is to initialize this struct in the stack memory:

</p>

{#code_begin|syntax#}

pub const StackTrace = struct {

index: usize,

instruction_addresses: [N]usize,

};

{#code_end#}

<p>

Here, N is the maximum function call depth as determined by call graph analysis. Recursion is ignored and counts for 2.

</p>

<p>

A pointer to <code>StackTrace</code> is passed as a secret parameter to every function that can return an error, but it's always the first parameter, so it can likely sit in a register and stay there.

</p>

<p>

That's it for the path when no errors occur. It's practically free in terms of performance.

</p>

<p>

When generating the code for a function that returns an error, just before the <code>return</code> statement (only for the <code>return</code> statements that return errors), Zig generates a call to this function:

</p>

{#code_begin|syntax#}

// marked as "no-inline" in LLVM IR

fn __zig_return_error(stack_trace: *StackTrace) void {

stack_trace.instruction_addresses[stack_trace.index] = @returnAddress();

stack_trace.index = (stack_trace.index + 1) % N;

}

{#code_end#}

<p>

The cost is 2 math operations plus some memory reads and writes. The memory accessed is constrained and should remain cached for the duration of the error return bubbling.

</p>

<p>

As for code size cost, 1 function call before a return statement is no big deal. Even so,

I have <a href="https://github.com/ziglang/zig/issues/690">a plan</a> to make the call to

<code>__zig_return_error</code> a tail call, which brings the code size cost down to actually zero. What is a return statement in code without error return tracing can become a jump instruction in code with error return tracing.

</p>

{#header_close#}

{#code_end#}

{#header_close#}

{#header_open|null#}

<p>

Just like {#link|undefined#}, <code>null</code> has its own type, and the only way to use it is to

cast it to a different type:

</p>

{#code_begin|syntax#}

const optional_value: ?i32 = null;

Zig has four build modes:

<li>{#link|ReleaseSmall#}</li>

<pre><code class="shell"> -Drelease-safe=[bool] optimizations on and safety on

-Drelease-fast=[bool] optimizations on and safety off

-Drelease-small=[bool] size optimizations on and safety off</code></pre>

<li>Large binary size</li>

<li>Large binary size</li>

<li>Large binary size</li>

{#header_open|ReleaseSmall#}

<pre><code class="shell">$ zig build-exe example.zig --release-small</code></pre>

<ul>

<li>Medium runtime performance</li>

<li>Safety checks disabled</li>

<li>Slow compilation speed</li>

<li>Small binary size</li>

</ul>

{#header_close#}

{#see_also|Compile Variables|Zig Build System|Undefined Behavior#}

with {#link|setRuntimeSafety#}. The {#link|ReleaseFast#}