document async frame lifetime

[marler8997]

Today I was made aware by @fengb that the storage for an async frame is on the stack just like a normal function. Once I understood this I was able to understand async alot better. However, neither me nor @fengb were able to see where in the documentation Zig says this is how async works. It was particularly confusing because Zig says that when a normal function is called "a frame is pushed to the stack" and in contrast, "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."

The 2 confusing parts here is that it says normal function frames are pushed to the stack, but doesn't mention this for async functions making it sound like they behave differently. The other part is that it says the frame is provided explicitly by the caller, but "explicitly" to me means it's specified in code, but the caller does not provide a memory pointer to the async call so this doesn't sound correct to me.

I think including something like this would have helped me alot:

When an async function is called, a frame is also pushed to the stack like a normal function. However, this frame differs from a normal function frame in that it must be large enough to accommodate the longest possible call chain. Also note that since the async frame is stored on the stack when it is called, the async frame is no longer valid once the calling function returns. Calling resume on an async frame where the "async" caller as returned is a "use after free" bug, i.e.

var the_frame: anyframe = undefined;
fn foo() void {
    suspend { the_frame = @frame(); }
}
fn callFooAsync() void {
    _ = async foo();
}
pub fn main() void {
    callFooAsync();
    resume the_frame; // use after free, the function that called "_ = async foo();" has returned
}

The corrected version would be:

var the_frame: anyframe = undefined;
fn foo() void {
    suspend { the_frame = @frame(); }
}
pub fn main() void {
    _ = async foo();
    resume the_frame;
}

[rohlem]

I haven't looked at the documentation for this feature since it was introduced, you're probably right that it can be improved.
The explanation provided here doesn't align with how I understand async to work either.
I believe the phrase "a frame is pushed onto the stack" means specifically the allocation, although the process of calling a function also involves saving the current function and setting the stack pointer, only the latter two are equivalent when calling and resuming suspendable (async) functions.
Rather than going into detail on subtle differences (my comments always become walls of texts anyway), I'll try to quickly summarize how I understand the main question of lifetime, and hopefully others can correct me if it turns out I'm also wrong.

EDIT: It got long again.
TL;DR: If you don't use the result of an operator (be it async or +) immediately, you can no longer rely on accessing it. (Note: anyframe is a pointer type, so saving the pointer from @frame() there doesn't help.)
Example code, note that _ = x can be understood as an anonymous block {var result = x;}:

// pointers don't extend lifetime!
var sum_ptr: *u8 = undefined;
var frame_ptr: anyframe = undefined;

// wrong: this saves a pointer, but not the value
{var result = a + b;        sum_ptr = &result;}
{var frame = async foo(); frame_ptr = &frame;} // this happens within foo() in your example

// also wrong: the value is still discarded
_ = blk: {var result = a + b;        sum_ptr = &result; break :blk result;}
_ = blk: {var frame = async foo(); frame_ptr = &frame;  break :blk frame;} // this happens within foo() in your example

// actually correct: saving the values in variables. The variables provide an extended lifetime.
var sum = a + b;
var frame = async foo(); //frames can contain self-referential pointers, so moving them ouf of this scope, f.e. by returning, is not safe in general.

// also correct: manual allocation:
sum_ptr = my_alloc(u8);
defer my_free(u8, sum_ptr); // or wherever, or not, depending on allocation strategy
frame_ptr = my_alloc(@Frame(foo));
defer my_free(@Frame(foo), frame_ptr); // or wherever, or not, depending on allocation strategy
sum_ptr                          .* = a + b;
@ptrCast(*@Frame(foo), frame_ptr).* = async foo(); //at least I think this should work; @asyncCall is used for this more often

---

long version:

The async operator creates a temporary value, just like arithmetic operators.

• a + b creates a resulting value, and uses the stack (note: + CPU registers etc.) to allocate required space.
• (It might also reuse the space of a, b, or other variables if they are no longer needed.)
• (Note: even more space may be required to compute a + b than to store the result alone).
• The "lifetime" of a + b ends at its immediate point of use. If you had a way to access its address, then in {_ = a + b; foo()}, foo() cannot rely on the fact that the result of a + b is still stored there.

async behaves completely analogously:

• async foo() creates the resumable stack frame (of the maximum required size) for resuming the rest of that function, and uses the stack to allocate required space.
• (It might also reuse the space of other variables if they are no longer needed.)
• (Note: even more space may be required to call the function initially than to store the part of the frame that is required for resuming/awaiting it.)
• The "lifetime" of async foo() also ends at its immediate point of use. Here you found a way to access its address during execution, but that doesn't mean that the embedding function "reserves" this space by itself.

So, how do we extend the "lifetime" of these expressions? By assigning them to variables (*):

• var sum = a + b;
• var the_frame = async foo()

In particular, the variable represents the memory reservation and has to stay alive, therefore discarding the result is not sufficient:

• _ = async foo();
• {var frame = async foo(); global_ptr = &frame;} //equivalent - frame "dies" at the end of the block
• {var sum = a + b; global_ptr = ∑ } //equivalent - sum "dies" at the end of the block
• Side note (which is noted in the documentation): anyframe is a pointer type, NOT the type of an actual frame (which would be @Frame(foo)).

To extend the lifetimes even beyond that, we need to use memory that is explicitly allocated. This requires explicit types, so f.e. u32 and @Frame(foo) (or at least their sizes, see @frameSize).
For using an explicit allocation strategy there is the builtin @asyncCall, which takes an aligned []u8 as untyped memory to use.
(I believe that assigning std.mem.bytesAsSlice(frame_buffer, @Frame(foo))[0] = async foo() should do the same as @asyncCall(frame_buffer, null, &foo, .{}). (*))

(Manual allocation patterns, on the heap or elsewhere, are of course also available -- they don't care about / have their own, manual concept of "lifetime".)

(*) This makes use of Zig's result location semantics, which guarantee that the location is already allocated and used when foo begins executing, so @frame() returns the address of the variable that the async expression is assigned to.

[marler8997]

@rohlem thanks for taking the time to write that up. My write up has some inaccuracies because when I wrote it I didn't realize it was the "return value" that housed the storage for the frame. I thought the frame was just pushed onto the stack and the async call returned a pointer to it.

[win-t]

also, I think it should be documented that dropping the frame will also discard the deferred statement

const expect = @import("std").testing.expect;

var a: usize = 0;

fn asdf() void {
    a += 1 ;
    defer a += 1;
    suspend {}
}

fn lala() void {
    var frame = async asdf();
    _ = frame;
}

test "droping the frame" {
    nosuspend lala();
    try expect(a == 1);
}

It is not so obvious, someone who codes an event loop will think it is okay to drop the frame if the task is not needed anymore

I've read somewhere before, this is the reason why golang doesn't have API to kill goroutine (remove the task from the event loop queue)