Async Method

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

public async Task<int> ProcessDataAsync(int input)
{
    // Synchronous execution up to the first incomplete await
    int intermediateResult = await CalculateAsync(input);
    
    // Continuation executes after CalculateAsync completes
    return intermediateResult * 2;
}

​

Compiler Mechanics: The State Machine

• State Tracking: The struct contains an integer state field that tracks the execution progress, allowing the method to pause and resume at specific await boundaries.
• Variable Hoisting: Local variables declared within the method are hoisted into fields of the state machine struct. This ensures their values persist across asynchronous suspensions.
• Awaiter Pattern: When the compiler encounters await, it calls GetAwaiter() on the awaitable object. If awaiter.IsCompleted is false, the state machine registers its own MoveNext method as a continuation via awaiter.OnCompleted(), and the method returns an uncompleted Task to the caller.

​

Valid Return Types

• Task: Represents an asynchronous operation that does not return a value.
• Task<TResult>: Represents an asynchronous operation that returns a value of type TResult.
• ValueTask / ValueTask<TResult>: A value-type (struct) alternative to Task. It is used to eliminate heap allocations when the asynchronous operation frequently completes synchronously.
• IAsyncEnumerable<T>: Used for asynchronous streams. The method uses yield return to produce multiple values asynchronously, which the caller can then consume using await foreach.
• void: Should be strictly reserved for event handlers. While the compiler allows any method to be marked async void, it operates in a “fire-and-forget” manner. It does not return a Task, meaning the caller cannot await it, and unhandled exceptions will crash the process rather than being captured in a Task.
• Custom Task-like Types: Any user-defined type decorated with [AsyncMethodBuilder].

​

Execution Flow and Context

1. Synchronous Start: Execution begins synchronously on the caller’s thread. It proceeds line-by-line until it hits the first await expression.
2. Suspension: If the awaited operation is not already complete, the method suspends. Control is yielded to the caller, and a Task (or task-like type) representing the ongoing operation is returned.
3. Continuation: Once the awaited operation completes, the remainder of the method executes.
4. Context Capture: By default, the await operator captures the current SynchronizationContext or TaskScheduler. When the continuation runs, it attempts to marshal execution back to this captured context. If no context is present, the continuation executes on an available ThreadPool thread.

​

Exception Handling Mechanics

public async Task FaultingOperationAsync()
{
    // Await an operation to prevent the CS1998 compiler warning
    await Task.Yield();

    // This exception is unhandled within this method.
    // The state machine catches it and transitions the returned Task to Faulted.
    throw new InvalidOperationException("Operation failed.");
}

public async Task ExecuteAsync()
{
    // The method executes up to the first suspension point.
    // The returned Task eventually transitions to a Faulted state.
    Task faultedTask = FaultingOperationAsync(); 
    
    try
    {
        // Awaiting the faulted task unwraps and re-throws the captured exception.
        await faultedTask; 
    }
    catch (InvalidOperationException ex)
    {
        // The exception is successfully handled by the caller.
        Console.WriteLine(ex.Message);
    }
}