Async Functions

    An async function is a function whose callsite 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.

    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).

    test.zig

    1. $ zig test test.zig
    2. 1/1 test "suspend with no resume"...OK
    3. All 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. @frame provides access to the async function frame pointer.

    test.zig

    1. const std = @import("std");
    2. const assert = std.debug.assert;
    4. var the_frame: anyframe = undefined;
    5. var result = false;
    7. test "async function suspend with block" {
    8.     _ = async testSuspendBlock();
    9.     assert(!result);
    10.     resume the_frame;
    11.     assert(result);
    12. }
    14. fn testSuspendBlock() void {
    15.     suspend {
    16.         comptime assert(@typeOf(@frame()) == *@Frame(testSuspendBlock));
    17.         the_frame = @frame();
    18.     }
    19.     result = true;
    20. }
    1. $ zig test test.zig
    2. 1/1 test "async function suspend with block"...OK
    3. All 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.

    test.zig

    1. $ zig test test.zig
    2. 1/1 test "resume from suspend"...OK
    3. All 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.

    test.zig

    1. const std = @import("std");
    2. const assert = std.debug.assert;
    4. test "async and await" {
    5.     // Here we have an exception where we do not match an async
    6.     // with an await. The test block is not async and so cannot
    7.     // have a suspend point in it.
    8.     // This is well-defined behavior, and everything is OK here.
    9.     // Note however that there would be no way to collect the
    10.     // return value of amain, if it were something other than void.
    11.     _ = async amain();
    12. }
    14. fn amain() void {
    15.     var frame = async func();
    17.     const ptr: anyframe->void = &frame;
    18.     const any_ptr: anyframe = ptr;
    20.     resume any_ptr;
    21.     await ptr;
    22. }
    24. fn func() void {
    25.     suspend;
    26. }
    1. $ zig test test.zig
    2. 1/1 test "async and await"...OK
    3. All 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 implicitly casts to anyframe->T.

    test.zig

    1. $ zig test test.zig
    2. 1/1 test "async function await"...OK
    3. All 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.warn("{}\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.direct_allocator;
    26.     var download_frame = async fetchUrl(allocator, "https://example.com/");
    27.     var awaited_download_frame = false;
    28.     errdefer if (!awaited_download_frame) {
    29.         if (await download_frame) |r| allocator.free(r) else |_| {}
    32.     var awaited_file_frame = false;
    33.     errdefer if (!awaited_file_frame) {
    34.         if (await file_frame) |r| allocator.free(r) else |_| {}
    35.     };
    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.warn("download_text: {}\n", download_text);
    46.     std.debug.warn("file_text: {}\n", file_text);
    47. }
    49. var global_download_frame: anyframe = undefined;
    50. fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
    51.     const result = try std.mem.dupe(allocator, u8, "this is the downloaded url contents");
    52.     errdefer allocator.free(result);
    53.     suspend {
    54.         global_download_frame = @frame();
    55.     }
    56.     std.debug.warn("fetchUrl returning\n");
    57.     return result;
    58. }
    60. var global_file_frame: anyframe = undefined;
    61. fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
    62.     const result = try std.mem.dupe(allocator, u8, "this is the file contents");
    63.     errdefer allocator.free(result);
    64.     suspend {
    65.         global_file_frame = @frame();
    66.     }
    67.     std.debug.warn("readFile returning\n");
    68.     return result;
    69. }
    1. $ zig build-exe async.zig
    2. $ ./async
    3. readFile returning
    4. fetchUrl returning
    5. download_text: this is the downloaded url contents
    6. 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

    1. $ zig build-exe blocking.zig
    2. $ ./blocking
    3. fetchUrl returning
    4. readFile returning
    5. file_text: this is the file contents

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