Async Functions

When a function is called, a frame is pushed to the stack, the function runs until it reaches a return statement, and then the frame is popped from the stack. At the callsite, the following code does not run until the function returns.

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

Suspend and Resume

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. const std = @import("std");
  2. const assert = std.debug.assert;
  4. var x: i32 = 1;
  6. test "suspend with no resume" {
  7.     var frame = async func();
  8.     assert(x == 2);
  9. }
  11. fn func() void {
  12.     x += 1;
  13.     suspend;
  14.     // This line is never reached because the suspend has no matching resume.
  15.     x += 1;
  16. }
  1. $ zig test test.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. @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 1 tests passed.

suspend causes a function to be async.

Resuming from Suspend Blocks

Upon entering a suspend block, the async function is already considered suspended, and can be resumed. For example, if you started another kernel thread, and had that thread call resume on the frame pointer provided by the @frame, the new thread would begin executing after the suspend block, while the old thread continued executing the suspend block.

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. const std = @import("std");
  2. const assert = std.debug.assert;
  4. test "resume from suspend" {
  5.     var my_result: i32 = 1;
  6.     _ = async testResumeFromSuspend(&my_result);
  7.     std.debug.assert(my_result == 2);
  8. }
  9. fn testResumeFromSuspend(my_result: *i32) void {
  10.     suspend {
  11.         resume @frame();
  12.     }
  13.     my_result.* += 1;
  14.     suspend;
  15.     my_result.* += 1;
  16. }
  1. $ zig test test.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.

Async and Await

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();
  16.     comptime assert(@TypeOf(frame) == @Frame(func));
  18.     const ptr: anyframe->void = &frame;
  19.     const any_ptr: anyframe = ptr;
  21.     resume any_ptr;
  22.     await ptr;
  23. }
  25. fn func() void {
  26.     suspend;
  27. }
  1. $ zig test test.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.

There is a common misconception that await resumes the target function. It is the other way around: it suspends until the target function completes. In the event that the target function has already completed, await does not suspend; instead it copies the return value directly from the target function's frame.

test.zig

  1. const std = @import("std");
  2. const assert = std.debug.assert;
  4. var the_frame: anyframe = undefined;
  5. var final_result: i32 = 0;
  7. test "async function await" {
  8.     seq('a');
  9.     _ = async amain();
  10.     seq('f');
  11.     resume the_frame;
  12.     seq('i');
  13.     assert(final_result == 1234);
  14.     assert(std.mem.eql(u8, &seq_points, "abcdefghi"));
  15. }
  16. fn amain() void {
  17.     seq('b');
  18.     var f = async another();
  19.     seq('e');
  20.     final_result = await f;
  21.     seq('h');
  22. }
  23. fn another() i32 {
  24.     seq('c');
  25.     suspend {
  26.         seq('d');
  27.         the_frame = @frame();
  28.     }
  29.     seq('g');
  30.     return 1234;
  31. }
  33. var seq_points = [_]u8{0} ** "abcdefghi".len;
  34. var seq_index: usize = 0;
  36. fn seq(c: u8) void {
  37.     seq_points[seq_index] = c;
  38.     seq_index += 1;
  39. }
  1. $ zig test test.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.

Async Function Example

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.page_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 |_| {}
  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 |_| {}
  36.     };
  38.     awaited_file_frame = true;
  39.     const file_text = try await file_frame;
  40.     defer allocator.free(file_text);
  42.     awaited_download_frame = true;
  43.     const download_text = try await download_frame;
  44.     defer allocator.free(download_text);
  46.     std.debug.warn("download_text: {}\n", .{download_text});
  47.     std.debug.warn("file_text: {}\n", .{file_text});
  48. }
  50. var global_download_frame: anyframe = undefined;
  51. fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
  52.     const result = try std.mem.dupe(allocator, u8, "this is the downloaded url contents");
  53.     errdefer allocator.free(result);
  54.     suspend {
  55.         global_download_frame = @frame();
  56.     }
  57.     std.debug.warn("fetchUrl returning\n", .{});
  58.     return result;
  59. }
  61. var global_file_frame: anyframe = undefined;
  62. fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
  63.     const result = try std.mem.dupe(allocator, u8, "this is the file contents");
  64.     errdefer allocator.free(result);
  65.     suspend {
  66.         global_file_frame = @frame();
  67.     }
  68.     std.debug.warn("readFile returning\n", .{});
  69.     return result;
  70. }
  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. const std = @import("std");
  2. const Allocator = std.mem.Allocator;
  4. pub fn main() void {
  5.     _ = async amainWrap();
  6. }
  8. fn amainWrap() void {
  9.     amain() catch |e| {
  10.         std.debug.warn("{}\n", .{e});
  11.         if (@errorReturnTrace()) |trace| {
  12.             std.debug.dumpStackTrace(trace.*);
  13.         }
  14.         std.process.exit(1);
  15.     };
  16. }
  18. fn amain() !void {
  19.     const allocator = std.heap.page_allocator;
  20.     var download_frame = async fetchUrl(allocator, "https://example.com/");
  21.     var awaited_download_frame = false;
  22.     errdefer if (!awaited_download_frame) {
  23.         if (await download_frame) |r| allocator.free(r) else |_| {}
  24.     };
  26.     var file_frame = async readFile(allocator, "something.txt");
  27.     var awaited_file_frame = false;
  28.     errdefer if (!awaited_file_frame) {
  29.         if (await file_frame) |r| allocator.free(r) else |_| {}
  30.     };
  32.     awaited_file_frame = true;
  33.     const file_text = try await file_frame;
  34.     defer allocator.free(file_text);
  36.     awaited_download_frame = true;
  37.     const download_text = try await download_frame;
  38.     defer allocator.free(download_text);
  40.     std.debug.warn("download_text: {}\n", .{download_text});
  41.     std.debug.warn("file_text: {}\n", .{file_text});
  42. }
  44. fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
  45.     const result = try std.mem.dupe(allocator, u8, "this is the downloaded url contents");
  46.     errdefer allocator.free(result);
  47.     std.debug.warn("fetchUrl returning\n", .{});
  48.     return result;
  49. }
  51. fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
  52.     const result = try std.mem.dupe(allocator, u8, "this is the file contents");
  53.     errdefer allocator.free(result);
  54.     std.debug.warn("readFile returning\n", .{});
  55.     return result;
  56. }
  1. $ zig build-exe blocking.zig
  2. $ ./blocking
  3. fetchUrl returning
  4. readFile returning
  5. download_text: this is the downloaded url contents
  6. 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.