{"id":44715,"date":"2023-03-16T04:20:00","date_gmt":"2023-03-16T11:20:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=44715"},"modified":"2023-06-06T17:47:03","modified_gmt":"2023-06-07T00:47:03","slug":"how-async-await-really-works","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/how-async-await-really-works\/","title":{"rendered":"How Async\/Await Really Works in C#"},"content":{"rendered":"

Several weeks ago, the .NET Blog<\/a> featured a post What is .NET, and why should you choose it?<\/a>. It provided a high-level overview of the platform, summarizing various components and design decisions, and promising more in-depth posts on the covered areas. This post is the first such follow-up, deep-diving into the history leading to, the design decisions behind, and implementation details of async<\/code>\/await<\/code> in C# and .NET.<\/p>\n

The support for async<\/code>\/await<\/code> has been around now for over a decade. In that time, it’s transformed how scalable code is written for .NET, and it’s both viable and extremely common to utilize the functionality without understanding exactly what’s going on under the covers. You start with a synchronous method like the following (this method is “synchronous” because a caller will not be able to do anything else until this whole operation completes and control is returned back to the caller):<\/p>\n

\/\/ Synchronously copy all data from source to destination.\r\npublic void CopyStreamToStream(Stream source, Stream destination)\r\n{\r\n    var buffer = new byte[0x1000];\r\n    int numRead;\r\n    while ((numRead = source.Read(buffer, 0, buffer.Length)) != 0)\r\n    {\r\n        destination.Write(buffer, 0, numRead);\r\n    }\r\n}<\/code><\/pre>\n
Then you sprinkle a few keywords, change a few method names, and you end up with the following asynchronous method instead (this method is “asynchronous” because control is expected to be returned back to its caller very quickly and possibly before the work associated with the whole operation has completed):<\/p>\n
\/\/ Asynchronously copy all data from source to destination.\r\npublic async Task CopyStreamToStreamAsync(Stream source, Stream destination)\r\n{\r\n    var buffer = new byte[0x1000];\r\n    int numRead;\r\n    while ((numRead = await source.ReadAsync(buffer, 0, buffer.Length)) != 0)\r\n    {\r\n        await destination.WriteAsync(buffer, 0, numRead);\r\n    }\r\n}<\/code><\/pre>\n
Almost identical in syntax, still able to utilize all of the same control flow constructs, but now non-blocking in nature, with a significantly different underlying execution model, and with all the heavy lifting done for you under the covers by the C# compiler and core libraries.<\/p>\n
While it’s common to use this support without knowing exactly what’s happening under the hood, I’m a firm believer that understanding how something actually works helps you to make even better use of it.  For async<\/code>\/await<\/code> in particular, understanding the mechanisms involved is especially helpful when you want to look below the surface, such as when you’re trying to debug things gone wrong or improve the performance of things otherwise gone right. In this post, then, we’ll deep-dive into exactly how await<\/code> works at the language, compiler, and library level, so that you can make the most of these valuable features.<\/p>\n
To do that well, though, we need to go way back to before async<\/code>\/await<\/code> to understand what state-of-the-art asynchronous code looked like in its absence. Fair warning, it wasn’t pretty.<\/p>\n
In the beginning…<\/h2>\n
All the way back in .NET Framework 1.0, there was the Asynchronous Programming Model pattern, otherwise known as the APM pattern, otherwise known as the Begin\/End pattern, otherwise known as the IAsyncResult<\/code> pattern.  At a high-level, the pattern is simple.  For a synchronous operation DoStuff<\/code>:<\/p>\n
class Handler\r\n{\r\n    public int DoStuff(string arg);\r\n}<\/code><\/pre>\n
there would be two corresponding methods as part of the pattern: a BeginDoStuff<\/code> method and an EndDoStuff<\/code> method:<\/p>\n
class Handler\r\n{\r\n    public int DoStuff(string arg);\r\n\r\n    public IAsyncResult BeginDoStuff(string arg, AsyncCallback? callback, object? state);\r\n    public int EndDoStuff(IAsyncResult asyncResult);\r\n}<\/code><\/pre>\n
BeginDoStuff<\/code> would accept all of the same parameters as does DoStuff<\/code>, but in addition it would also accept an AsyncCallback<\/code><\/a> delegate and an opaque state object<\/code>, one or both of which could be null<\/code>. The Begin method was responsible for initiating the asynchronous operation, and if provided with a callback (often referred to as the “continuation” for the initial operation), it was also responsible for ensuring the callback was invoked when the asynchronous operation completed.  The Begin method would also construct an instance of a type that implemented IAsyncResult<\/code><\/a>, using the optional state<\/code> to populate that IAsyncResult<\/code>‘s AsyncState<\/code> property:<\/p>\n
namespace System\r\n{\r\n    public interface IAsyncResult\r\n    {\r\n        object? AsyncState { get; }\r\n        WaitHandle AsyncWaitHandle { get; }\r\n        bool IsCompleted { get; }\r\n        bool CompletedSynchronously { get; }\r\n    }\r\n\r\n    public delegate void AsyncCallback(IAsyncResult ar);\r\n}<\/code><\/pre>\n
This IAsyncResult<\/code> instance would then both be returned from the Begin method as well as passed to the AsyncCallback<\/code> when it was eventually invoked.  When ready to consume the results of the operation, a caller would then pass that IAsyncResult<\/code> instance to the End method, which was responsible for ensuring the operation was completed (synchronously waiting for it to complete by blocking if it wasn’t) and then returning any result of the operation, including propagating any errors\/exceptions that may have occurred.  Thus, instead of writing code like the following to perform the operation synchronously:<\/p>\n
try\r\n{\r\n    int i = handler.DoStuff(arg); \r\n    Use(i);\r\n}\r\ncatch (Exception e)\r\n{\r\n    ... \/\/ handle exceptions from DoStuff and Use\r\n}<\/code><\/pre>\n
the Begin\/End methods could be used in the following manner to perform the same operation asynchronously:<\/p>\n
try\r\n{\r\n    handler.BeginDoStuff(arg, iar =>\r\n    {\r\n        try\r\n        {\r\n            Handler handler = (Handler)iar.AsyncState!;\r\n            int i = handler.EndDoStuff(iar);\r\n            Use(i);\r\n        }\r\n        catch (Exception e2)\r\n        {\r\n            ... \/\/ handle exceptions from EndDoStuff and Use\r\n        }\r\n    }, handler);\r\n}\r\ncatch (Exception e)\r\n{\r\n    ... \/\/ handle exceptions thrown from the synchronous call to BeginDoStuff\r\n}<\/code><\/pre>\n
For anyone who’s dealt with callback-based APIs in any language, this should feel familiar.<\/p>\n
Things only got more complicated from there, however. For instance, there’s the issue of “stack dives.”  A stack dive is when code repeatedly makes calls that go deeper and deeper on the stack, to the point where it could potentially stack overflow.  The Begin method is allowed to invoke the callback synchronously if the operation completes synchronously, meaning the call to Begin might itself directly invoke the callback.  And “asynchronous” operations that complete synchronously are actually very common; they’re not “asynchronous” because they’re guaranteed to complete asynchronously but rather are just permitted to. For example, consider an asynchronous read from some networked operation, like receiving from a socket.  If you need only a small amount of data for each individual operation, such as reading some header data from a response, you might put a buffer in place in order to avoid the overhead of lots of system calls. Instead of doing a small read for just the amount of data you need immediately, you perform a larger read into the buffer and then consume data from that buffer until its exhausted; that lets you reduce the number of expensive system calls required to actually interact with the socket.  Such a buffer might exist behind whatever asynchronous abstraction you’re using, such that the first “asynchronous” operation you perform (filling the buffer) completes asynchronously, but then all subsequent operations until that underlying buffer is exhausted don’t actually need to do any I\/O, instead just pulling from the buffer, and can thus all complete synchronously.  When the Begin method performs one of these operations, and finds it completes synchronously, it can then invoke the callback synchronously.  That means you have one stack frame that called the Begin method, another stack frame for the Begin method itself, and now another stack frame for the callback.  Now what happens if that callback turns around and calls Begin again?  If that operation completes synchronously and its callback is invoked synchronously, you’re now again several more frames deep on the stack.  And so on, and so on, until eventually you run out of stack.<\/p>\n
This is a real possibility that’s easy to repro.  Try this program on .NET Core:<\/p>\n
using System.Net;\r\nusing System.Net.Sockets;\r\n\r\nusing Socket listener = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);\r\nlistener.Bind(new IPEndPoint(IPAddress.Loopback, 0));\r\nlistener.Listen();\r\n\r\nusing Socket client = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);\r\nclient.Connect(listener.LocalEndPoint!);\r\n\r\nusing Socket server = listener.Accept();\r\n_ = server.SendAsync(new byte[100_000]);\r\n\r\nvar mres = new ManualResetEventSlim();\r\nbyte[] buffer = new byte[1];\r\n\r\nvar stream = new NetworkStream(client);\r\n\r\nvoid ReadAgain()\r\n{\r\n    stream.BeginRead(buffer, 0, 1, iar =>\r\n    {\r\n        if (stream.EndRead(iar) != 0)\r\n        {\r\n            ReadAgain(); \/\/ uh oh!\r\n        }\r\n        else\r\n        {\r\n            mres.Set();\r\n        }\r\n    }, null);\r\n};\r\nReadAgain();\r\n\r\nmres.Wait();<\/code><\/pre>\n
Here I’ve set up a simple client socket and server socket connected to each other.  The server sends 100,000 bytes to the client, which then proceeds to use BeginRead<\/code>\/EndRead<\/code> to consume them “asynchronously” one at a time (this is terribly inefficient and is only being done in the name of pedagogy).  The callback passed to BeginRead<\/code> finishes the read by calling EndRead<\/code>, and then if it successfully read the desired byte (in which case it wasn’t yet at end-of-stream), it issues another BeginRead<\/code> via a recursive call to the ReadAgain<\/code> local function.  However, in .NET Core, socket operations are much faster than they were on .NET Framework, and will complete synchronously if the OS is able to satisfy the operation synchronously (noting the kernel itself has a buffer used to satisfy socket receive operations).  Thus, this stack overflows:\n\"Stack<\/p>\n
So, compensation for this was built into the APM model.  There are two possible ways to compensate for this:<\/p>\n
    \n
  1. Don’t allow the AsyncCallback<\/code> to be invoked synchronously.  If it’s always invoked asynchronously, even if the operation completes synchronously, then the risk of stack dives goes away.  But so too does performance, because operations that complete synchronously (or so quickly that they’re observably indistinguishable) are very common, and forcing each of those to queue its callback adds measurable overhead.<\/li>\n
  2. Employ a mechanism that allows the caller rather than the callback to do the continuation work if the operation completes synchronously. That way, you escape the extra method frame and continue doing the follow-on work no deeper on the stack.<\/li>\n<\/ol>\n
    The APM pattern goes with option (2). For that, the IAsyncResult<\/code> interface exposes two related but distinct members: IsCompleted<\/code> and CompletedSynchronously<\/code>.  IsCompleted<\/code> tells you whether the operation has completed: you can check it multiple times, and eventually it’ll transition from false<\/code> to true<\/code> and then stay there.  In contrast, CompletedSynchronously<\/code> never changes (or if it does, it’s a nasty bug waiting to happen); it’s used to communicate between the caller of the Begin method and the AsyncCallback<\/code> which of them is responsible for performing any continuation work.  If CompletedSynchronously<\/code> is false<\/code>, then the operation is completing asynchronously and any continuation work in response to the operation completing should be left up to the callback; after all, if the work didn’t complete synchronously, the caller of Begin can’t really handle it because the operation isn’t known to be done yet (and if the caller were to just call End, it would block until the operation completed).  If, however, CompletedSynchronously<\/code> is true<\/code>, if the callback were to handle the continuation work, then it risks a stack dive, as it’ll be performing that continuation work deeper on the stack than where it started.  Thus, any implementations at all concerned about such stack dives need to examine CompletedSynchronously<\/code> and have the caller of the Begin method do the continuation work if it’s true<\/code>, which means the callback then needs to not<\/em> do the continuation work.  This is also why CompletedSynchronously<\/code> must never change: the caller and the callback need to see the same value to ensure that the continuation work is performed once and only once, regardless of race conditions.<\/p>\n
    In our previous DoStuff<\/code> example, that then leads to code like this:<\/p>\n
    try\r\n{\r\n    IAsyncResult ar = handler.BeginDoStuff(arg, iar =>\r\n    {\r\n        if (!iar.CompletedSynchronously)\r\n        {\r\n            try\r\n            {\r\n                Handler handler = (Handler)iar.AsyncState!;\r\n                int i = handler.EndDoStuff(iar);\r\n                Use(i);\r\n            }\r\n            catch (Exception e2)\r\n            {\r\n                ... \/\/ handle exceptions from EndDoStuff and Use\r\n            }\r\n        }\r\n    }, handler);\r\n    if (ar.CompletedSynchronously)\r\n    {\r\n        int i = handler.EndDoStuff(ar);\r\n        Use(i);\r\n    }\r\n}\r\ncatch (Exception e)\r\n{\r\n    ... \/\/ handle exceptions that emerge synchronously from BeginDoStuff and possibly EndDoStuff\/Use\r\n}<\/code><\/pre>\n
    That’s a mouthful.  And so far we’ve only looked at consuming the pattern… we haven’t looked at implementing the pattern.  While most developers wouldn’t need to be concerned about leaf operations (e.g. implementing the actual Socket.BeginReceive<\/code>\/EndReceive<\/code> methods that interact with the operating system), many, many developers would need to be concerned with composing these operations (performing multiple asynchronous operations that together form a larger one), which means not only consuming other Begin\/End methods but also implementing them yourself so that your composition itself can be consumed elsewhere.  And, you’ll notice there was no control flow in my previous DoStuff<\/code> example.  Introduce multiple operations into this, especially with even simple control flow like a loop, and all of a sudden this becomes the domain of experts that enjoy pain, or blog post authors trying to make a point.<\/p>\n
    So just to drive that point home, let’s implement a complete example.  At the beginning of this post, I showed a CopyStreamToStream<\/code> method that copies all of the data from one stream to another (\u00e0 la Stream.CopyTo<\/code>, but, for the sake of explanation, assuming that doesn’t exist):<\/p>\n
    public void CopyStreamToStream(Stream source, Stream destination)\r\n{\r\n    var buffer = new byte[0x1000];\r\n    int numRead;\r\n    while ((numRead = source.Read(buffer, 0, buffer.Length)) != 0)\r\n    {\r\n        destination.Write(buffer, 0, numRead);\r\n    }\r\n}<\/code><\/pre>\n
    Straightforward: we repeatedly read from one stream and then write the resulting data to the other, read from one stream and write to the other, and so on, until we have no more data to read.  Now, how would we implement this asynchronously using the APM pattern?  Something like this:<\/p>\n
    public IAsyncResult BeginCopyStreamToStream(\r\n    Stream source, Stream destination,\r\n    AsyncCallback callback, object state)\r\n{\r\n    var ar = new MyAsyncResult(state);\r\n    var buffer = new byte[0x1000];\r\n\r\n    Action<IAsyncResult?> readWriteLoop = null!;\r\n    readWriteLoop = iar =>\r\n    {\r\n        try\r\n        {\r\n            for (bool isRead = iar == null; ; isRead = !isRead)\r\n            {\r\n                if (isRead)\r\n                {\r\n                    iar = source.BeginRead(buffer, 0, buffer.Length, static readResult =>\r\n                    {\r\n                        if (!readResult.CompletedSynchronously)\r\n                        {\r\n                            ((Action<IAsyncResult?>)readResult.AsyncState!)(readResult);\r\n                        }\r\n                    }, readWriteLoop);\r\n\r\n                    if (!iar.CompletedSynchronously)\r\n                    {\r\n                        return;\r\n                    }\r\n                }\r\n                else\r\n                {\r\n                    int numRead = source.EndRead(iar!);\r\n                    if (numRead == 0)\r\n                    {\r\n                        ar.Complete(null);\r\n                        callback?.Invoke(ar);\r\n                        return;\r\n                    }\r\n\r\n                    iar = destination.BeginWrite(buffer, 0, numRead, writeResult =>\r\n                    {\r\n                        if (!writeResult.CompletedSynchronously)\r\n                        {\r\n                            try\r\n                            {\r\n                                destination.EndWrite(writeResult);\r\n                                readWriteLoop(null);\r\n                            }\r\n                            catch (Exception e2)\r\n                            {\r\n                                ar.Complete(e);\r\n                                callback?.Invoke(ar);\r\n                            }\r\n                        }\r\n                    }, null);\r\n\r\n                    if (!iar.CompletedSynchronously)\r\n                    {\r\n                        return;\r\n                    }\r\n\r\n                    destination.EndWrite(iar);\r\n                }\r\n            }\r\n        }\r\n        catch (Exception e)\r\n        {\r\n            ar.Complete(e);\r\n            callback?.Invoke(ar);\r\n        }\r\n    };\r\n\r\n    readWriteLoop(null);\r\n\r\n    return ar;\r\n}\r\n\r\npublic void EndCopyStreamToStream(IAsyncResult asyncResult)\r\n{\r\n    if (asyncResult is not MyAsyncResult ar)\r\n    {\r\n        throw new ArgumentException(null, nameof(asyncResult));\r\n    }\r\n\r\n    ar.Wait();\r\n}\r\n\r\nprivate sealed class MyAsyncResult : IAsyncResult\r\n{\r\n    private bool _completed;\r\n    private int _completedSynchronously;\r\n    private ManualResetEvent? _event;\r\n    private Exception? _error;\r\n\r\n    public MyAsyncResult(object? state) => AsyncState = state;\r\n\r\n    public object? AsyncState { get; }\r\n\r\n    public void Complete(Exception? error)\r\n    {\r\n        lock (this)\r\n        {\r\n            _completed = true;\r\n            _error = error;\r\n            _event?.Set();\r\n        }\r\n    }\r\n\r\n    public void Wait()\r\n    {\r\n        WaitHandle? h = null;\r\n        lock (this)\r\n        {\r\n            if (_completed)\r\n            {\r\n                if (_error is not null)\r\n                {\r\n                    throw _error;\r\n                }\r\n                return;\r\n            }\r\n\r\n            h = _event ??= new ManualResetEvent(false);\r\n        }\r\n\r\n        h.WaitOne();\r\n        if (_error is not null)\r\n        {\r\n            throw _error;\r\n        }\r\n    }\r\n\r\n    public WaitHandle AsyncWaitHandle\r\n    {\r\n        get\r\n        {\r\n            lock (this)\r\n            {\r\n                return _event ??= new ManualResetEvent(_completed);\r\n            }\r\n        }\r\n    }\r\n\r\n    public bool CompletedSynchronously\r\n    {\r\n        get\r\n        {\r\n            lock (this)\r\n            {\r\n                if (_completedSynchronously == 0)\r\n                {\r\n                    _completedSynchronously = _completed ? 1 : -1;\r\n                }\r\n\r\n                return _completedSynchronously == 1;\r\n            }\r\n        }\r\n    }\r\n\r\n    public bool IsCompleted\r\n    {\r\n        get\r\n        {\r\n            lock (this)\r\n            {\r\n                return _completed;\r\n            }\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
    Yowsers.  And, even with all of that gobbledygook, it’s still not a great implementation.  For example, the IAsyncResult<\/code> implementation is locking on every operation rather than doing things in a more lock-free manner where possible, the Exception<\/code> is being stored raw rather than as an ExceptionDispatchInfo<\/code><\/a> that would enable augmenting its call stack when propagated, there’s a lot of allocation involved in each individual operation (e.g. a delegate being allocated for each BeginWrite<\/code> call), and so on. Now, imagine having to do all of this for each method you wanted to write.  Every time you wanted to write a reusable method that would consume another asynchronous operation, you’d need to do all of this work.  And if you wanted to write reusable combinators that could operate over multiple discrete IAsyncResult<\/code>s efficiently (think Task.WhenAll<\/code>), that’s another level of difficulty; every operation implementing and exposing its own APIs specific to that operation meant there was no lingua franca for talking about them all similarly (though some developers wrote libraries that tried to ease the burden a bit, typically via another layer of callbacks that enabled the API to supply an appropriate AsyncCallback<\/code> to a Begin method).<\/p>\n
    And all of that complication meant that very few folks even attempted this, and for those who did, well, bugs were rampant.  To be fair, this isn’t really a criticism of the APM pattern.  Rather, it’s a critique of callback-based asynchrony in general.  We’re all so used to the power and simplicity that control flow constructs in modern languages provide us with, and callback-based approaches typically run afoul of such constructs once any reasonable amount of complexity is introduced.  No other mainstream language had a better alternative available, either.<\/p>\n
    We needed a better way, one in which we learned from the APM pattern, incorporating the things it got right while avoiding its pitfalls.  An interesting thing to note is that the APM pattern is just that, a pattern; the runtime, core libraries, and compiler didn’t provide any assistance in consuming or implementing the pattern.<\/p>\n
    Event-Based Asynchronous Pattern<\/h2>\n
    .NET Framework 2.0 saw a few APIs introduced that implemented a different pattern for handling asynchronous operations, one primarily intended for doing so in the context of client applications.  This Event-based Asynchronous Pattern, or EAP, also came as a pair of members (at least, possibly more), this time a method to initiate the asynchronous operation and an event to listen for its completion.  Thus, our earlier DoStuff<\/code> example might have been exposed as a set of members like this:<\/p>\n
    class Handler\r\n{\r\n    public int DoStuff(string arg);\r\n\r\n    public void DoStuffAsync(string arg, object? userToken);\r\n    public event DoStuffEventHandler? DoStuffCompleted;\r\n}\r\n\r\npublic delegate void DoStuffEventHandler(object sender, DoStuffEventArgs e);\r\n\r\npublic class DoStuffEventArgs : AsyncCompletedEventArgs\r\n{\r\n    public DoStuffEventArgs(int result, Exception? error, bool canceled, object? userToken) :\r\n        base(error, canceled, usertoken) => Result = result;\r\n\r\n    public int Result { get; }\r\n}<\/code><\/pre>\n
    You’d register your continuation work with the DoStuffCompleted<\/code> event and then invoke the DoStuffAsync<\/code> method; it would initiate the operation, and upon that operation’s completion, the DoStuffCompleted<\/code> event would be raised asynchronously from the caller.  The handler could then run its continuation work, likely validating that the userToken<\/code> supplied matched the one it was expecting, enabling multiple handlers to be hooked up to the event at the same time.<\/p>\n
    This pattern made a few use cases a bit easier while making other uses cases significantly harder (and given the previous APM CopyStreamToStream<\/code> example, that’s saying something). It didn’t get rolled out in a widespread manner, and it came and went effectively in a single release of .NET Framework, albeit leaving behind the APIs added during its tenure, like Ping.SendAsync<\/code>\/Ping.PingCompleted<\/code>:<\/p>\n
    public class Ping : Component\r\n{\r\n    public void SendAsync(string hostNameOrAddress, object? userToken);\r\n    public event PingCompletedEventHandler? PingCompleted;\r\n    ...\r\n}<\/code><\/pre>\n
    However, it did add one notable advance that the APM pattern didn’t factor in at all, and that has endured into the models we embrace today: SynchronizationContext<\/code><\/a>.<\/p>\n
    SynchronizationContext<\/code> was also introduced in .NET Framework 2.0, as an abstraction for a general scheduler.  In particular, SynchronizationContext<\/code>‘s most used method is Post<\/code>, which queues a work item to whatever scheduler is represented by that context.  The base implementation of SynchronizationContext<\/code>, for example, just represents the ThreadPool<\/code>, and so the base implementation of SynchronizationContext.Post<\/code><\/a> simply delegates to ThreadPool.QueueUserWorkItem<\/code><\/a>, which is used to ask the ThreadPool<\/code> to invoke the supplied callback with the associated state on one the pool’s threads. However, SynchronizationContext<\/code>‘s bread-and-butter isn’t just about supporting arbitrary schedulers, rather it’s about supporting scheduling in a manner that works according to the needs of various application models.<\/p>\n
    Consider a UI framework like Windows Forms.  As with most UI frameworks on Windows, controls are associated with a particular thread, and that thread runs a message pump which runs work that’s able to interact with those controls: only that thread should try to manipulate those controls, and any other thread that wants to interact with the controls should do so by sending a message to be consumed by the UI thread’s pump.  Windows Forms makes this easy with methods like Control.BeginInvoke<\/code>, which queues the supplied delegate and arguments to be run by whatever thread is associated with that Control<\/code>.  You can thus write code like this:<\/p>\n
    private void button1_Click(object sender, EventArgs e)\r\n{\r\n    ThreadPool.QueueUserWorkItem(_ =>\r\n    {\r\n        string message = ComputeMessage();\r\n        button1.BeginInvoke(() =>\r\n        {\r\n            button1.Text = message;\r\n        });\r\n    });\r\n}<\/code><\/pre>\n
    That will offload the ComputeMessage()<\/code> work to be done on a ThreadPool<\/code> thread (so as to keep the UI responsive while it’s being processed), and then when that work has completed, queue a delegate back to the thread associated with button1<\/code> to update button1<\/code>‘s label.  Easy enough.  WPF has something similar, just with its Dispatcher<\/code> type:<\/p>\n
    private void button1_Click(object sender, RoutedEventArgs e)\r\n{\r\n    ThreadPool.QueueUserWorkItem(_ =>\r\n    {\r\n        string message = ComputeMessage();\r\n        button1.Dispatcher.InvokeAsync(() =>\r\n        {\r\n            button1.Content = message;\r\n        });\r\n    });\r\n}<\/code><\/pre>\n
    And .NET MAUI has something similar. But what if I wanted to put this logic into a helper method? e.g.<\/p>\n
    \/\/ Call ComputeMessage and then invoke the update action to update controls.\r\ninternal static void ComputeMessageAndInvokeUpdate(Action<string> update) { ... }<\/code><\/pre>\n
    I could then use that like this:<\/p>\n
    private void button1_Click(object sender, EventArgs e)\r\n{\r\n    ComputeMessageAndInvokeUpdate(message => button1.Text = message);\r\n}<\/code><\/pre>\n
    but how could ComputeMessageAndInvokeUpdate<\/code> be implemented in such a way that it could work in any of those applications?  Would it need to be hardcoded to know about every possible UI framework? That’s where SynchronizationContext<\/code> shines.  We might implement the method like this:<\/p>\n
    internal static void ComputeMessageAndInvokeUpdate(Action<string> update)\r\n{\r\n    SynchronizationContext? sc = SynchronizationContext.Current;\r\n    ThreadPool.QueueUserWorkItem(_ =>\r\n    {\r\n        string message = ComputeMessage();\r\n        if (sc is not null)\r\n        {\r\n            sc.Post(_ => update(message), null);\r\n        }\r\n        else\r\n        {\r\n            update(message);\r\n        }\r\n    });\r\n}<\/code><\/pre>\n
    That uses the SynchronizationContext<\/code> as an abstraction to target whatever “scheduler” should be used to get back to the necessary environment for interacting with the UI.  Each application model then ensures it’s published as SynchronizationContext.Current<\/code> a SynchronizationContext<\/code>-derived type that does the “right thing.”  For example, Windows Forms has this<\/a>:<\/p>\n
    public sealed class WindowsFormsSynchronizationContext : SynchronizationContext, IDisposable\r\n{\r\n    public override void Post(SendOrPostCallback d, object? state) =>\r\n        _controlToSendTo?.BeginInvoke(d, new object?[] { state });\r\n    ...\r\n}<\/code><\/pre>\n
    and WPF has this<\/a>:<\/p>\n
    public sealed class DispatcherSynchronizationContext : SynchronizationContext\r\n{\r\n    public override void Post(SendOrPostCallback d, Object state) =>\r\n        _dispatcher.BeginInvoke(_priority, d, state);\r\n    ...\r\n}<\/code><\/pre>\n
    ASP.NET used<\/em> to have one<\/a>, which didn’t actually care about what thread work ran on, but rather that work associated with a given request was serialized such that multiple threads wouldn’t concurrently be accessing a given HttpContext<\/code>:<\/p>\n
    internal sealed class AspNetSynchronizationContext : AspNetSynchronizationContextBase\r\n{\r\n    public override void Post(SendOrPostCallback callback, Object state) =>\r\n        _state.Helper.QueueAsynchronous(() => callback(state));\r\n    ...\r\n}<\/code><\/pre>\n
    This also isn’t limited to such main application models.  For example, xunit<\/a> is a popular unit testing framework, one that .NET’s core repos use for their unit testing, and it also employs multiple custom SynchronizationContext<\/code>s. You can, for example, allow tests to run in parallel but limit the number of tests that are allowed to be running concurrently.  How is that enabled? Via a SynchronizationContext<\/code>:<\/p>\n
    public class MaxConcurrencySyncContext : SynchronizationContext, IDisposable\r\n{\r\n    public override void Post(SendOrPostCallback d, object? state)\r\n    {\r\n        var context = ExecutionContext.Capture();\r\n        workQueue.Enqueue((d, state, context));\r\n        workReady.Set();\r\n    }\r\n}<\/code><\/pre>\n
    MaxConcurrencySyncContext<\/code>‘s<\/a> Post<\/code> method just queues the work to its own internal work queue, which it then processes on its own worker threads, where it controls how many there are based on the max concurrency desired. You get the idea.<\/p>\n
    How does this tie in with the Event-based Asynchronous Pattern?  Both EAP and SynchronizationContext<\/code> were introduced at the same time, and the EAP dictated that the completion events should be queued to whatever SynchronizationContext<\/code> was current when the asynchronous operation was initiated.  To simplify that ever so slightly (and arguably not enough to warrant the extra complexity), some helper types were also introduced in System.ComponentModel<\/code>, in particular AsyncOperation<\/code> and AsyncOperationManager<\/code>.  The former was just a tuple that wrapped the user-supplied state object and the captured SynchronizationContext<\/code>, and the latter just served as a simple factory to do that capture and create the AsyncOperation<\/code> instance.  Then EAP implementations would use those, e.g. Ping.SendAsync<\/code> called AsyncOperationManager.CreateOperation<\/code><\/a> to capture the SynchronizationContext<\/code>, and then when the operation completed, the AsyncOperation<\/code>‘s PostOperationCompleted<\/code><\/a> method would be invoked to call the stored SynchronizationContext<\/code>‘s Post<\/code> method.<\/p>\n
    SynchronizationContext<\/code> provides a few more trinkets worthy of mention as they’ll show up again in a bit.  In particular, it exposes OperationStarted<\/code> and OperationCompleted<\/code> methods.  The base implementation of these virtuals are empty, doing nothing, but a derived implementation might override these to know about in-flight operations.  That means EAP implementations would also invoke these OperationStarted<\/code>\/OperationCompleted<\/code> at the beginning and end of each operation, in order to inform any present SynchronizationContext<\/code> and allow it to track the work.  This is particularly relevant to the EAP pattern because the methods that initiate the async operations are void<\/code> returning: you get nothing back that allows you to track the work individually.  We’ll get back to that.<\/p>\n
    So, we needed something better than the APM pattern, and the EAP that came next introduced some new things but didn’t really address the core problems we faced. We still needed something better.<\/p>\n
    Enter Tasks<\/h2>\n
    .NET Framework 4.0 introduced the System.Threading.Tasks.Task<\/code> type. At its heart, a Task<\/code> is just a data structure that represents the eventual completion of some asynchronous operation (other frameworks call a similar type a “promise” or a “future”).  A Task<\/code> is created to represent some operation, and then when the operation it logically represents completes, the results are stored into that Task<\/code>. Simple enough. But the<\/em> key feature that Task<\/code> provides that makes it leaps and bounds more useful than IAsyncResult<\/code> is that it builds into itself the notion of a continuation.  That one feature means you can walk up to any Task<\/code> and ask to be notified asynchronously when it completes, with the task itself handling the synchronization to ensure the continuation is invoked regardless of whether the task has already completed, hasn’t yet completed, or is completing concurrently with the notification request. Why is that so impactful?  Well, if you remember back to our discussion of the old APM pattern, there were two primary problems.<\/p>\n
      \n
    1. You had to implement a custom IAsyncResult<\/code> implementation for every operation: there was no built-in IAsyncResult<\/code> implementation anyone could just use for their needs.<\/li>\n
    2. You had to know prior to the Begin method being called what you wanted to do when it was complete. This makes it a significant challenge to implement combinators and other generalized routines for consuming and composing arbitrary async implementations.<\/li>\n<\/ol>\n
      In contrast, with Task<\/code>, that shared representation lets you walk up to an async operation after<\/em> you’ve already initiated the operation and provide a continuation after<\/em> you’ve already initiated the operation… you don’t need to provide that continuation to<\/em> the method that initiates the operation.  Everyone who has asynchronous operations can produce a Task<\/code>, and everyone who consumes asynchronous operations can consume a Task<\/code>, and nothing custom needs to be done to connect the two: Task<\/code> becomes the lingua franca for enabling producers and consumers of asynchronous operations to talk.  And that has changed the face of .NET.  More on that in a bit…<\/p>\n
      For now, let’s better understand what this actually means.  Rather than dive into the intricate code for Task<\/code>, we’ll do the pedagogical thing and just implement a simple version.  This isn’t meant to be a great implementation, rather only complete enough functionally to help understand the meat of what is a Task<\/code>, which, at the end of the day, is really just a data structure that handles coordinating the setting and reception of a completion signal.  We’ll start with just a few fields:<\/p>\n
      class MyTask\r\n{\r\n    private bool _completed;\r\n    private Exception? _error;\r\n    private Action<MyTask>? _continuation;\r\n    private ExecutionContext? _ec;\r\n    ...\r\n}<\/code><\/pre>\n
      We need a field to know whether the task has completed (_completed<\/code>), and we need a field to store any error that caused the task to fail (_error<\/code>); if we were also implementing a generic MyTask<TResult><\/code>, there’d also be a private TResult _result<\/code> field for storing the successful result of the operation.  Thus far, this looks a lot like our custom IAsyncResult<\/code> implementation earlier (not a coincidence, of course).  But now the pi\u00e8ce de r\u00e9sistance, the _continuation<\/code> field. In this simple implementation, we’re supporting just a single continuation, but that’s enough for explanatory purposes (the real Task<\/code> employs an object<\/code> field<\/a> that can either be an individual continuation object or a List<><\/code> of continuation objects).  This is a delegate that will be invoked when the task completes.<\/p>\n
      Now, a bit of surface area. As noted, one of the fundamental advances in Task<\/code> over previous models was the ability to supply the continuation work (the callback) after<\/em> the operation was initiated.  We need a method to let us do that, so let’s add ContinueWith<\/code>:<\/p>\n
      public void ContinueWith(Action<MyTask> action)\r\n{\r\n    lock (this)\r\n    {\r\n        if (_completed)\r\n        {\r\n            ThreadPool.QueueUserWorkItem(_ => action(this));\r\n        }\r\n        else if (_continuation is not null)\r\n        {\r\n            throw new InvalidOperationException(\"Unlike Task, this implementation only supports a single continuation.\");\r\n        }\r\n        else\r\n        {\r\n            _continuation = action;\r\n            _ec = ExecutionContext.Capture();\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
      If the task has already been marked completed by the time ContinueWith<\/code> is called, ContinueWith<\/code> just queues the execution of the delegate.  Otherwise, the method stores the delegate, such that the continuation may be queued when the task completes (it also stores something called an ExecutionContext<\/code>, and then uses that when the delegate is later invoked, but don’t worry about that part for now… we’ll get to it).  Simple enough.<\/p>\n
      Then we need to be able to mark the MyTask<\/code> as completed, meaning whatever asynchronous operation it represents has finished. For that, we’ll expose two methods, one to mark it completed successfully (“SetResult”), and one to mark it completed with an error (“SetException”):<\/p>\n
      public void SetResult() => Complete(null);\r\n\r\npublic void SetException(Exception error) => Complete(error);\r\n\r\nprivate void Complete(Exception? error)\r\n{\r\n    lock (this)\r\n    {\r\n        if (_completed)\r\n        {\r\n            throw new InvalidOperationException(\"Already completed\");\r\n        }\r\n\r\n        _error = error;\r\n        _completed = true;\r\n\r\n        if (_continuation is not null)\r\n        {\r\n            ThreadPool.QueueUserWorkItem(_ =>\r\n            {\r\n                if (_ec is not null)\r\n                {\r\n                    ExecutionContext.Run(_ec, _ => _continuation(this), null);\r\n                }\r\n                else\r\n                {\r\n                    _continuation(this);\r\n                }\r\n            });\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
      We store any error, we mark the task as having been completed, and then if a continuation had previously been registered, we queue it to be invoked.<\/p>\n
      Finally, we need a way to propagate any exception that may have occurred in the task (and, if this were a generic MyTask<T><\/code>, to return its _result<\/code>); to facilitate certain scenarios, we also allow this method to block waiting for the task to complete, which we can implement in terms of ContinueWith<\/code> (the continuation just signals a ManualResetEventSlim<\/code> that the caller then blocks on waiting for completion).<\/p>\n
      public void Wait()\r\n{\r\n    ManualResetEventSlim? mres = null;\r\n    lock (this)\r\n    {\r\n        if (!_completed)\r\n        {\r\n            mres = new ManualResetEventSlim();\r\n            ContinueWith(_ => mres.Set());\r\n        }\r\n    }\r\n\r\n    mres?.Wait();\r\n    if (_error is not null)\r\n    {\r\n        ExceptionDispatchInfo.Throw(_error);\r\n    }\r\n}<\/code><\/pre>\n
      And that’s basically it. Now to be sure, the real Task<\/code> is way more complicated, with a much more efficient implementation, with support for any number of continuations, with a multitude of knobs about how it should behave (e.g. should continuations be queued as is being done here or should they be invoked synchronously as part of the task’s completion), with the ability to store multiple exceptions rather than just one, with special knowledge of cancellation, with tons of helper methods for doing common operations (e.g. Task.Run<\/code> which creates a Task<\/code> to represent a delegate queued to be invoked on the thread pool), and so on.  But there’s no magic to any of that; at its core, it’s just what we saw here.<\/p>\n
      You might also notice that my simple MyTask<\/code> has public SetResult<\/code>\/SetException<\/code> methods directly on it, whereas Task<\/code> doesn’t.  Actually, Task<\/code> does<\/em> have such methods, they’re just internal<\/a>, with a System.Threading.Tasks.TaskCompletionSource<\/code> type serving as a separate “producer” for the task and its completion; that was done not out of technical necessity but as a way to keep the completion methods off of the thing meant only for consumption.  You can then hand out a Task<\/code> without having to worry about it being completed out from under you; the completion signal is an implementation detail of whatever created the task and also reserves the right to complete it by keeping the TaskCompletionSource<\/code> to itself. (CancellationToken<\/code> and CancellationTokenSource<\/code> follow a similar pattern: CancellationToken<\/code> is just a struct wrapper for a CancellationTokenSource<\/code>, serving up only the public surface area related to consuming a cancellation signal but without the ability to produce one, which is a capability restricted to whomever has access to the CancellationTokenSource<\/code>.)<\/p>\n
      Of course, we can implement combinators and helpers for this MyTask<\/code> similar to what Task<\/code> provides.  Want a simple MyTask.WhenAll<\/code>? Here you go:<\/p>\n
      public static MyTask WhenAll(MyTask t1, MyTask t2)\r\n{\r\n    var t = new MyTask();\r\n\r\n    int remaining = 2;\r\n    Exception? e = null;\r\n\r\n    Action<MyTask> continuation = completed =>\r\n    {\r\n        e ??= completed._error; \/\/ just store a single exception for simplicity\r\n        if (Interlocked.Decrement(ref remaining) == 0)\r\n        {\r\n            if (e is not null) t.SetException(e);\r\n            else t.SetResult();\r\n        }\r\n    };\r\n\r\n    t1.ContinueWith(continuation);\r\n    t2.ContinueWith(continuation);\r\n\r\n    return t;\r\n}<\/code><\/pre>\n
      Want a MyTask.Run<\/code>? You got it:<\/p>\n
      public static MyTask Run(Action action)\r\n{\r\n    var t = new MyTask();\r\n\r\n    ThreadPool.QueueUserWorkItem(_ =>\r\n    {\r\n        try\r\n        {\r\n            action();\r\n            t.SetResult();\r\n        }\r\n        catch (Exception e)\r\n        {\r\n            t.SetException(e);\r\n        }\r\n    });\r\n\r\n    return t;\r\n}<\/code><\/pre>\n
      How about a MyTask.Delay<\/code>? Sure:<\/p>\n
      public static MyTask Delay(TimeSpan delay)\r\n{\r\n    var t = new MyTask();\r\n\r\n    var timer = new Timer(_ => t.SetResult());\r\n    timer.Change(delay, Timeout.InfiniteTimeSpan);\r\n\r\n    return t;\r\n}<\/code><\/pre>\n
      You get the idea.<\/p>\n
      With Task<\/code> in place, all previous async patterns in .NET became a thing of the past.  Anywhere an asynchronous implementation previously was implemented with the APM pattern or the EAP pattern, new Task<\/code>-returning methods were exposed.<\/p>\n
      And ValueTasks<\/h3>\n
      Task<\/code> continues to be the workhorse for asynchrony in .NET to this day, with new methods exposed every release and routinely throughout the ecosystem that return Task<\/code> and Task<TResult><\/code>. However, Task<\/code> is a class, which means creating one does come with an allocation.  For the most part, one extra allocation for a long-lived asynchronous operation is a pittance and won’t meaningfully impact performance for all but the most performance-sensitive operations.  However, as was previously noted, synchronous completion of asynchronous operations is fairly common.  Stream.ReadAsync<\/code> was introduced to return a Task<int><\/code>, but if you’re reading from, say, a BufferedStream<\/code>, there’s a really good chance many of your reads are going to complete synchronously due to simply needing to pull data from an in-memory buffer rather than performing syscalls and real I\/O.  Having to allocate an additional object just to return such data is unfortunate (note it was the case with APM as well).  For non-generic Task<\/code>-returning methods, the method can just return a singleton already-completed task, and in fact one such singleton is provided by Task<\/code> in the form of Task.CompletedTask<\/code>.  But for Task<TResult><\/code>, it’s impossible to cache a Task<\/code> for every possible TResult<\/code>.  What can we do to make such synchronous completion faster?<\/p>\n
      It is possible to cache some<\/em> Task<TResult><\/code>s.  For example, Task<bool><\/code> is very common, and there’s only two meaningful things to cache there: a Task<bool><\/code> when the Result<\/code> is true<\/code> and one when the Result<\/code> is false<\/code>.  Or while we wouldn’t want to try caching four billion Task<int><\/code>s to accommmodate every possible Int32<\/code> result, small Int32<\/code> values are very common, so we could cache a few for, say, -1 through 8.  Or for arbitrary types, default<\/code> is a reasonably common value, so we could cache a Task<TResult><\/code> where Result<\/code> is default(TResult)<\/code> for every relevant type.  And in fact, Task.FromResult<\/code> does that today<\/a> (as of recent versions of .NET), using a small cache of such reusable Task<TResult><\/code> singletons and returning one of them if appropriate or otherwise allocating a new Task<TResult><\/code> for the exact provided result value.  Other schemes can be created to handle other reasonably common cases.  For example, when working with Stream.ReadAsync<\/code>, it’s reasonably common to call it multiple times on the same stream, all with the same count<\/code> for the number of bytes allowed to be read.  And it’s reasonably common for the implementation to be able to fully satisfy that count<\/code> request.  Which means it’s reasonably common for Stream.ReadAsync<\/code> to repeatedly return the same int<\/code> result value.  To avoid multiple allocations in such scenarios, multiple Stream<\/code> types (like MemoryStream<\/code>) will cache the last Task<int><\/code> they successfully returned, and if the next read ends up also completing synchronously and successfully with the same result, it can just return the same Task<int><\/code> again rather than creating a new one.  But what about other cases?  How can this allocation for synchronous completions be avoided more generally in situations where the performance overhead really matters?<\/p>\n
      That’s where ValueTask<TResult><\/code> comes into the picture (a much more detailed examination of ValueTask<TResult><\/code><\/a> is also available). ValueTask<TResult><\/code> started life as a discriminated union between a TResult<\/code> and a Task<TResult><\/code>.  At the end of the day, ignoring all the bells and whistles, that’s all it is<\/a> (or, rather, was), either an immediate result or a promise for a result at some point in the future:<\/p>\n
      public readonly struct ValueTask<TResult>\r\n{\r\n   private readonly Task<TResult>? _task;\r\n   private readonly TResult _result;\r\n   ...\r\n}<\/code><\/pre>\n
      A method could then return such a ValueTask<TResult><\/code> instead of a Task<TResult><\/code>, and at the expense of a larger return type and a little more indirection, avoid the Task<TResult><\/code> allocation if the TResult<\/code> was known by the time it needed to be returned.<\/p>\n
      There are, however, super duper extreme high-performance scenarios where you want to be able to avoid the Task<TResult><\/code> allocation even in the asynchronous-completion case.  For example, Socket<\/code> lives at the bottom of the networking stack, and SendAsync<\/code> and ReceiveAsync<\/code> on sockets are on the super hot path for many a service, with both synchronous and asynchronous completions being very common (most sends complete synchronously, and many receives complete synchronously due to data having already been buffered in the kernel).  Wouldn’t it be nice if, on a given Socket<\/code>, we could make such sending and receiving allocation-free, regardless of whether the operations complete synchronously or asynchronously?<\/p>\n
      That’s where System.Threading.Tasks.Sources.IValueTaskSource<TResult><\/code> enters the picture:<\/p>\n
      public interface IValueTaskSource<out TResult>\r\n{\r\n    ValueTaskSourceStatus GetStatus(short token);\r\n    void OnCompleted(Action<object?> continuation, object? state, short token, ValueTaskSourceOnCompletedFlags flags);\r\n    TResult GetResult(short token);\r\n}<\/code><\/pre>\n
      The IValueTaskSource<TResult><\/code> interface allows an implementation to provide its own backing object for a ValueTask<TResult><\/code>, enabling the object to implement methods like GetResult<\/code> to retrieve the result of the operation and OnCompleted<\/code> to hook up a continuation to the operation. With that, ValueTask<TResult><\/code> evolved a small change to its definition<\/a>, with its Task<TResult>? _task<\/code> field replaced by an object? _obj<\/code> field:<\/p>\n
      public readonly struct ValueTask<TResult>\r\n{\r\n   private readonly object? _obj;\r\n   private readonly TResult _result;\r\n   ...\r\n}<\/code><\/pre>\n
      Whereas the _task<\/code> field was either a Task<TResult><\/code> or null, the _obj<\/code> field now can also be an IValueTaskSource<TResult><\/code>.  Once a Task<TResult><\/code> is marked as completed, that’s it, it will remain completed and never transition back to an incomplete state. In contrast, an object implementing IValueTaskSource<TResult><\/code> has full control over the implementation, and is free to transition bidirectionally between complete and incomplete states, as ValueTask<TResult><\/code>‘s contract is that a given instance may be consumed only once, thus by construction it shouldn’t observe a post-consumption change in the underlying instance (this is why analysis rules like CA2012<\/a> exist). This then enables types like Socket<\/code> to pool IValueTaskSource<TResult><\/code> instances to use for repeated calls.  Socket<\/code> caches up to two such instances, one for reads and one for writes, since the 99.999% case is to have at most one receive and one send in-flight at the same time.<\/p>\n
      I mentioned ValueTask<TResult><\/code> but not ValueTask<\/code>.  When dealing only with avoiding allocation for synchronous completion, there’s little performance benefit to a non-generic ValueTask<\/code> (representing result-less, void<\/code> operations), since the same condition can be represented with Task.CompletedTask<\/code>.  But once we care about the ability to use a poolable underlying object for avoiding allocation in asynchronous completion case, that then also matters for the non-generic.  Thus, when IValueTaskSource<TResult><\/code> was introduced, so too were IValueTaskSource<\/code> and ValueTask<\/code>.<\/p>\n
      So, we have Task<\/code>, Task<TResult><\/code>, ValueTask<\/code>, and ValueTask<TResult><\/code>.  We’re able to interact with them in various ways, representing arbitrary asynchronous operations and hooking up continuations to handle the completion of those asynchronous operations. And yes, we can do so before<\/em> or after<\/em> the operation completes.<\/p>\n
      But<\/em>… those continuations are still callbacks!<\/p>\n
      We’re still forced into a continuation-passing style for encoding our asynchronous control flow!!<\/p>\n
      It’s still really hard to get right!!!<\/p>\n
      How can we fix that????<\/p>\n
      C# Iterators to the Rescue<\/h2>\n
      The glimmer of hope for that solution actually came about a few years before Task<\/code> hit the scene, with C# 2.0, when it added support for iterators.<\/p>\n
      “Iterators?” you ask? “You mean for IEnumerable<T><\/code>?” That’s the one.  Iterators let you write a single method that is then used by the compiler to implement an IEnumerable<T><\/code> and\/or an IEnumerator<T><\/code>.  For example, if I wanted to create an enumerable that yielded the Fibonacci sequence, I might write something like this:<\/p>\n
      public static IEnumerable<int> Fib()\r\n{\r\n    int prev = 0, next = 1;\r\n    yield return prev;\r\n    yield return next;\r\n\r\n    while (true)\r\n    {\r\n        int sum = prev + next;\r\n        yield return sum;\r\n        prev = next;\r\n        next = sum;\r\n    }\r\n}<\/code><\/pre>\n
      I can then enumerate this with a foreach<\/code>:<\/p>\n
      foreach (int i in Fib())\r\n{\r\n    if (i > 100) break;\r\n    Console.Write($\"{i} \");\r\n}<\/code><\/pre>\n
      I can compose it with other IEnumerable<T><\/code>s via combinators like those on System.Linq.Enumerable<\/code>:<\/p>\n
      foreach (int i in Fib().Take(12))\r\n{\r\n    Console.Write($\"{i} \");\r\n}<\/code><\/pre>\n
      Or I can just manually enumerate it directly via an IEnumerator<T><\/code>:<\/p>\n
      using IEnumerator<int> e = Fib().GetEnumerator();\r\nwhile (e.MoveNext())\r\n{\r\n    int i = e.Current;\r\n    if (i > 100) break;\r\n    Console.Write($\"{i} \");\r\n}<\/code><\/pre>\n
      All of the above result in this output:<\/p>\n
      0 1 1 2 3 5 8 13 21 34 55 89<\/code><\/pre>\n
      The really interesting thing about this is that in order to achieve the above, we need to be able to enter and exit that Fib<\/code> method multiple times.  We call MoveNext<\/code>, it enters the method, the method then executes until it encounters a yield return<\/code>, at which point the call to MoveNext<\/code> needs to return true<\/code> and a subsequent access to Current<\/code> needs to return the yielded value.  Then we call MoveNext<\/code> again, and we need to be able to pick up in Fib<\/code> just after where we last left off, and with all of the state from the previous invocation intact.  Iterators are effectively coroutines provided by the C# language \/ compiler, with the compiler expanding my Fib<\/code> iterator into a full-blown state machine:<\/p>\n
      public static IEnumerable<int> Fib() => new <Fib>d__0(-2);\r\n\r\n[CompilerGenerated]\r\nprivate sealed class <Fib>d__0 : IEnumerable<int>, IEnumerable, IEnumerator<int>, IEnumerator, IDisposable\r\n{\r\n    private int <>1__state;\r\n    private int <>2__current;\r\n    private int <>l__initialThreadId;\r\n    private int <prev>5__2;\r\n    private int <next>5__3;\r\n    private int <sum>5__4;\r\n\r\n    int IEnumerator<int>.Current => <>2__current;\r\n    object IEnumerator.Current => <>2__current;\r\n\r\n    public <Fib>d__0(int <>1__state)\r\n    {\r\n        this.<>1__state = <>1__state;\r\n        <>l__initialThreadId = Environment.CurrentManagedThreadId;\r\n    }\r\n\r\n    private bool MoveNext()\r\n    {\r\n        switch (<>1__state)\r\n        {\r\n            default:\r\n                return false;\r\n            case 0:\r\n                <>1__state = -1;\r\n                <prev>5__2 = 0;\r\n                <next>5__3 = 1;\r\n                <>2__current = <prev>5__2;\r\n                <>1__state = 1;\r\n                return true;\r\n            case 1:\r\n                <>1__state = -1;\r\n                <>2__current = <next>5__3;\r\n                <>1__state = 2;\r\n                return true;\r\n            case 2:\r\n                <>1__state = -1;\r\n                break;\r\n            case 3:\r\n                <>1__state = -1;\r\n                <prev>5__2 = <next>5__3;\r\n                <next>5__3 = <sum>5__4;\r\n                break;\r\n        }\r\n        <sum>5__4 = <prev>5__2 + <next>5__3;\r\n        <>2__current = <sum>5__4;\r\n        <>1__state = 3;\r\n        return true;\r\n    }\r\n\r\n    IEnumerator<int> IEnumerable<int>.GetEnumerator()\r\n    {\r\n        if (<>1__state == -2 &&\r\n            <>l__initialThreadId == Environment.CurrentManagedThreadId)\r\n        {\r\n            <>1__state = 0;\r\n            return this;\r\n        }\r\n        return new <Fib>d__0(0);\r\n    }\r\n\r\n    IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable<int>)this).GetEnumerator();\r\n    void IEnumerator.Reset() => throw new NotSupportedException();\r\n    void IDisposable.Dispose() { }\r\n}<\/code><\/pre>\n
      All of the logic for Fib is now inside of the MoveNext<\/code> method, but as part of a jump table that lets the implementation branch to where it last left off, which is tracked in a generated state field on the enumerator type.  And the variables I wrote as locals, like prev<\/code>, next<\/code>, and sum<\/code>, have been “lifted” to be fields on the enumerator, so that they may persist across invocations of MoveNext<\/code>.<\/p>\n
      (Note that the previous code snippet showing how the C# compiler emits the implementation won’t compile as-is.  The C# compiler synthesizes “unspeakable” names, meaning it names types and members it creates in a way that’s valid IL but invalid C#, so as not to risk conflicting with any user-named types and members.  I’ve kept everything named as the compiler does, but if you want to experiment with compiling it, you can rename things to use valid C# names instead.)<\/p>\n
      In my previous example, the last form of enumeration I showed involved manually using the IEnumerator<T><\/code>. At that level, we’re manually invoking MoveNext()<\/code>, deciding when it was an appropriate time to re-enter the coroutine. But… what if instead of invoking it like that, I could instead have the next invocation of MoveNext<\/code> actually be part of the continuation work performed when an asynchronous operation completes?  What if I could yield return<\/code> something that represents an asynchronous operation and have the consuming code hook up a continuation to that yielded object where that continuation then does the MoveNext<\/code>? With such an approach, I could write a helper method like this:<\/p>\n
      static Task IterateAsync(IEnumerable<Task> tasks)\r\n{\r\n    var tcs = new TaskCompletionSource();\r\n\r\n    IEnumerator<Task> e = tasks.GetEnumerator();\r\n\r\n    void Process()\r\n    {\r\n        try\r\n        {\r\n            if (e.MoveNext())\r\n            {\r\n                e.Current.ContinueWith(t => Process());\r\n                return;\r\n            }\r\n        }\r\n        catch (Exception e)\r\n        {\r\n            tcs.SetException(e);\r\n            return;\r\n        }\r\n        tcs.SetResult();\r\n    };\r\n    Process();\r\n\r\n    return tcs.Task;\r\n}<\/code><\/pre>\n
      Now this is getting interesting.  We’re given an enumerable of tasks that we can iterate through.  Each time we MoveNext<\/code> to the next Task<\/code> and get one, we then hook up a continuation to that Task<\/code>; when that Task<\/code> completes, it’ll just turn around and call right back to the same logic that does a MoveNext<\/code>, gets the next Task<\/code>, and so on.  This is building on the idea of Task<\/code> as a single representation for any asynchronous operation, so the enumerable we’re fed can be a sequence of any asynchronous operations.  Where might such a sequence come from?  From an iterator, of course.  Remember our earlier CopyStreamToStream<\/code> example and how gloriously horrible the APM-based implementation was?  Consider this instead:<\/p>\n
      static Task CopyStreamToStreamAsync(Stream source, Stream destination)\r\n{\r\n    return IterateAsync(Impl(source, destination));\r\n\r\n    static IEnumerable<Task> Impl(Stream source, Stream destination)\r\n    {\r\n        var buffer = new byte[0x1000];\r\n        while (true)\r\n        {\r\n            Task<int> read = source.ReadAsync(buffer, 0, buffer.Length);\r\n            yield return read;\r\n            int numRead = read.Result;\r\n            if (numRead <= 0)\r\n            {\r\n                break;\r\n            }\r\n\r\n            Task write = destination.WriteAsync(buffer, 0, numRead);\r\n            yield return write;\r\n            write.Wait();\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
      Wow, this is almost legible.  We’re calling that IterateAsync<\/code> helper, and the enumerable we’re feeding it is one produced by an iterator that’s handling all the control flow for the copy.  It calls Stream.ReadAsync<\/code> and then yield return<\/code>s that Task<\/code>; that yielded task is what will be handed off to IterateAsync<\/code> after it calls MoveNext<\/code>, and IterateAsync<\/code> will hook a continuation up to that Task<\/code>, which when it completes will then just call back into MoveNext<\/code> and end up back in this iterator just after the yield<\/code>.  At that point, the Impl<\/code> logic gets the result of the method, calls WriteAsync<\/code>, and again yields the Task<\/code> it produced.  And so on.<\/p>\n
      And that, my friends, is the beginning of async<\/code>\/await<\/code> in C# and .NET. Something around 95% of the logic in support of iterators and async<\/code>\/await<\/code> in the C# compiler is shared.  Different syntax, different types involved, but fundamentally the same transform. Squint at the yield return<\/code>s, and you can almost see await<\/code>s in their stead.<\/p>\n
      In fact, some enterprising developers  used iterators in this fashion for asynchronous programming<\/a> before async<\/code>\/await<\/code> hit the scene. And a similar transformation was prototyped in the experimental Axum<\/a> programming language, serving as a key inspiration for C#’s async support. Axum provided an async<\/code> keyword that could be put onto a method, just like async<\/code> can now in C#. Task<\/code> wasn’t yet ubiquitous, so inside of async<\/code> methods, the Axum compiler heuristically matched synchronous method calls to their APM counterparts, e.g. if it saw you calling stream.Read<\/code>, it would find and utilize the corresponding stream.BeginRead<\/code> and stream.EndRead<\/code> methods, synthesizing the appropriate delegate to pass to the Begin method, while also generating a complete APM implementation for the async<\/code> method being defined such that it was compositional. It even integrated with SynchronizationContext<\/code>! While Axum was eventually shelved, it served as an awesome and motivating prototype for what eventually became async<\/code>\/await<\/code> in C#.<\/p>\n
      async<\/code>\/await<\/code> under the covers<\/h2>\n
      Now that we know how we got here, let’s dive in to how it actually works.  For reference, here’s our example synchronous method again:<\/p>\n
      public void CopyStreamToStream(Stream source, Stream destination)\r\n{\r\n    var buffer = new byte[0x1000];\r\n    int numRead;\r\n    while ((numRead = source.Read(buffer, 0, buffer.Length)) != 0)\r\n    {\r\n        destination.Write(buffer, 0, numRead);\r\n    }\r\n}<\/code><\/pre>\n
      and again here’s what the corresponding method looks like with async<\/code>\/await<\/code>:<\/p>\n
      public async Task CopyStreamToStreamAsync(Stream source, Stream destination)\r\n{\r\n    var buffer = new byte[0x1000];\r\n    int numRead;\r\n    while ((numRead = await source.ReadAsync(buffer, 0, buffer.Length)) != 0)\r\n    {\r\n        await destination.WriteAsync(buffer, 0, numRead);\r\n    }\r\n}<\/code><\/pre>\n
      A breadth of fresh air in comparison to everything we’ve seen thus far. The signature changed from void<\/code> to async Task<\/code>, we call ReadAsync<\/code> and WriteAsync<\/code> instead of Read<\/code> and Write<\/code>, respectively, and both of those operations are prefixed with await<\/code>.  That’s it.  The compiler and the core libraries take over the rest, fundamentally changing how the code is actually executed.  Let’s dive into how.<\/p>\n
      Compiler Transform<\/h3>\n
      As we’ve already seen, as with iterators, the compiler rewrites the async method into one based on a state machine.  We still have a method with the same signature the developer wrote (public Task CopyStreamToStreamAsync(Stream source, Stream destination)<\/code>), but the body of that method is completely different:<\/p>\n
      [AsyncStateMachine(typeof(<CopyStreamToStreamAsync>d__0))]\r\npublic Task CopyStreamToStreamAsync(Stream source, Stream destination)\r\n{\r\n    <CopyStreamToStreamAsync>d__0 stateMachine = default;\r\n    stateMachine.<>t__builder = AsyncTaskMethodBuilder.Create();\r\n    stateMachine.source = source;\r\n    stateMachine.destination = destination;\r\n    stateMachine.<>1__state = -1;\r\n    stateMachine.<>t__builder.Start(ref stateMachine);\r\n    return stateMachine.<>t__builder.Task;\r\n}\r\n\r\nprivate struct <CopyStreamToStreamAsync>d__0 : IAsyncStateMachine\r\n{\r\n    public int <>1__state;\r\n    public AsyncTaskMethodBuilder <>t__builder;\r\n    public Stream source;\r\n    public Stream destination;\r\n    private byte[] <buffer>5__2;\r\n    private TaskAwaiter <>u__1;\r\n    private TaskAwaiter<int> <>u__2;\r\n\r\n    ...\r\n}<\/code><\/pre>\n
      Note that the only signature difference from what the dev wrote is the lack of the async<\/code> keyword itself.  async<\/code> isn’t actually a part of the method signature; like unsafe<\/code>, when you put it in the method signature, you’re expressing an implementation detail of the method rather than something that’s actually exposed as part of the contract.  Using async<\/code>\/await<\/code> to implement a Task<\/code>-returning method is an implementation detail.<\/p>\n
      The compiler has generated a struct named <CopyStreamToStreamAsync>d__0<\/code>, and it’s zero-initialized an instance of that struct on the stack. Importantly, if the async method completes synchronously, this state machine will never have left the stack.  That means there’s no allocation associated with the state machine unless<\/em> the method needs to complete asynchronously, meaning it await<\/code>s something that’s not yet completed by that point.  More on that in a bit.<\/p>\n
      This struct is<\/em> the state machine for the method, containing not only all of the transformed logic from what the developer wrote, but also fields for tracking the current position in that method as well as all of the “local” state the compiler lifted out of the method that needs to survive between MoveNext<\/code> invocations.  It’s the logical equivalent of the IEnumerable<T><\/code>\/IEnumerator<T><\/code> implementation we saw in the iterator. (Note that the code I’m showing is from a release build; in debug builds the C# compiler will actually generate these state machine types as classes, as doing so can aid in certain debugging exercises).<\/p>\n
      After initializing the state machine, we see a call to AsyncTaskMethodBuilder.Create()<\/code><\/a>.  While we’re currently focused on Task<\/code>s, the C# language and compiler allow for arbitrary types (“task-like” types<\/a>) to be returned from async<\/code> methods, e.g. I can write a method public async MyTask CopyStreamToStreamAsync<\/code>, and it would compile just fine as long as we augment the MyTask<\/code> we defined earlier in an appropriate way. That appropriateness includes declaring an associated “builder” type and associating it with the type via the AsyncMethodBuilder<\/code> attribute:<\/p>\n
      [AsyncMethodBuilder(typeof(MyTaskMethodBuilder))]\r\npublic class MyTask\r\n{\r\n    ...\r\n}\r\n\r\npublic struct MyTaskMethodBuilder\r\n{\r\n    public static MyTaskMethodBuilder Create() { ... }\r\n\r\n    public void Start<TStateMachine>(ref TStateMachine stateMachine) where TStateMachine : IAsyncStateMachine { ... }\r\n    public void SetStateMachine(IAsyncStateMachine stateMachine) { ... }\r\n\r\n    public void SetResult() { ... }\r\n    public void SetException(Exception exception) { ... }\r\n\r\n    public void AwaitOnCompleted<TAwaiter, TStateMachine>(\r\n        ref TAwaiter awaiter, ref TStateMachine stateMachine)\r\n        where TAwaiter : INotifyCompletion\r\n        where TStateMachine : IAsyncStateMachine { ... }\r\n    public void AwaitUnsafeOnCompleted<TAwaiter, TStateMachine>(\r\n        ref TAwaiter awaiter, ref TStateMachine stateMachine)\r\n        where TAwaiter : ICriticalNotifyCompletion\r\n        where TStateMachine : IAsyncStateMachine { ... }\r\n\r\n    public MyTask Task { get { ... } }\r\n}<\/code><\/pre>\n
      In this context, such a “builder” is something that knows how to create an instance of that type (the Task<\/code> property), complete it either successfully and with a result if appropriate (SetResult<\/code>) or with an exception (SetException<\/code>), and handle hooking up continuations to await<\/code>ed things that haven’t yet completed (AwaitOnCompleted<\/code>\/AwaitUnsafeOnCompleted<\/code>).  In the case of System.Threading.Tasks.Task<\/code>, it is by default associated with the AsyncTaskMethodBuilder<\/code>.  Normally that association is provided via an [AsyncMethodBuilder(...)]<\/code> attribute applied to the type, but Task<\/code> is known specially to C# and so isn’t actually adorned with that attribute.  As such, the compiler has reached for the builder to use for this async<\/code> method, and is constructing an instance of it using the Create<\/code> method that’s part of the pattern.  Note that as with the state machine, AsyncTaskMethodBuilder<\/code> is also a struct, so there’s no allocation here, either.<\/p>\n
      The state machine is then populated with the arguments to this entry point method.  Those parameters need to be available to the body of the method that’s been moved into MoveNext<\/code>, and as such these arguments need to be stored in the state machine so that they can be referenced by the code on the subsequent call to MoveNext<\/code>.  The state machine is also initialized to be in the initial -1<\/code> state.  If MoveNext<\/code> is called and the state is -1<\/code>, we’ll end up starting logically at the beginning of the method.<\/p>\n
      Now the most unassuming but most consequential line: a call to the builder’s Start<\/code><\/a> method.  This is another part of the pattern that must be exposed on a type used in the return position of an async<\/code> method, and it’s used to perform the initial MoveNext<\/code> on the state machine.  The builder’s Start method is effectively just this:<\/p>\n
      public void Start<TStateMachine>(ref TStateMachine stateMachine) where TStateMachine : IAsyncStateMachine\r\n{\r\n    stateMachine.MoveNext();\r\n}<\/code><\/pre>\n
      such that calling stateMachine.<>t__builder.Start(ref stateMachine);<\/code> is really just calling stateMachine.MoveNext()<\/code>.  In which case, why doesn’t the compiler just emit that directly? Why have Start<\/code> at all?  The answer is that there’s a tad bit more to Start<\/code> than I let on.  But for that, we need to take a brief detour into understanding ExecutionContext<\/code>.<\/p>\n
      ExecutionContext<\/h4>\n
      We’re all familiar with passing around state from method to method.  You call a method, and if that method specifies parameters, you call the method with arguments in order to feed that data into the callee.  This is explicitly passing around data.  But there are other more implicit means.  For example, rather than passing data as arguments, a method could be parameterless but could dictate that some specific static fields may be populated prior to making the method call, and the method will pull state from there.  Nothing about the method’s signature indicates it takes arguments, because it doesn’t: there’s just an implicit contract between the caller and callee that the caller might populate some memory locations and the callee might read those memory locations.  The callee and the caller may not even realize it’s happening if they’re intermediaries, e.g. method A<\/code> might populate the statics and then call B<\/code> which calls C<\/code> which calls D<\/code> which eventually calls E<\/code> that reads the values of those statics. This is often referred to as “ambient” data: it’s not passed to you via parameters but rather is just sort of hanging out there and available for you to consume if desired.<\/p>\n
      We can take this a step further, and use thread-local state. Thread-local state, which in .NET is achieved via static fields attributed as [ThreadStatic]<\/code> or via the ThreadLocal<T><\/code> type, can be used in the same way, but with the data limited to just the current thread of execution, with every thread able to have its own isolated copy of those fields.  With that, you could populate the thread static, make the method call, and then upon the method’s completion revert the changes to the thread static, enabling a fully isolated form of such implicitly passed data.<\/p>\n
      But, what about asynchrony? If we make an asynchronous method call and logic inside that asynchronous method wants to access that ambient data, how would it do so?  If the data were stored in regular statics, the asynchronous method would be able to access it, but you could only ever have one such method in flight at a time, as multiple callers could end up overwriting each others’ state when they write to those shared static fields.  If the data were stored in thread statics, the asynchronous method would be able to access it, but only up until the point where it stopped running synchronously on the calling thread; if it hooked up a continuation to some operation it initiated and that continuation ended up running on some other thread, it would no longer have access to the thread static information.  Even if it did happen to run on the same thread, either by chance or because the scheduler forced it to, by the time it did it’s likely the data would have been removed and\/or overwritten by some other operation initiated by that thread.  For asynchrony, what we need is a mechanism that would allow arbitrary ambient data to flow across these asynchronous points, such that throughout an async method’s logic, wherever and whenever that logic might run, it would have access to that same data.<\/p>\n
      Enter ExecutionContext<\/code>.  The ExecutionContext<\/code> type is the vehicle by which ambient data flows from async operation to async operation.  It lives in a [ThreadStatic]<\/code>, but then when some asynchronous operation is initiated, it’s “captured” (a fancy way of saying “read a copy from that thread static”), stored, and then when the continuation of that asynchronous operation is run, the ExecutionContext<\/code> is first restored to live in the [ThreadStatic]<\/code> on the thread which is about to run the operation.  ExecutionContext<\/code> is the mechanism by which AsyncLocal<T><\/code> is implemented (in fact, in .NET Core, ExecutionContext<\/code> is entirely about AsyncLocal<T><\/code>, nothing more), such that if you store a value into an AsyncLocal<T><\/code>, and then for example queue a work item to run on the ThreadPool<\/code>, that value will be visible in that AsyncLocal<T><\/code> inside of that work item running on the pool:<\/p>\n
      var number = new AsyncLocal<int>();\r\n\r\nnumber.Value = 42;\r\nThreadPool.QueueUserWorkItem(_ => Console.WriteLine(number.Value));\r\nnumber.Value = 0;\r\n\r\nConsole.ReadLine();<\/code><\/pre>\n
      That will print 42<\/code> every time this is run.  It doesn’t matter that the moment after we queue the delegate we reset the value of the AsyncLocal<int><\/code> back to 0, because the ExecutionContext<\/code> was captured as part of the QueueUserWorkItem<\/code> call, and that capture included the state of the AsyncLocal<int><\/code> at that exact moment.  We can see this in more detail by implementing our own simple thread pool:<\/p>\n
      using System.Collections.Concurrent;\r\n\r\nvar number = new AsyncLocal<int>();\r\n\r\nnumber.Value = 42;\r\nMyThreadPool.QueueUserWorkItem(() => Console.WriteLine(number.Value));\r\nnumber.Value = 0;\r\n\r\nConsole.ReadLine();\r\n\r\nclass MyThreadPool\r\n{\r\n    private static readonly BlockingCollection<(Action, ExecutionContext?)> s_workItems = new();\r\n\r\n    public static void QueueUserWorkItem(Action workItem)\r\n    {\r\n        s_workItems.Add((workItem, ExecutionContext.Capture()));\r\n    }\r\n\r\n    static MyThreadPool()\r\n    {\r\n        for (int i = 0; i < Environment.ProcessorCount; i++)\r\n        {\r\n            new Thread(() =>\r\n            {\r\n                while (true)\r\n                {\r\n                    (Action action, ExecutionContext? ec) = s_workItems.Take();\r\n                    if (ec is null)\r\n                    {\r\n                        action();\r\n                    }\r\n                    else\r\n                    {\r\n                        ExecutionContext.Run(ec, s => ((Action)s!)(), action);\r\n                    }\r\n                }\r\n            })\r\n            { IsBackground = true }.UnsafeStart();\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
      Here MyThreadPool<\/code> has a BlockingCollection<(Action, ExecutionContext?)><\/code> that represents its work item queue, with each work item being the delegate for the work to be invoked as well as the ExecutionContext<\/code> associated with that work.  The static constructor for the pool spins up a bunch of threads, each of which just sits in an infinite loop taking the next work item and running it.  If no ExecutionContext<\/code> was captured for a given delegate, the delegate is just invoked directly.  But if an ExecutionContext<\/code> was captured, rather than invoking the delegate directly, we call the ExecutionContext.Run<\/code> method, which will restore the supplied ExecutionContext<\/code> as the current context prior to running the delegate, and will then reset the context afterwards.  This example includes the exact same code with an AsyncLocal<int><\/code> previously shown, except this time using MyThreadPool<\/code> instead of ThreadPool<\/code>, yet it will still output 42<\/code> each time, because the pool is properly flowing ExecutionContext<\/code>.<\/p>\n
      As an aside, you’ll note I called UnsafeStart<\/code> in MyThreadPool<\/code>‘s static constructor. Starting a new thread is exactly the kind of asynchronous point that should flow ExecutionContext<\/code>, and indeed, Thread<\/code>‘s Start<\/code> method uses ExecutionContext.Capture<\/code> to capture the current context, store it on the Thread<\/code>, and then use that captured context when eventually invoking the Thread<\/code>‘s ThreadStart<\/code> delegate.  I didn’t want to do that in this example, though, as I didn’t want the Thread<\/code>s to capture whatever ExecutionContext<\/code> happened to be present when the static constructor ran (doing so could make a demo about ExecutionContext<\/code> more convoluted), so I used the UnsafeStart<\/code> method instead.  Threading-related methods that begin with Unsafe<\/code> behave exactly the same as the corresponding method that lacks the Unsafe<\/code> prefix except that they don’t<\/em> capture ExecutionContext<\/code>, e.g. Thread.Start<\/code> and Thread.UnsafeStart<\/code> do identical work, but whereas Start<\/code> captures ExecutionContext<\/code>, UnsafeStart<\/code> does not.<\/p>\n
      Back To Start<\/h4>\n
      We took a detour into discussing ExecutionContext<\/code> when I was writing about the implementation of AsyncTaskMethodBuilder.Start<\/code>, which I said was effectively:<\/p>\n
      public void Start<TStateMachine>(ref TStateMachine stateMachine) where TStateMachine : IAsyncStateMachine\r\n{\r\n    stateMachine.MoveNext();\r\n}<\/code><\/pre>\n
      and then suggested I simplified a bit.  That simplification was ignoring the fact that the method actually needs to factor ExecutionContext<\/code> into things, and is thus more like this:<\/p>\n
      public void Start<TStateMachine>(ref TStateMachine stateMachine) where TStateMachine : IAsyncStateMachine\r\n{\r\n    ExecutionContext previous = Thread.CurrentThread._executionContext; \/\/ [ThreadStatic] field\r\n    try\r\n    {\r\n        stateMachine.MoveNext();\r\n    }\r\n    finally\r\n    {\r\n        ExecutionContext.Restore(previous); \/\/ internal helper\r\n    }\r\n}<\/code><\/pre>\n
      Rather than just calling stateMachine.MoveNext()<\/code> as I’d previously suggested we did, we do a dance here of getting the current ExecutionContext<\/code>, then invoking MoveNext<\/code>, and then upon its completion resetting the current context back to what it was prior to the MoveNext<\/code> invocation.<\/p>\n
      The reason for this is to prevent ambient data leakage from an async method out to its caller.  An example method demonstrates why that matters:<\/p>\n
      async Task ElevateAsAdminAndRunAsync()\r\n{\r\n    using (WindowsIdentity identity = LoginAdmin())\r\n    {\r\n        using (WindowsImpersonationContext impersonatedUser = identity.Impersonate())\r\n        {\r\n            await DoSensitiveWorkAsync();\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
      “Impersonation” is the act of changing ambient information about the current user to instead be that of someone else; this lets code act on behalf of someone else, using their privileges and access. In .NET, such impersonation flows across asynchronous operations, which means it’s part of ExecutionContext<\/code>.  Now imagine if Start<\/code> didn’t restore the previous context, and consider this code:<\/p>\n
      Task t = ElevateAsAdminAndRunAsync();\r\nPrintUser();\r\nawait t;<\/code><\/pre>\n
      This code could find that the ExecutionContext<\/code> modified inside of ElevateAsAdminAndRunAsync<\/code> remains after ElevateAsAdminAndRunAsync<\/code> returns to its synchronous caller (which happens the first time the method await<\/code>s something that’s not yet complete).  That’s because after calling Impersonate<\/code>, we call DoSensitiveWorkAsync<\/code> and await<\/code> the task it returns.  Assuming that task isn’t complete, it will cause the invocation of ElevateAsAdminAndRunAsync<\/code> to yield and return to the caller, with the impersonation still in effect on the current thread. That is not something we want.  As such, Start<\/code> erects this guard that ensures any modifications to ExecutionContext<\/code> don’t flow out<\/em> of the synchronous method call and only flow along with any subsequent work performed by the method.<\/p>\n
      MoveNext<\/h4>\n
      So, the entry point method was invoked, the state machine struct was initialized, Start<\/code> was called, and that invoked MoveNext<\/code>.  What is MoveNext<\/code>?  It’s the method that contains all of the original logic from the dev’s method, but with a whole bunch of changes.  Let’s start just by looking at the scaffolding of the method. Here’s a decompiled version of what the compiler emit for our method, but with everything inside of the generated try<\/code> block removed:<\/p>\n
      private void MoveNext()\r\n{\r\n    try\r\n    {\r\n        ... \/\/ all of the code from the CopyStreamToStreamAsync method body, but not exactly as it was written\r\n    }\r\n    catch (Exception exception)\r\n    {\r\n        <>1__state = -2;\r\n        <buffer>5__2 = null;\r\n        <>t__builder.SetException(exception);\r\n        return;\r\n    }\r\n\r\n    <>1__state = -2;\r\n    <buffer>5__2 = null;\r\n    <>t__builder.SetResult();\r\n}<\/code><\/pre>\n
      Whatever other work is performed by MoveNext<\/code>, it has the responsibility of completing the Task<\/code> returned from the async Task<\/code> method when all of the work is done.  If the body of the try<\/code> block throws an exception that goes unhandled, then the task will be faulted with that exception.  And if the async method successfully reaches its end (equivalent to a synchronous method returning), it will complete the returned task successfully.  In either of those cases, it’s setting the state of the state machine to indicate completion. (I sometimes hear developers theorize that, when it comes to exceptions, there’s a difference between those thrown before the first await<\/code> and after… based on the above, it should be clear that is not<\/em> the case.  Any exception that goes unhandled inside of an async<\/code> method, no matter where it is in the method and no matter whether the method has yielded, will end up in the above catch<\/code> block, with the caught exception then stored into the Task<\/code> that’s returned from the async<\/code> method.)<\/p>\n
      Also note that this completion is going through the builder, using its SetException<\/code> and SetResult<\/code> methods that are part of the pattern for a builder expected by the compiler.  If the async method has previously suspended, the builder will have already had to manufacture a Task<\/code> as part of that suspension handling (we’ll see how and where soon), in which case calling SetException<\/code>\/SetResult<\/code> will complete that Task<\/code>.  If, however, the async method hasn’t previously suspended, then we haven’t yet created a Task<\/code> or returned anything to the caller, so the builder has more flexibility in how it produces that Task<\/code>.  If you remember previously in the entry point method, the very last thing it does is return the Task<\/code> to the caller, which it does by returning the result of accessing the builder’s Task<\/code> property (so many things called “Task”, I know):<\/p>\n
      public Task CopyStreamToStreamAsync(Stream source, Stream destination)\r\n{\r\n    ...\r\n    return stateMachine.<>t__builder.Task;\r\n}<\/code><\/pre>\n
      The builder knows if the method ever suspended, in which case it has a Task<\/code> that was already created and just returns that.  If the method never suspended and the builder doesn’t yet have a task, it can manufacture a completed task here. In this case, with a successful completion, it can just use Task.CompletedTask<\/code> rather than allocating a new task, avoiding any allocation. In the case of a generic Task<TResult><\/code>, the builder can just use Task.FromResult<TResult>(TResult result)<\/code>.<\/p>\n
      The builder can also do whatever translations it deems are appropriate to the kind of object it’s creating.  For example, Task<\/code> actually has three possible final states: success, failure, and canceled. The AsyncTaskMethodBuilder<\/code>‘s SetException<\/code> method special-cases OperationCanceledException<\/code><\/a>, transitioning the Task<\/code> into a TaskStatus.Canceled<\/code> final state if the exception provided is or derives from OperationCanceledException<\/code>; otherwise, the task ends as TaskStatus.Faulted<\/code>.  Such a distinction often isn’t apparent in consuming code; since the exception is stored into the Task<\/code> regardless of whether it’s marked as Canceled<\/code> or Faulted<\/code>, code await<\/code>‘ing that Task<\/code> will not be able to observe the difference between the states (the original exception will be propagated in either case)… it only affects code that interacts with the Task<\/code> directly, such as via ContinueWith<\/code>, which has overloads that enable a continuation to be invoked only for a subset of completion statuses.<\/p>\n
      Now that we understand the lifecycle aspects, here’s everything filled in inside the try<\/code> block in MoveNext<\/code>:<\/p>\n
      private void MoveNext()\r\n{\r\n    try\r\n    {\r\n        int num = <>1__state;\r\n\r\n        TaskAwaiter<int> awaiter;\r\n        if (num != 0)\r\n        {\r\n            if (num != 1)\r\n            {\r\n                <buffer>5__2 = new byte[4096];\r\n                goto IL_008b;\r\n            }\r\n\r\n            awaiter = <>u__2;\r\n            <>u__2 = default(TaskAwaiter<int>);\r\n            num = (<>1__state = -1);\r\n            goto IL_00f0;\r\n        }\r\n\r\n        TaskAwaiter awaiter2 = <>u__1;\r\n        <>u__1 = default(TaskAwaiter);\r\n        num = (<>1__state = -1);\r\n        IL_0084:\r\n        awaiter2.GetResult();\r\n\r\n        IL_008b:\r\n        awaiter = source.ReadAsync(<buffer>5__2, 0, <buffer>5__2.Length).GetAwaiter();\r\n        if (!awaiter.IsCompleted)\r\n        {\r\n            num = (<>1__state = 1);\r\n            <>u__2 = awaiter;\r\n            <>t__builder.AwaitUnsafeOnCompleted(ref awaiter, ref this);\r\n            return;\r\n        }\r\n        IL_00f0:\r\n        int result;\r\n        if ((result = awaiter.GetResult()) != 0)\r\n        {\r\n            awaiter2 = destination.WriteAsync(<buffer>5__2, 0, result).GetAwaiter();\r\n            if (!awaiter2.IsCompleted)\r\n            {\r\n                num = (<>1__state = 0);\r\n                <>u__1 = awaiter2;\r\n                <>t__builder.AwaitUnsafeOnCompleted(ref awaiter2, ref this);\r\n                return;\r\n            }\r\n            goto IL_0084;\r\n        }\r\n    }\r\n    catch (Exception exception)\r\n    {\r\n        <>1__state = -2;\r\n        <buffer>5__2 = null;\r\n        <>t__builder.SetException(exception);\r\n        return;\r\n    }\r\n\r\n    <>1__state = -2;\r\n    <buffer>5__2 = null;\r\n    <>t__builder.SetResult();\r\n}<\/code><\/pre>\n
      This kind of complication might feel a tad familiar.  Remember how convoluted our manually-implemented BeginCopyStreamToStream<\/code> based on APM was?  This isn’t quite as complicated, but is also way better in that the compiler is doing the work for us, having rewritten the method in a form of continuation passing while ensuring that all necessary state is preserved for those continuations.  Even so, we can squint and follow along.  Remember that the state was initialized to -1 in the entry point.  We then enter MoveNext<\/code>, find that this state (which is now stored in the num<\/code> local) is neither 0 nor 1, and thus execute the code that creates the temporary buffer and then branches to label IL_008b, where it makes the call to stream.ReadAsync<\/code>.  Note that at this point we’re still running synchronously from this call to MoveNext<\/code>, and thus synchronously from Start<\/code>, and thus synchronously from the entry point, meaning the developer’s code called CopyStreamToStreamAsync<\/code> and it’s still synchronously executing, having not yet returned back a Task<\/code> to represent the eventual completion of this method. That might be about to change…<\/p>\n
      We call Stream.ReadAsync<\/code> and we get back a Task<int><\/code> from it.  The read may have completed synchronously, it may have completed asynchronously but so fast that it’s now already completed, or it might not have completed yet.  Regardless, we have a Task<int><\/code> that represents its eventual completion, and the compiler emits code that inspects that Task<int><\/code> to determine how to proceed: if the Task<int><\/code> has in fact already completed (doesn’t matter whether it was completed synchronously or just by the time we checked), then the code for this method can just continue running synchronously… no point in spending unnecessary overhead queueing a work item to handle the remainder of the method’s execution when we can instead just keep running here and now.  But to handle the case where the Task<int><\/code> hasn’t completed, the compiler needs to emit code to hook up a continuation to the Task<\/code>.  It thus needs to emit code that asks the Task<\/code> “are you done?”  Does it talk to the Task<\/code> directly to ask that?<\/p>\n
      It would be limiting if the only thing you could await<\/code> in C# was a System.Threading.Tasks.Task<\/code>.  Similarly, it would be limiting if the C# compiler had to know about every possible type that could be await<\/code>ed.  Instead, C# does what it typically does in cases like this: it employs a pattern of APIs. Code can await<\/code> anything that exposes that appropriate pattern, the “awaiter” pattern (just as you can foreach<\/code> anything that provides the proper “enumerable” pattern).  For example, we can augment the MyTask<\/code> type we wrote earlier to implement the awaiter pattern:<\/p>\n
      class MyTask\r\n{\r\n    ...\r\n    public MyTaskAwaiter GetAwaiter() => new MyTaskAwaiter { _task = this };\r\n\r\n    public struct MyTaskAwaiter : ICriticalNotifyCompletion\r\n    {\r\n        internal MyTask _task;\r\n\r\n        public bool IsCompleted => _task._completed;\r\n        public void OnCompleted(Action continuation) => _task.ContinueWith(_ => continuation());\r\n        public void UnsafeOnCompleted(Action continuation) => _task.ContinueWith(_ => continuation());\r\n        public void GetResult() => _task.Wait();\r\n    }\r\n}<\/code><\/pre>\n
      A type can be awaited if it exposes a GetAwaiter()<\/code> method, which Task<\/code> does.  That method needs to return something that in turn exposes several members, including an IsCompleted<\/code> property, which is used to check at the moment IsCompleted<\/code> is called whether the operation has already completed.  And you can see that happening: at IL_008b, the Task<\/code> returned from ReadAsync<\/code> has GetAwaiter<\/code> called on it, and then IsCompleted<\/code> accessed on that struct awaiter instance.  If IsCompleted<\/code> returns true<\/code>, then we’ll end up falling through to IL_00f0, where the code calls another member of the awaiter: GetResult()<\/code>.  If the operation failed, GetResult()<\/code> is responsible for throwing an exception in order to propagate it out of the await<\/code> in the async method; otherwise, GetResult()<\/code> is responsible for returning the result of the operation, if there is one.  In the case here of the ReadAsync<\/code>, if that result is 0, then we break out of our read\/write loop, go to the end of the method where it calls SetResult<\/code>, and we’re done.<\/p>\n
      Backing up a moment, though, the really interesting part of all of this is what happens if that IsCompleted<\/code> check actually returns false<\/code>.  If it returns true<\/code>, we just keep on processing the loop, akin to in the APM pattern when CompletedSynchronously<\/code> returned true and the caller of the Begin method, rather than the callback, was responsible for continuing execution. But if IsCompleted<\/code> returns false, we need to suspend the execution of the async method until the await<\/code>‘d operation completes.  That means returning out of MoveNext<\/code>, and as this was part of Start<\/code> and we’re still in the entry point method, that means returning the Task<\/code> out to the caller.  But before any of that can happen, we need to hook up a continuation to the Task<\/code> being awaited (noting that to avoid stack dives as in the APM case, if the asynchronous operation completes after IsCompleted<\/code> returns false but before we get to hook up the continuation, the continuation still needs to be invoked asynchronously from the calling thread, and thus it’ll get queued).  Since we can await<\/code> anything, we can’t just talk to the Task<\/code> instance directly; instead, we need to go through some pattern-based method to perform this.<\/p>\n
      Does that mean there’s a method on the awaiter that will hook up the continuation?  That would make sense; after all, Task<\/code> itself supports continuations, has a ContinueWith<\/code> method, etc… shouldn’t it be the TaskAwaiter<\/code> returned from GetAwaiter<\/code> that exposes the method that lets us set up a continuation?  It does, in fact.  The awaiter pattern requires that the awaiter implement the INotifyCompletion<\/code> interface, which contains a single method void OnCompleted(Action continuation)<\/code>.  An awaiter can also optionally implement the ICriticalNotifyCompletion<\/code> interface, which inherits INotifyCompletion<\/code> and adds a void UnsafeOnCompleted(Action continuation)<\/code> method.  Per our previous discussion of ExecutionContext<\/code>, you can guess what the difference between these two methods is: both hook up the continuation, but whereas OnCompleted<\/code> should flow ExecutionContext<\/code>, UnsafeOnCompleted<\/code> needn’t. The need for two distinct methods here, INotifyCompletion.OnCompleted<\/code> and ICriticalNotifyCompletion.UnsafeOnCompleted<\/code>, is largely historical, having to do with Code Access Security, or CAS.  CAS no longer exists in .NET Core, and it’s off by default in .NET Framework, having teeth only if you opt back in to the legacy partial trust feature.  When partial trust is used, CAS information flows as part of ExecutionContext<\/code>, and thus not flowing it is “unsafe”, hence why methods that don’t flow ExecutionContext<\/code> were prefixed with “Unsafe”.  Such methods were also attributed as [SecurityCritical]<\/code>, and partially trusted code can’t call a [SecurityCritical]<\/code> method.  As a result, two variants of OnCompleted<\/code> were created, with the compiler preferring to use UnsafeOnCompleted<\/code> if provided, but with the OnCompleted<\/code> variant always provided on its own in case an awaiter needed to support partial trust.  From an async method perspective, however, the builder always flows ExecutionContext<\/code> across await points, so an awaiter that also does so is unnecessary and duplicative work.<\/p>\n
      Ok, so the awaiter does expose a method to hook up the continuation.  The compiler could<\/em> use it directly, except for a very critical piece of the puzzle: what exactly should the continuation be?  And more to the point, with what object should it be associated? Remember that the state machine struct is on the stack, and the MoveNext<\/code> invocation we’re currently running in is a method call on that instance. We need to preserve the state machine so that upon resumption we have all the correct state, which means the state machine can’t just keep living on the stack; it needs to be copied to somewhere on the heap, since the stack is going to end up being used for other subsequent, unrelated work performed by this thread.  And then the continuation needs to invoke the MoveNext<\/code> method on that copy of the state machine on the heap.<\/p>\n
      Moreover, ExecutionContext<\/code> is relevant here as well.  The state machine needs to ensure that any ambient data stored in the ExecutionContext<\/code> is captured at the point of suspension and then applied at the point of resumption, which means the continuation also needs to incorporate that ExecutionContext<\/code>.  So, just creating a delegate that points to MoveNext<\/code> on the state machine is insufficient.  It’s also undesirable overhead.  If when we suspend we create a delegate that points to MoveNext<\/code> on the state machine, each time we do so we’ll be boxing the state machine struct (even when it’s already on the heap as part of some other object) and allocating an additional delegate (the delegate’s this<\/code> object reference will be to a newly boxed copy of the struct).  We thus need to do a complicated dance whereby we ensure we only promote the struct from the stack to the heap the first time the method suspends execution but all other times uses the same heap object as the target of the MoveNext<\/code>, and in the process ensures we’ve captured the right context, and upon resumption ensures we’re using that captured context to invoke the operation.<\/p>\n
      That’s a lot more logic than we want the compiler to emit… we instead want it encapsulated in a helper, for several reasons. First, it’s a lot of complicated code to be emitted into each user’s assembly. Second, we want to allow customization of that logic as part of implementing the builder pattern (we’ll see an example of why later when talking about pooling).  And third, we want to be able to evolve and improve that logic and have existing previously-compiled binaries just get better.  That’s not a hypothetical; the library code for this support was completely overhauled in .NET Core 2.1, such that the operation is much more efficient than it was on .NET Framework.  We’ll start by exploring exactly how this worked on .NET Framework, and then look at what happens now in .NET Core.<\/p>\n
      You can see in the code generated by the C# compiler happens when we need to suspend:<\/p>\n
      if (!awaiter.IsCompleted) \/\/ we need to suspend when IsCompleted is false\r\n{\r\n    <>1__state = 1;\r\n    <>u__2 = awaiter;\r\n    <>t__builder.AwaitUnsafeOnCompleted(ref awaiter, ref this);\r\n    return;\r\n}<\/code><\/pre>\n
      We’re storing into the state field the state id that indicates the location we should jump to when the method resumes.  We’re then persisting the awaiter itself into a field, so that it can be used to call GetResult<\/code> after resumption.  And then just before returning out of the MoveNext<\/code> call, the very last thing we do is call <>t__builder.AwaitUnsafeOnCompleted(ref awaiter, ref this)<\/code>, asking the builder to hook up a continuation to the awaiter for this state machine. (Note that it calls the builder’s AwaitUnsafeOnCompleted<\/code> rather than the builder’s AwaitOnCompleted<\/code> because the awaiter implements ICriticalNotifyCompletion<\/code>; the state machine handles flowing ExecutionContext<\/code> so we needn’t require the awaiter to as well… as mentioned earlier, doing so would just be duplicative and unnecessary overhead.)<\/p>\n
      The implementation of that AwaitUnsafeOnCompleted<\/code> method is too complicated to copy here, so I’ll summarize what it does<\/a> on .NET Framework:<\/p>\n
        \n
      1. \n
        It uses ExecutionContext.Capture()<\/code> to grab the current context.<\/p>\n<\/li>\n
      2. \n
        It then allocates a MoveNextRunner<\/code> object to wrap both the captured context as well as the boxed state machine (which we don’t yet have if this is the first time the method suspends, so we just use null<\/code> as a placeholder).<\/p>\n<\/li>\n
      3. \n
        It then creates an Action<\/code> delegate to a Run<\/code> method on that MoveNextRunner<\/code>; this is how it’s able to get a delegate that will invoke the state machine’s MoveNext<\/code> in the context of the captured ExecutionContext<\/code>.<\/p>\n<\/li>\n
      4. \n
        If this is the first time the method is suspending, we won’t yet have a boxed state machine, so at this point it boxes it, creating a copy on the heap by storing the instance into a local typed as the IAsyncStateMachine<\/code> interface.  That box is then stored into the MoveNextRunner<\/code> that was allocated.<\/p>\n<\/li>\n
      5. \n
        Now comes a somewhat mind-bending step.  If you look back at the definition of the state machine struct, it contains the builder, public AsyncTaskMethodBuilder <>t__builder;<\/code>, and if you look at the definition of the builder, it contains internal IAsyncStateMachine m_stateMachine;<\/code>.  The builder needs to reference the boxed state machine so that on subsequent suspensions it can see it’s already boxed the state machine and doesn’t need to do so again.  But we just boxed the state machine, and that state machine contained a builder whose m_stateMachine<\/code> field is null.  We need to mutate that boxed state machine’s builder’s m_stateMachine<\/code> to point to its parent box.  To achieve that, the IAsyncStateMachine<\/code> interface that the compiler-generated state machine struct implements includes a void SetStateMachine(IAsyncStateMachine stateMachine);<\/code> method, and that state machine struct includes an implementation of that interface method:<\/p>\n
        private void SetStateMachine(IAsyncStateMachine stateMachine) =>\r\n    <>t__builder.SetStateMachine(stateMachine);<\/code><\/pre>\n
        So the builder boxes the state machine, and then passes that box to the box’s SetStateMachine<\/code> method, which calls to the builder’s SetStateMachine<\/code> method, which stores the box into the field. Whew.<\/p>\n<\/li>\n
      6. \n
        Finally, we have an Action<\/code> that represents the continuation, and that’s passed to the awaiter’s UnsafeOnCompleted<\/code> method.  In the case of a TaskAwaiter<\/code>, the task will store that Action<\/code> into the task’s continuation list, such that when the task completes, it’ll invoke the Action<\/code>, call back through the MoveNextRunner.Run<\/code>, call back through ExecutionContext.Run<\/code>, and finally invoke the state machine’s MoveNext<\/code> method to re-enter the state machine and continue running from where it left off.<\/p>\n<\/li>\n<\/ol>\n
        That’s what happens on .NET Framework, and you can witness the outcome of this in a profiler, such as by running an allocation profiler to see what’s allocated on each await.  Let’s take this silly program, which I’ve written just to highlight the allocation costs involved:<\/p>\n
        using System.Threading;\r\nusing System.Threading.Tasks;\r\n\r\nclass Program\r\n{\r\n    static async Task Main()\r\n    {\r\n        var al = new AsyncLocal<int>() { Value = 42 };\r\n        for (int i = 0; i < 1000; i++)\r\n        {\r\n            await SomeMethodAsync();\r\n        }\r\n    }\r\n\r\n    static async Task SomeMethodAsync()\r\n    {\r\n        for (int i = 0; i < 1000; i++)\r\n        {\r\n            await Task.Yield();\r\n        }\r\n    }\r\n}<\/code><\/pre>\n
        This program is creating an AsyncLocal<int><\/code> to flow the value 42 through all subsequent async operations.  It’s then calling SomeMethodAsync<\/code> 1000 times, each of which is suspending\/resuming 1000 times.  In Visual Studio, I run this using the .NET Object Allocation Tracking profiler<\/a>, which yields the following results:\n\"Allocation\nThat’s… a lot of allocation! Let’s examine each of these to understand where they’re coming from.<\/p>\n