async and await from first principles

A price check asks three vendors for a quote, and their answers take 300, 200 and 250 ms to arrive. Awaited one after another, the three take 750 ms; started together, about 300 ms. Either way the waiting needs no thread: await lets the method step aside while the answer travels, so a server keeps its threads for other requests.

You will see what await does to a method and to the thread that runs it, write async methods that return Task and Task<T>, start waits so that they overlap, give CPU-bound work a thread of its own, and catch the exceptions that awaited tasks carry.

await hands control back to the caller and resumes the method later

order.cs calls an async method that waits 500 ms for a quote, standing in for a network call, and prints where each part of the run happens:

// What await does to a method. The part before the first await runs at once, on the caller's thread; the caller
// gets an unfinished task back; the rest of the method runs later, when the awaited task completes.
Console.WriteLine($"Main calls LoadQuoteAsync (thread-pool thread: {OnPool()})");

Task<int> loading = LoadQuoteAsync();
Console.WriteLine($"Main has a task back: completed {loading.IsCompleted}, status {loading.Status}");

int quote = await loading;
Console.WriteLine($"Main resumes with {quote} (thread-pool thread: {OnPool()})");

static async Task<int> LoadQuoteAsync()
{
    Console.WriteLine($"  LoadQuoteAsync runs up to its await (thread-pool thread: {OnPool()})");

    // Task.Delay stands in for a network call that answers after 500 ms.
    await Task.Delay(500);

    Console.WriteLine($"  LoadQuoteAsync resumes after the wait (thread-pool thread: {OnPool()})");
    return 412;
}

static bool OnPool() => Thread.CurrentThread.IsThreadPoolThread;

Main calls LoadQuoteAsync (thread-pool thread: False)
  LoadQuoteAsync runs up to its await (thread-pool thread: False)
Main has a task back: completed False, status WaitingForActivation
  LoadQuoteAsync resumes after the wait (thread-pool thread: True)
Main resumes with 412 (thread-pool thread: True)

Read the five lines in order. LoadQuoteAsync ran on the caller’s thread up to its await, as an ordinary method would. At the await the delay was not finished, so the method stopped there and gave its caller a tasktask: An object that stands for work in progress, such as a Task or a Task<T>. It ends once, with a result, an exception or a cancel; code awaits it to get the outcome, or reads its Status. that was not complete yet. WaitingForActivation is the status .NET gives an async method’s task while the method is still in progress. Main went on to its own await, and the program waited. When the delay ended, the rest of LoadQuoteAsync ran, its continuationcontinuation: The code that runs when an awaited task completes: the rest of an async method after the await. Without a synchronization context, as in a console app, it runs on a thread-pool thread., then the rest of Main, both on a thread-poolthread pool: The set of worker threads that .NET keeps and reuses for short pieces of work: the work given to Task.Run, timer callbacks and the continuations of awaited tasks. thread. Step through the same run:

For those 500 ms no thread was inside LoadQuoteAsync. The compiler turns every async method into a state machineThe object the compiler writes for an async method. It keeps the method's local variables and the place where it stopped, so the method can go on from that await when the awaited task completes. that remembers its local variables and where it stopped, and the timer, not a waiting thread, resumed it. In a console app the main thread does wait at the end, because the runtime waits for Main’s task before the process exits; in a web server the thread goes back to serve another request.

An async method returns a task that promises its result

An async method declares what its task will carry: Task<int> for a method that ends with return 412;, and a plain Task for one that returns nothing. The return statement gives the value, the compiler stores it in the task, and await takes it out again. tasks.cs shows both kinds, and what happens to a call that nobody awaits:

// Task<int> promises an int, Task promises only that the work ends. await unwraps the int, and waits for the Task.
Task<int> pending = QuoteAsync("north");
Console.WriteLine($"QuoteAsync gave back a task with status {pending.Status}");

int price = await pending;
Console.WriteLine($"await gave the int inside it: {price}; status now {pending.Status}");

await SaveReceiptAsync("order 7");
Console.WriteLine("order 7: Main went on after the receipt was saved");

// The mistake: the call is not awaited (warning CS4014), so Main goes on at once and the program ends
// before the receipt is saved. Nothing reports it.
SaveReceiptAsync("order 8");
Console.WriteLine("order 8: Main went on without waiting, and the program ends here");

static async Task<int> QuoteAsync(string vendor)
{
    await Task.Delay(200);
    return vendor == "north" ? 412 : 398;
}

static async Task SaveReceiptAsync(string order)
{
    await Task.Delay(1000);
    Console.WriteLine($"  receipt saved for {order}");
}

