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. The code following the callsite does not run until the function returns.

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

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.

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

suspend_no_resume.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. var x: i32 = 1;
  6. test "suspend with no resume" {
  7.     var frame = async func();
  8.     try expect(x == 2);
  9.     _ = frame;
  10. }
  12. fn func() void {
  13.     x += 1;
  14.     suspend {}
  15.     // This line is never reached because the suspend has no matching resume.
  16.     x += 1;
  17. }

Shell

  1. $ zig test suspend_no_resume.zig -fstage1
  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.

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

resume_from_suspend.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  4. test "resume from suspend" {
  5.     var my_result: i32 = 1;
  6.     _ = async testResumeFromSuspend(&my_result);
  7.     try std.testing.expect(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. }

Shell

  1. $ zig test resume_from_suspend.zig -fstage1
  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 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 {
  13.     var frame = async func();
  14.     comptime try expect(@TypeOf(frame) == @Frame(func));
  16.     const ptr: anyframe->void = &frame;
  17.     const any_ptr: anyframe = ptr;
  19.     resume any_ptr;
  20.     await ptr;
  21. }
  23. fn func() void {
  24.     suspend {}
  25. }

Shell

  1. $ zig test async_await.zig -fstage1
  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.

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.

async_await_sequence.zig

  1. const std = @import("std");
  2. const expect = std.testing.expect;
  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.     try expect(final_result == 1234);
  14.     try expect(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. }

Shell

  1. $ zig test async_await_sequence.zig -fstage1
  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.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) {
  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.print("download_text: {s}\n", .{download_text});
  47.     std.debug.print("file_text: {s}\n", .{file_text});
  48. }
  50. var global_download_frame: anyframe = undefined;
  51. fn fetchUrl(allocator: Allocator, url: []const u8) ![]u8 {
  52.     _ = url; // this is just an example, we don't actually do it!
  53.     const result = try allocator.dupe(u8, "this is the downloaded url contents");
  54.     errdefer allocator.free(result);
  55.     suspend {
  56.         global_download_frame = @frame();
  57.     }
  58.     std.debug.print("fetchUrl returning\n", .{});
  59.     return result;
  60. }
  62. var global_file_frame: anyframe = undefined;
  63. fn readFile(allocator: Allocator, filename: []const u8) ![]u8 {
  64.     _ = filename; // this is just an example, we don't actually do it!
  65.     const result = try allocator.dupe(u8, "this is the file contents");
  66.     errdefer allocator.free(result);
  67.     suspend {
  68.         global_file_frame = @frame();
  69.     }
  70.     std.debug.print("readFile returning\n", .{});
  71.     return result;
  72. }

Shell

  1. $ zig build-exe async.zig -fstage1
  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

  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.print("{}\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.print("download_text: {s}\n", .{download_text});
  41.     std.debug.print("file_text: {s}\n", .{file_text});
  42. }
  44. fn fetchUrl(allocator: Allocator, url: []const u8) ![]u8 {
  45.     _ = url; // this is just an example, we don't actually do it!
  46.     const result = try allocator.dupe(u8, "this is the downloaded url contents");
  47.     errdefer allocator.free(result);
  48.     std.debug.print("fetchUrl returning\n", .{});
  49.     return result;
  50. }
  52. fn readFile(allocator: Allocator, filename: []const u8) ![]u8 {
  53.     _ = filename; // this is just an example, we don't actually do it!
  54.     const result = try allocator.dupe(u8, "this is the file contents");
  55.     errdefer allocator.free(result);
  56.     std.debug.print("readFile returning\n", .{});
  57.     return result;
  58. }

Shell

  1. $ zig build-exe blocking.zig -fstage1
  3. $ ./blocking
  4. fetchUrl returning
  5. readFile returning
  6. download_text: this is the downloaded url contents
  7. 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.