Async/Await in C#: A Deep Dive

How Async/Await Works: The Compiler-Generated State Machine#

When Roslyn compiles an async method, it turns the body into a state machine type that implements IAsyncStateMachine, and it replaces the original method with a small stub. Consider this method:

public async Task<int> GetOrderCountAsync(HttpClient http, CancellationToken ct)
{
    string json = await http.GetStringAsync("/api/orders/count", ct);
    return int.Parse(json);
}

The generated code is roughly equivalent to the following simplified sketch:

public Task<int> GetOrderCountAsync(HttpClient http, CancellationToken ct)
{
    var sm = new GetOrderCountStateMachine
    {
        Builder = AsyncTaskMethodBuilder<int>.Create(),
        Http = http,
        Ct = ct,
        State = -1,
    };
    sm.Builder.Start(ref sm);   // runs MoveNext synchronously until the first real suspension
    return sm.Builder.Task;
}

struct GetOrderCountStateMachine : IAsyncStateMachine
{
    public int State;
    public AsyncTaskMethodBuilder<int> Builder;
    public HttpClient Http;
    public CancellationToken Ct;
    private TaskAwaiter<string> _awaiter;

    public void MoveNext()
    {
        try
        {
            if (State != 0)
            {
                _awaiter = Http.GetStringAsync("/api/orders/count", Ct).GetAwaiter();
                if (!_awaiter.IsCompleted)
                {
                    State = 0;
                    Builder.AwaitUnsafeOnCompleted(ref _awaiter, ref this);   // suspend
                    return;
                }
            }

            State = -1;
            string json = _awaiter.GetResult();   // returns the value or rethrows
            Builder.SetResult(int.Parse(json));
        }
        catch (Exception ex)
        {
            State = -2;
            Builder.SetException(ex);
        }
    }

    public void SetStateMachine(IAsyncStateMachine stateMachine) =>
        Builder.SetStateMachine(stateMachine);
}

Three pieces cooperate. The state machine holds locals and parameters as fields plus an integer state that records which await to resume after. The builder (AsyncTaskMethodBuilder<T>, or AsyncValueTaskMethodBuilder<T> for ValueTask) creates the returned task and completes it with SetResult or SetException. The awaiter comes from the awaitable's GetAwaiter() method and exposes IsCompleted, OnCompleted or UnsafeOnCompleted, and GetResult. Any type with that shape can be awaited, which is why await works on Task, ValueTask, Task.Yield() and custom awaitables.

The IsCompleted check is the synchronous fast path: if the awaited operation already finished, the method continues immediately without scheduling anything. In Release builds the state machine is a struct, so a method that never suspends allocates nothing beyond its result task. Even that allocation can disappear, because a method that completes synchronously gets a cached task for common results, such as a completed Task, true, false, or Task<int> values from -1 to 8. On the first real suspension, the runtime copies the struct into a heap box that is itself the returned Task<T>, so the task and the state machine share one allocation.

.NET 11 adds a second implementation called runtime async, in which the runtime rather than compiler-generated state machines manages suspension and resumption. The goals are lower overhead and cleaner stack traces. In the .NET 11 previews the runtime libraries themselves were rebuilt with it, while your own code opts in through the runtime-async=on compiler feature switch. The semantics described in this guide do not change; only the machinery underneath does.