QuoteAsync gave back a task with status WaitingForActivation
await gave the int inside it: 412; status now RanToCompletion
  receipt saved for order 7
order 7: Main went on after the receipt was saved
order 8: Main went on without waiting, and the program ends here

await pending gave the int 412 and left the task RanToCompletion. SaveReceiptAsync returns a plain Task: awaiting it gives no value, but Main waited until the receipt for order 7 was saved before it printed its next line. The call for order 8 was not awaited, so Main went straight on, the program ended, and that receipt was never saved. Nothing reported it at run time. The compiler does warn about the call:

SaveReceiptAsync("order 8");
Console.WriteLine($"Main went on; the receipt has {await CountLinesAsync("total 412\npaid")} lines");

static async Task SaveReceiptAsync(string order)
{
    await Task.Delay(1000);
    Console.WriteLine($"receipt saved for {order}");
}

static async Task<int> CountLinesAsync(string text) => text.Split('\n').Length;

from session import run

# warnings/Program.cs makes the two mistakes of this lesson: a call whose task is not awaited, and an async method
# with no await in it. Both compile; this SDK warns about the first one only.
run("""
cd warnings
dotnet build -v q
""")

$ cd warnings
$ dotnet build -v q
warnings/Program.cs(1,1): warning CS4014: Because this call is not awaited, execution of the current method continues before the call is completed. Consider applying the 'await' operator to the result of the call. [warnings/App.csproj]

Build succeeded.

warnings/Program.cs(1,1): warning CS4014: Because this call is not awaited, execution of the current method continues before the call is completed. Consider applying the 'await' operator to the result of the call. [warnings/App.csproj]
    1 Warning(s)
    0 Error(s)

Time Elapsed …

CS4014 marks the call whose task nobody awaits. The second mistake in the file, CountLinesAsync, an async method with no await in it, compiled without a word from this SDK, though Microsoft’s list of compiler messages still describes a warning, CS1998, for it; the section after next shows what such a method does. The return types an async method can have:

By convention the name ends in Async. Main may be async Task Main() since C# 7.1, and top-level statements may use await directly, as every example here does.

Waits overlap when you start them before you await them

waits.cs asks three vendors for a quote, with waits of 300, 200 and 250 ms. First it awaits each call before it makes the next; then it starts all three calls and awaits them after:

using System.Diagnostics;

// Three price quotes, each a wait of a few hundred milliseconds (Task.Delay stands in for the network).
// First each call is awaited before the next one starts; then all three start first and are awaited after.
var watch = Stopwatch.StartNew();
int north = await QuoteAsync("north", 300);
int south = await QuoteAsync("south", 200);
int east = await QuoteAsync("east", 250);
Console.WriteLine($"awaited one by one: cheapest {Math.Min(north, Math.Min(south, east))}, about {Rounded(watch)} ms");

watch.Restart();
Task<int> northTask = QuoteAsync("north", 300);
Task<int> southTask = QuoteAsync("south", 200);
Task<int> eastTask = QuoteAsync("east", 250);
int cheapest = Math.Min(await northTask, Math.Min(await southTask, await eastTask));
Console.WriteLine($"started together:   cheapest {cheapest}, about {Rounded(watch)} ms");

static async Task<int> QuoteAsync(string vendor, int milliseconds)
{
    await Task.Delay(milliseconds);
    return vendor switch
    {
        "north" => 412,
        "south" => 398,
        _ => 405,
    };
}

// The elapsed time, to the nearest 50 ms: the exact figure changes a little from run to run.
static long Rounded(Stopwatch watch) => (long)Math.Round(watch.Elapsed.TotalMilliseconds / 50) * 50;

awaited one by one: cheapest 398, about 750 ms
started together:   cheapest 398, about 300 ms

Awaited one by one, the waits added up: 300 + 200 + 250 = 750 ms. Started together, they overlapped, and the whole check took as long as the slowest vendor, about 300 ms. The second version calls QuoteAsync three times before its first await. Each call runs up to its own await, starts its delay and returns a task at once, so all three delays are running before Main waits for any of them:

None of the three waits used a thread. A delay is a timer, and a network reply is a notice from the operating system, so I/O-boundI/O-bound: Work that spends its time waiting for something outside the processor, such as a disk, a database or a network reply. While it waits, it needs no thread. work needs a thread only for the moments its own code runs. That is why async code helps most with I/O: a thread that would sit blocked for 300 ms can serve other work instead.

CPU-bound work needs a thread, so it goes to Task.Run

