Lesson 18. async and await

Mission link: This is the mission's own success criterion: write async/await code and explain what happens to a method's execution at each await. The answer is one sentence from the reference, and the rest of the lesson is its consequences.
Primary source: Docs: "await operator", Microsoft Learn
Prerequisites: Lesson 17, Lesson 16, Lesson 14

Warm-up

1. ▢ Is a task a thread? What settles it?

2. ▢ A task faults and nothing ever waits on it or reads its result. What is the risk?

3. ▢ Which bodies are legal for a void expression-bodied member?

Know this

The whole mechanism is one paragraph from the reference, and it is worth reading slowly. The await operator suspends evaluation of the enclosing async method until the asynchronous operation represented by its operand completes; when the operation completes, await returns its result, if any; await does not block the thread that evaluates the async method; and when await suspends the enclosing method, control returns to the caller of the method (await operator).

Read the last two clauses together and the mission's question is answered. The method stops; the thread does not. Control goes back to whoever called the method, which is free to carry on, and the remainder of the async method runs later, when the operation it was waiting for has finished.

Not every await suspends. Applied to an operand representing an already completed operation, await returns the result immediately, without suspending the enclosing method. So async marks a method that may yield, not one that does, and an async method whose awaits all happen to complete synchronously runs start to finish like an ordinary method. That is worth knowing before you try to reason about ordering from the presence of the keyword.

The type of an await expression, and what it does with failure.

And in both cases, if t throws an exception, await t rethrows it. Set that against lesson 17: joining a task through Wait or Result hands you an AggregateException wrapping the failure, while await rethrows the exception itself. The same fault therefore arrives in two different shapes depending on how you observed it, and await is the one that delivers the exception your catch block was actually written for.

Three places await is forbidden, and the second is a design statement rather than a restriction. You may use await only inside a method, lambda expression or anonymous method carrying the async modifier, and within an async method you may not use it:

• in the body of a synchronous local function,
• inside the block of a lock statement,
• in an unsafe context.

The lock prohibition is the interesting one: you cannot hold a monitor across a suspension. Since the method may resume on a different thread and arbitrary other work may run in between, a lock held across an await would be a lock whose owner has walked away. The language refuses rather than letting you find out.

The operand is usually a Task, Task<TResult>, ValueTask or ValueTask<TResult>, but any awaitable expression works, which is the same extensibility that lets async methods return custom task-like types.

Return types, and the one that breaks the contract. An async method may return Task, Task<TResult>, void, or any type with an accessible GetAwaiter method, of which ValueTask<TResult> is one (async). Use Task<TResult> when the method returns a value, and Task when it does not: the call still returns a Task, and an await of that task evaluates to void.

Then the guidance on void, which is the most consequential sentence in the lesson: generally avoid async void for anything other than event handlers, because callers cannot await those methods and must implement some other mechanism to report successful completion or error conditions.

Put that beside the two facts you already have. Lesson 14 established that an event handler's signature is fixed by its delegate type, which is why the exception exists at all. Lesson 17 established that a faulted task nobody observes is an unhandled exception waiting for a finalizer. An async void method returns nothing to observe, so its failure has nowhere to go by construction. That is the whole argument, and it does not need embellishing.

Two smaller rules worth having. An async method cannot declare in, ref, ref readonly or out parameters, nor return by reference, though it may call methods that do. And Main may return Task or Task<int>, which makes it async so that await works in its body; before that was possible, the way to make Main wait was reading Result or calling Wait, which is exactly the blocking pattern lesson 17 taught you to be suspicious of.

One convention. Asynchronous methods are named with an Async suffix, as in GetStringAsync and GetUrlContentLengthAsync. It is a convention rather than a rule, and following it is how a caller knows there is a task to await before reading the signature.

Practice

1. ▢ In this method, say what has already run when the await suspends it, and where control goes:

public async Task<int> GetUrlContentLengthAsync()
{
    using var client = new HttpClient();
    Task<string> getStringTask = client.GetStringAsync("https://example.com");
    DoIndependentWork();
    string contents = await getStringTask;
    return contents.Length;
}

2. ▢ Does every await suspend the enclosing method?

3. ▢ The same task faults. One caller writes await t; and another writes t.Wait();. What does each one catch?

4. ▢ Why is async void a trap, and what is the one case it exists for?

5. ▢ Which claim about await is correct?

   • a) An await blocks the current thread until the awaited operation finishes running
   • b) An await suspends the enclosing method and returns control to its caller
   • c) An await always suspends, even when the awaited operation has already completed
   • d) An await starts the awaited operation, which does not begin until awaited

Real-world reps

• [ ] Search C# you have access to for async void. For each hit, decide whether it is an event handler, and if it is not, what a caller currently does about failure.
• [ ] Find an async method and mark the point where control returns to its caller. Then check what the caller does immediately afterwards, and whether it depends on the result.
• [ ] Tomorrow: find a catch clause around an awaited call and around a .Result call in the same codebase. Confirm the exception types they catch are the ones each one can actually receive.

Going further

• Docs: "await operator", Microsoft Learn
• Docs: "async keyword", Microsoft Learn
• Docs: "Task asynchronous programming model", Microsoft Learn
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.