What does the compiler generate for an async method? Explain the async state machine.

1. A simplified state machine

// async Task<int> GetAsync() { int a = await A(); int b = await B(a); return a + b; }
[CompilerGenerated]
private struct GetAsyncSM : IAsyncStateMachine
{
    public int state;
    public AsyncTaskMethodBuilder<int> builder;
    private int a;                    // hoisted: used after the second await
    private TaskAwaiter<int> awaiter; // reused for both awaits (same awaiter type)

    public void MoveNext()
    {
        int result;
        try
        {
            TaskAwaiter<int> aw;
            switch (state)
            {
                case 0: aw = awaiter; awaiter = default; state = -1; goto ResumeA;
                case 1: aw = awaiter; awaiter = default; state = -1; goto ResumeB;
            }
            aw = A().GetAwaiter();
            if (!aw.IsCompleted) { state = 0; awaiter = aw; builder.AwaitUnsafeOnCompleted(ref aw, ref this); return; }
        ResumeA:
            a = aw.GetResult();
            aw = B(a).GetAwaiter();
            if (!aw.IsCompleted) { state = 1; awaiter = aw; builder.AwaitUnsafeOnCompleted(ref aw, ref this); return; }
        ResumeB:
            result = a + aw.GetResult();
        }
        catch (Exception ex) { state = -2; builder.SetException(ex); return; }
        state = -2;
        builder.SetResult(result);
    }

    void IAsyncStateMachine.SetStateMachine(IAsyncStateMachine sm) => builder.SetStateMachine(sm);
}

// Stub
public static Task<int> GetAsync()
{
    var sm = new GetAsyncSM { builder = AsyncTaskMethodBuilder<int>.Create(), state = -1 };
    sm.builder.Start(ref sm);
    return sm.builder.Task;
}

2. Boxing on first suspension

Call 1 (completes synchronously):  struct on the stack -> no heap box
Call 2 (suspends):                 struct copied into AsyncStateMachineBox<GetAsyncSM> on the heap
                                   box : Task<int>   <- returned to the caller
                                   box.StateMachine  <- the struct, now on the heap
                                   box.Context       <- captured ExecutionContext
                                   later awaits in the same call reuse this box

Because the box is the task, an async method that suspends allocates one object for both the task and the state machine.

3. What AwaitUnsafeOnCompleted does

• Ensures the box exists (first time).
• Captures ExecutionContext into the box (once).
• For TaskAwaiter, registers the box directly as a continuation on the awaited task (no extra delegate allocation in the common case).
• Respects SynchronizationContext / TaskScheduler capture (or not, with ConfigureAwait(false)).

OnCompleted (non-"unsafe") would flow ExecutionContext itself; the builder uses the unsafe version because it already manages context flow.

4. Hoisting rules

5. Reading async in dumps and traces

• Because suspended methods aren't on any thread's stack, a normal stack dump shows almost nothing.
• dotnet-dump analyze → dumpasync walks AsyncStateMachineBox objects and their continuations to reconstruct logical async call chains, including state values.
• Visual Studio's Parallel Stacks → Tasks view does the same in a debugger.
• Since .NET Core 2.1, exception stack traces are cleaned up to hide MoveNext noise.

6. Async iterators

async IAsyncEnumerable<T> methods generate a class that implements IAsyncEnumerable<T>, IAsyncEnumerator<T>, IAsyncDisposable and IValueTaskSource<bool>, using ManualResetValueTaskSourceCore<bool> so MoveNextAsync can return a reusable ValueTask<bool> without allocating per item.

7. Version notes

8. Try it yourself

1. Run the code example in Debug and Release and compare IsValueType for the state machine type.
2. Paste the method into SharpLab (C# view, Release) and find <>1__state, the builder and MoveNext.
3. Add a large struct local used after the second await, check SharpLab for the new field, and benchmark allocated bytes.
4. Benchmark an async method that always completes synchronously vs one that awaits Task.Yield() with [MemoryDiagnoser].
5. Take a dump of an app with many pending async calls and run dumpasync.
6. Decompile an async IAsyncEnumerable<int> method and find the IValueTaskSource<bool> implementation.

using System.Runtime.CompilerServices;

// Observe the state machine type at run time.
Task<int> t = Sample.GetAsync();
Console.WriteLine(await t);

// The attribute the compiler adds to the stub points at the generated type.
var attr = typeof(Sample).GetMethod(nameof(Sample.GetAsync))!
    .GetCustomAttributes(typeof(AsyncStateMachineAttribute), false)
    .Cast<AsyncStateMachineAttribute>()
    .Single();
Console.WriteLine($"State machine type: {attr.StateMachineType.Name}, struct: {attr.StateMachineType.IsValueType}");
// Release build: struct = True. Debug build: struct = False (class, for debugging).

static class Sample
{
    public static async Task<int> GetAsync()
    {
        int a = await StepAsync(1); // suspension point 0
        int b = await StepAsync(a); // suspension point 1
        return a + b;
    }

    private static async Task<int> StepAsync(int x)
    {
        await Task.Delay(10);
        return x + 1;
    }
}