A wait needs no thread, but a computation does. Counting the primes below 10 million keeps a processor busy for the whole count, so it is CPU-boundCPU-bound: Work that keeps a processor busy computing, such as hashing a file or resizing images. It needs a thread for its whole run, which Task.Run can take from the thread pool., and marking the method async changes nothing about where it runs. cpu.cs counts twice: once in an async method with no await, once through Task.Run:

// CPU-bound work. An async method with no await in it runs to its end before it returns, so the caller waits for
// the whole count. Task.Run puts the count on a thread-pool thread and returns an unfinished task at once.
Task<(int Count, bool OnPool)> direct = CountPrimesAsync(10_000_000);
Console.WriteLine($"async method without await: task completed on return: {direct.IsCompleted}");

Task<(int Count, bool OnPool)> offloaded = Task.Run(() => CountPrimes(10_000_000));
Console.WriteLine($"Task.Run: task completed on return: {offloaded.IsCompleted}");

var (count, onPool) = await direct;
Console.WriteLine($"without await: {count} primes, counted on a thread-pool thread: {onPool}");
(count, onPool) = await offloaded;
Console.WriteLine($"with Task.Run: {count} primes, counted on a thread-pool thread: {onPool}");

// The mistake this example shows: async on a method that never awaits.
static async Task<(int Count, bool OnPool)> CountPrimesAsync(int limit) => CountPrimes(limit);

// The sieve of Eratosthenes: the primes below limit.
static (int Count, bool OnPool) CountPrimes(int limit)
{
    var composite = new bool[limit];
    int count = 0;
    for (int n = 2; n < limit; n++)
    {
        if (composite[n])
        {
            continue;
        }

        count++;
        for (long m = (long)n * n; m < limit; m += n)
        {
            composite[m] = true;
        }
    }

    return (count, Thread.CurrentThread.IsThreadPoolThread);
}

async method without await: task completed on return: True
Task.Run: task completed on return: False
without await: 664579 primes, counted on a thread-pool thread: False
with Task.Run: 664579 primes, counted on a thread-pool thread: True

The async method had finished the whole count before it returned: its task was already complete, and the count ran on the main thread, so the caller could do nothing in the meantime. Task.Run queued the same count to a thread-pool thread and returned a task that was not complete yet, which the caller awaited while the count went on elsewhere. Both found 664579 primes. Microsoft’s guide to async scenarios sorts work with two questions: does the code wait for a result, or does it run an expensive computation? The two kinds of work side by side:

Task.Run belongs where one particular thread must stay free, such as the UI thread of a desktop app, or where the caller has other work to do while the count runs. A web request is different: ASP.NET Core already runs it on a thread-pool thread, and Microsoft’s performance guidance says not to call Task.Run and await it at once there, since that only adds a hop to another pool thread. Wrapping a database call in Task.Run gains nothing either: the call already returns a task, and the extra thread would only wait for it.

A failed task keeps its exception until you await it

faults.cs calls a quote method that throws after its wait, then blocks on two more calls instead of awaiting them:

// An exception inside an async method does not fly out of the call. It is stored in the task the call returned,
// and await throws it again, as the same exception.
Task<int> quote = QuoteAsync("west");
Console.WriteLine($"the call returned without an exception; status {quote.Status}");

try
{
    int price = await quote;
    Console.WriteLine($"price {price}");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"await threw {e.GetType().Name}: {e.Message}");
}

Console.WriteLine($"the task is {quote.Status}, its Exception holds {quote.Exception!.InnerExceptions.Count} exception");

// Even a throw before the first await is stored, not thrown at the call.
Task<int> empty = QuoteAsync("");
Console.WriteLine($"empty vendor name: the call returned too; status {empty.Status}");

// Blocking on the task instead of awaiting it: .Result wraps the exception, GetAwaiter().GetResult() does not.
try
{
    _ = QuoteAsync("west").Result;
}
catch (AggregateException e)
{
    Console.WriteLine($".Result threw {e.GetType().Name} around {e.InnerException!.GetType().Name}");
}

try
{
    _ = QuoteAsync("west").GetAwaiter().GetResult();
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"GetAwaiter().GetResult() threw {e.GetType().Name}");
}

static async Task<int> QuoteAsync(string vendor)
{
    ArgumentException.ThrowIfNullOrEmpty(vendor);
    await Task.Delay(100);
    throw new InvalidOperationException($"{vendor} sent no price");
}

