Async Functions

    An async function is a function whose execution is split into an initiation, followed by an await completion. Its frame is provided explicitly by the caller, and it can be suspended and resumed any number of times.

    The code following the async callsite runs immediately after the async function first suspends. When the return value of the async function is needed, the calling code can await on the async function frame. This will suspend the calling code until the async function completes, at which point execution resumes just after the await callsite.

    Zig infers that a function is async when it observes that the function contains a suspension point. Async functions can be called the same as normal functions. A function call of an async function is a suspend point.

    At any point, a function may suspend itself. This causes control flow to return to the callsite (in the case of the first suspension), or resumer (in the case of subsequent suspensions).

    suspend_no_resume.zig

    Shell

    1. $ zig test suspend_no_resume.zig
    2. 1/1 test "suspend with no resume"... OK
    3. All 1 tests passed.

    In the same way that each allocation should have a corresponding free, Each suspend should have a corresponding resume. A suspend block allows a function to put a pointer to its own frame somewhere, for example into an event loop, even if that action will perform a resume operation on a different thread. provides access to the async function frame pointer.

    async_suspend_block.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    4. var the_frame: anyframe = undefined;
    5. var result = false;
    7. test "async function suspend with block" {
    8.     _ = async testSuspendBlock();
    9.     try expect(!result);
    10.     resume the_frame;
    11.     try expect(result);
    12. }
    14. fn testSuspendBlock() void {
    15.     suspend {
    16.         comptime try expect(@TypeOf(@frame()) == *@Frame(testSuspendBlock));
    17.         the_frame = @frame();
    18.     }
    19.     result = true;
    20. }

    Shell

    1. $ zig test async_suspend_block.zig
    2. 1/1 test "async function suspend with block"... OK
    3. All 1 tests passed.

    suspend causes a function to be async.

    However, the async function can be directly resumed from the suspend block, in which case it never returns to its resumer and continues executing.

    resume_from_suspend.zig

    Shell

    1. $ zig test resume_from_suspend.zig
    2. 1/1 test "resume from suspend"... OK
    3. All 1 tests passed.

    This is guaranteed to tail call, and therefore will not cause a new stack frame.

    In the same way that every suspend has a matching resume, every async has a matching await in standard code.

    However, it is possible to have an async call without a matching await. Upon completion of the async function, execution would continue at the most recent async callsite or resume callsite, and the return value of the async function would be lost.

    async_await.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    4. test "async and await" {
    5.     // The test block is not async and so cannot have a suspend
    6.     // point in it. By using the nosuspend keyword, we promise that
    7.     // the code in amain will finish executing without suspending
    8.     // back to the test block.
    9.     nosuspend amain();
    10. }
    12. fn amain() void {
    14.     comptime try expect(@TypeOf(frame) == @Frame(func));
    16.     const ptr: anyframe->void = &frame;
    18.     resume any_ptr;
    19.     await ptr;
    20. }
    22. fn func() void {
    23.     suspend {}
    24. }

    Shell

    1. $ zig test async_await.zig
    2. 1/1 test "async and await"... OK
    3. All 1 tests passed.

    The await keyword is used to coordinate with an async function’s return statement.

    await is a suspend point, and takes as an operand anything that coerces to anyframe->T. Calling await on the frame of an async function will cause execution to continue at the await callsite once the target function completes.

    async_await_sequence.zig

    Shell

    1. $ zig test async_await_sequence.zig
    2. 1/1 test "async function await"... OK
    3. All 1 tests passed.

    In general, suspend is lower level than await. Most application code will use only async and await, but event loop implementations will make use of suspend internally.

    Putting all of this together, here is an example of typical async/await usage:

    async.zig

    1. const std = @import("std");
    2. const Allocator = std.mem.Allocator;
    4. pub fn main() void {
    5.     _ = async amainWrap();
    7.     // Typically we would use an event loop to manage resuming async functions,
    8.     // but in this example we hard code what the event loop would do,
    9.     // to make things deterministic.
    10.     resume global_file_frame;
    11.     resume global_download_frame;
    12. }
    14. fn amainWrap() void {
    15.     amain() catch |e| {
    16.         std.debug.print("{}\n", .{e});
    17.         if (@errorReturnTrace()) |trace| {
    18.             std.debug.dumpStackTrace(trace.*);
    19.         }
    20.         std.process.exit(1);
    21.     };
    22. }
    24. fn amain() !void {
    25.     const allocator = std.heap.page_allocator;
    26.     var download_frame = async fetchUrl(allocator, "https://example.com/");
    27.     var awaited_download_frame = false;
    28.     errdefer if (!awaited_download_frame) {
    30.     };
    32.     var file_frame = async readFile(allocator, "something.txt");
    33.     var awaited_file_frame = false;
    34.     errdefer if (!awaited_file_frame) {
    35.         if (await file_frame) |r| allocator.free(r) else |_| {}
    37.     awaited_file_frame = true;
    38.     const file_text = try await file_frame;
    39.     defer allocator.free(file_text);
    41.     awaited_download_frame = true;
    42.     const download_text = try await download_frame;
    43.     defer allocator.free(download_text);
    45.     std.debug.print("download_text: {s}\n", .{download_text});
    46.     std.debug.print("file_text: {s}\n", .{file_text});
    47. }
    49. var global_download_frame: anyframe = undefined;
    50. fn fetchUrl(allocator: Allocator, url: []const u8) ![]u8 {
    51.     _ = url; // this is just an example, we don't actually do it!
    52.     const result = try allocator.dupe(u8, "this is the downloaded url contents");
    53.     errdefer allocator.free(result);
    54.     suspend {
    55.         global_download_frame = @frame();
    56.     }
    57.     std.debug.print("fetchUrl returning\n", .{});
    58.     return result;
    59. }
    61. var global_file_frame: anyframe = undefined;
    62. fn readFile(allocator: Allocator, filename: []const u8) ![]u8 {
    63.     _ = filename; // this is just an example, we don't actually do it!
    64.     const result = try allocator.dupe(u8, "this is the file contents");
    65.     errdefer allocator.free(result);
    66.     suspend {
    67.         global_file_frame = @frame();
    68.     }
    69.     std.debug.print("readFile returning\n", .{});
    70.     return result;
    71. }

    Shell

    1. $ zig build-exe async.zig
    3. $ ./async
    4. readFile returning
    5. fetchUrl returning
    6. download_text: this is the downloaded url contents
    7. file_text: this is the file contents

    Now we remove the suspend and resume code, and observe the same behavior, with one tiny difference:

    blocking.zig

    Shell

    1. $ zig build-exe blocking.zig
    3. $ ./blocking
    4. fetchUrl returning
    5. readFile returning
    6. download_text: this is the downloaded url contents

    Previously, the fetchUrl and readFile functions suspended, and were resumed in an order determined by the function. Now, since there are no suspend points, the order of the printed “… returning” messages is determined by the order of async callsites.