the call returned without an exception; status WaitingForActivation
await threw InvalidOperationException: west sent no price
the task is Faulted, its Exception holds 1 exception
empty vendor name: the call returned too; status Faulted
.Result threw AggregateException around InvalidOperationException
GetAwaiter().GetResult() threw InvalidOperationException

The call itself returned normally, with a task still in progress. The exception came out of await quote, as the same InvalidOperationException that was thrown, so a plain try and catch around the await caught it. In between it was stored in the task, which ended Faulted: a faulted taskfaulted task: A task that ended with an unhandled exception. Its Status is Faulted, its Exception property holds the exception inside an AggregateException, and await throws the exception again., whose Exception property is an AggregateExceptionAggregateException: An exception that holds a list of other exceptions in its InnerExceptions property. Task.Exception is one, because a task can fail with more than one exception, and .Result and Wait() throw it too. holding 1 exception. Even the throw at the top of the method, for an empty vendor name, before any await, was stored the same way: that call returned a task that was already Faulted. Follow the exception of the first call:

Blocking on the task changes the shape of the error. .Result threw the AggregateException with the real exception inside it, while GetAwaiter().GetResult() threw the InvalidOperationException itself. Both hold the thread until the task ends, so async code uses await; Microsoft’s guide to task exceptions keeps the blocking forms for synchronous entry points that cannot await.

async void hands its exception to no one, and the process ends

Event handlers must return void, so C# allows async void methods for them. Such a method gives its caller nothing to await, which changes where its exception goes. handlers.cs fails the same way in two click handlers:

// Two click handlers fail the same way. The async Task one returns a task, so its caller awaits it and catches the
// error. The async void one returns nothing to await: its exception goes to the thread pool and ends the process.
AppDomain.CurrentDomain.UnhandledException += (_, e) =>
    Console.WriteLine($"unhandled: {((Exception)e.ExceptionObject).Message}; the process ends: {e.IsTerminating}");

try
{
    await OnPrintClickedAsync(null, EventArgs.Empty);
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"async Task handler: the caller caught '{e.Message}'");
}

try
{
    OnPrintClicked(null, EventArgs.Empty);
    Console.WriteLine("async void handler: the call returned, and no exception reached this try");
}
catch (InvalidOperationException)
{
    Console.WriteLine("never printed: this catch block cannot see the exception");
}

// The async void handler fails while Main waits here.
await Task.Delay(1000);
Console.WriteLine("never printed: the process has already ended");

static async Task OnPrintClickedAsync(object? sender, EventArgs e)
{
    await Task.Delay(100);
    throw new InvalidOperationException("printer out of paper");
}

static async void OnPrintClicked(object? sender, EventArgs e)
{
    await Task.Delay(100);
    throw new InvalidOperationException("printer out of paper");
}

async Task handler: the caller caught 'printer out of paper'
async void handler: the call returned, and no exception reached this try
unhandled: printer out of paper; the process ends: True

Unhandled exception. System.InvalidOperationException: printer out of paper
   at Program.<<Main>$>g__OnPrintClicked|0_2(Object sender, EventArgs e) in ./handlers.cs:line 38
   at System.Threading.Tasks.Task.<>c.<ThrowAsync>b__124_1(Object state)
   at System.Threading.ThreadPoolWorkQueue.Dispatch()
   at System.Threading.PortableThreadPool.WorkerThread.WorkerThreadStart()
   at System.Threading.Thread.StartCallback()

The async Task handler’s exception reached its caller’s catch block. The async void handler’s call returned at its first await, and the try around it caught nothing. When that handler threw, 100 ms later, there was no task to store the exception in. A console app has no synchronization contextAn object that decides where the continuations of awaits run. UI frameworks install one that sends them back to the UI thread; console apps and ASP.NET Core have none, so continuations run on the thread pool. to post it to, so .NET threw it on a thread-pool thread, where an unhandled exception ends the process. The UnhandledException event reported it with IsTerminating true, the runtime printed the stack trace, and the run ended with exit status 134, before Main’s last line. Step through both paths:

Microsoft’s guidance gives async void to event handlers only: the caller cannot catch their exceptions, they are hard to test, and callers do not expect them to still be running. Every other async method returns a task. An event handler that must be async void catches and handles its own exceptions inside.

Practise: the cheapest of three quotes

prices.cs checks CheapestQuoteAsync, which asks several vendors for a price. The rules are at the top of the file, and all five checks fail on the starter:

// Practice: write CheapestQuoteAsync, then run this file until all five checks pass.
// The rules: ask every vendor at once (start every call before awaiting any), skip a vendor whose task fails,
// return the cheapest price that arrived, and throw InvalidOperationException when no vendor sent a price.
// As written, CheapestQuoteAsync throws NotImplementedException.
(string Check, Func<Task<string>> Run, string Expected)[] checks =
[
    ("three prices", () => Cheapest(new Vendor(412, 300), new Vendor(398, 200), new Vendor(405, 250)), "398"),
    ("one vendor fails", () => Cheapest(new Vendor(412, 300), new Vendor(0, 100, Fails: true), new Vendor(405, 250)), "405"),
    ("the cheapest vendor fails", () => Cheapest(new Vendor(399, 100, Fails: true), new Vendor(420, 200)), "420"),
    ("every vendor fails", () => Cheapest(new Vendor(0, 100, Fails: true), new Vendor(0, 50, Fails: true)), "throws InvalidOperationException"),
    ("all calls start before any finishes", StartedTogether, "3 started when the first finished"),
];

int passed = 0;
foreach (var (check, run, expected) in checks)
{
    string got = await run();
    bool ok = got == expected;
    if (ok)
    {
        passed++;
    }

    Console.WriteLine(ok ? $"{check}: ok" : $"{check}: FAIL, {got} instead of {expected}");
}

Console.WriteLine($"{passed} of {checks.Length} checks pass");
return passed == checks.Length ? 0 : 1;

static async Task<int> CheapestQuoteAsync(params Func<Task<int>>[] vendors)
{
    throw new NotImplementedException();
}

static async Task<string> Cheapest(params Vendor[] vendors)
{
    try
    {
        return (await CheapestQuoteAsync([.. vendors.Select(v => (Func<Task<int>>)v.QuoteAsync)])).ToString();
    }
    catch (Exception e)
    {
        return $"throws {e.GetType().Name}";
    }
}

// Each vendor counts the calls started so far; the first one to finish notes how many there were.
static async Task<string> StartedTogether()
{
    var log = new StartLog();
    Vendor[] vendors = [new(412, 300, Log: log), new(398, 200, Log: log), new(405, 250, Log: log)];
    await Cheapest(vendors);
    return log.SeenByFirst is int n ? $"{n} started when the first finished" : "no vendor finished";
}

sealed class StartLog
{
    public int Started;
    public int? SeenByFirst;
}

sealed record Vendor(int Price, int Milliseconds, bool Fails = false, StartLog? Log = null)
{
    public async Task<int> QuoteAsync()
    {
        if (Log is not null)
        {
            Log.Started++;
        }

        await Task.Delay(Milliseconds);
        if (Log is not null)
        {
            Log.SeenByFirst ??= Log.Started;
        }

        return Fails ? throw new InvalidOperationException("the vendor sent no price") : Price;
    }
}

three prices: FAIL, throws NotImplementedException instead of 398
one vendor fails: FAIL, throws NotImplementedException instead of 405
the cheapest vendor fails: FAIL, throws NotImplementedException instead of 420
every vendor fails: FAIL, throws NotImplementedException instead of throws InvalidOperationException
all calls start before any finishes: FAIL, no vendor finished instead of 3 started when the first finished
0 of 5 checks pass

Last, a self-check on all six sections. It begins where your answers so far are weakest, and it gives the reason behind each choice, right or wrong:

Interview questions

Fresher · What does await do to the thread that is running the method?

It lets the thread go. When await meets a task that has not completed, it stores the rest of the method as a continuation and returns to the caller, often with a task of its own; no thread stays blocked inside the method while the operation runs. When the awaited task completes, the continuation is scheduled: on the thread pool in a console app or ASP.NET Core, back on the UI thread in a desktop app. The result, or the stored exception, comes out of the await expression. If the task had already completed, await goes straight on without returning at all. await itself starts no work and creates no thread: the call before it started the operation.

Key takeaways

• An async method runs on the caller’s thread up to the first await of an unfinished task, then returns a task; its continuation runs when that task completes, on the thread pool in a console app.
• Task<T> carries the result that return gives and await takes out; Task carries only the end of the work, and a call whose task nobody awaits runs on unchecked, which CS4014 warns about.
• Independent waits overlap when every call starts before the first await, so the total is the longest wait rather than the sum; I/O-bound waits hold no thread.
• An async method with no await runs to its end before it returns, so CPU-bound work that must not block the caller goes to Task.Run.
• A failed task stores its exception, and await rethrows it as it was thrown, while .Result wraps it in an AggregateException.
• An async void method has no task to hold its exception, so the exception ends the process; keep async void for event handlers that catch their own errors.