C#

What Is Async

Updated:

It is not a feature of the CPU, the language, or even the runtime. It is an orchestration — a pattern glued together from a compiler-built state machine, an ordinary object on the heap, and a single non-blocking call to the operating system. No one entity “does” the async. This article takes it apart down to the bare metal and puts it back together.

A note on how this article presented

Throughout, hard mechanics are introduced twice. First as a metaphor — a deliberately simple, slightly imprecise picture whose only job is to install the right intuition. Then as the precise version — the technically correct statement, once the intuition is in place.

This is how every complex idea is taught: you explain orbits to a child as “the moon falls around the Earth forever” before you show them the calculus. The metaphor is not a lie; it is scaffolding. We keep both, side by side, and always lead with the metaphor — because intuition first, rigor second, is the order in which human understanding actually forms.

So when you see 🟢 Metaphor followed by 🔵 Precise, that is the pattern. Read the green to get it, read the blue to get it right.

The false picture almost everyone holds

Ask a working developer what await does and you will usually hear: “it pauses the method and waits for the result without blocking the thread.”

Every word of that sentence is misleading.

  • It does not “pause the method” — methods cannot pause; they run to a return and end.
  • It does not “wait” — nothing in your program waits.
  • The thread is not “not blocked” — the thread is gone entirely, off doing other work.

The sentence describes an illusion so convincing that the people maintaining the illusion forget it is one. The truth is stranger and, once seen, far simpler: async/await is an invented pattern that makes a method look like one continuous top-to-bottom flow when it is actually two or more disconnected fragments, stitched together by a state-tracking object and woken up by the operating system.

To prove that, we have to go all the way to the floor — below HttpClient, below FileStream, below every library you would normally trust to “be async” — to the single place where the asynchrony is physically real: a system call to the OS kernel.

The Basic Analogy: A Quick Overview

As established, the whole “async” thing is an orchestration. At the low-level mechanics there is no single component called “async” — so what does the orchestration actually look like? Here is the first look, built by hand so every moving part is visible.

The trick async must pull off: when a thread is released, its stack is wiped — local variables and all. So the state of an in-flight job has to be moved somewhere that outlives the thread: the heap. Picture a mission tracker.

// A plain object holding the FACTS of one in-flight read — state only, no behavior.
public class MissionInfo
{
    public string OriginalFile = "";
    public string TargetNewFile = "";
}

class MyClass
{
    // Collection of Objects is kept on the heap, keyed by a mission id, so each mission survives after its thread is freed.
    // the mission tracker
    static Dictionary<int, MissionInfo> dicMissionInfo = new Dictionary<int, MissionInfo>();

    // The stack memory thread
    // PHASE 1 — runs on the calling thread, then leaves.
    public static void ReadFile(string originalFile, string targetNewFile)
    {
        // Build the mission state on the stack memory (conceptually, a tiny hand-made "state machine").
        var missionInfo = new MissionInfo
        {
            OriginalFile  = originalFile,
            TargetNewFile = targetNewFile
        };

        int missionId = GetNewMissionId();

        // Move the state onto the heap so it outlives this thread.
        dicMissionInfo[missionId] = missionInfo;

        // Overlapped (non-blocking) call: hand the OS the mission id + a callback, then leave.
        OS.ReadFileOverlapped(originalFile, missionId, OnBytesReady);

        // Nothing left to do → the thread is released, 
        // exactly like any ordinary method ending.
        // The stack clears, the thread is freed — but missionInfo lives on, on the heap.
        // So how to release a thread you ask? when there is nothing to do left, it's freed automatically
    }

    // PHASE 2 — the OS calls this LATER, on a thread it supplies, when the bytes are ready.
    static void OnBytesReady(int missionId, byte[] data)
    {
        var missionInfo = dicMissionInfo[missionId];          // recover the saved state
        System.IO.File.WriteAllBytes(missionInfo.TargetNewFile, data);
        dicMissionInfo.Remove(missionId);                     // mission accomplished
    }
}

(This code is metaphorical — a scale model of the idea, not the real API.)

The flow it models: your thread calls a special OS function marked “overlapped” (Windows’ word for non-blocking).

🟢 Metaphor. Synchronous is a phone call where you stay silent on the line until the other person finds the answer. Overlapped/async is leaving a voicemail with your callback number and hanging up — you’re free instantly, and they call you back when the answer exists. Leaving the voicemail is one action; their return call is a separate action, later.

🔵 Precise. This is not one function “returning twice.” It is two distinct events: the OS call returns once, immediately, with a “pending” acknowledgement — which frees your thread; and later, the kernel (holding the callback and buffer you gave it) invokes that callback on a thread it supplies, once the hardware has delivered the bytes. One return, plus one callback. Two mechanisms, not one call with two answers.

This is exactly why the state had to go on the heap. Between the “pending” return and the callback, your thread is gone — and a vanished thread takes its stack with it. The dictionary is what survives the gap.

What the real runtime does with this idea

The C# runtime automates the hand-built tracker above. Conceptually:

Phase 1 — on the calling thread:

  • Create a state machine for the call. It starts as a struct on the stack (cheap, free to discard).
  • At the first genuine suspension, copy that struct onto the heap so it can outlive the thread that is about to leave.
  • Issue the overlapped OS call, handing over a callback.
  • Return — nothing left to do — which releases the thread automatically.

What the state machine actually stores (and what it does not):

  • ✅ The method’s local variables, lifted into fields so they survive on the heap.
  • ✅ A position marker (an integer) recording which await it paused at.
  • ✅ A reference to the awaiter it is waiting on.
  • ❌ Not “the methods” or “the callbacks” — code is not copied into the object; only data and the resume-position are.

Between phases — outside your program:
OS/kernel → IOCP → hardware/firmware → OS/kernel. No thread of yours exists during this stretch.

Phase 2 — on a thread the OS supplies:
The kernel signals completion; the runtime takes a pool thread, hands it the heap-resident state machine, and resumes the method from its saved position — local variables intact, because they were never on a stack that could be wiped.

That is the entire orchestration. The next section drops below even this — to the raw Win32 syscall — to prove the “overlapped” call and its “pending” return are real, not a story.

The same job, in sync

Everything above — the mission tracker, the heap promotion, the two-event callback dance — exists to enable one thing: the OS overlapped call, and its two-step return. That single capability is what the entire orchestration is built around.

Now here is the identical task — read a file, write it elsewhere — in the synchronous form every developer already knows:

class MyClass
{
    public static void ReadFile(string originalFile, string targetNewFile)
    {
        // thread waits here for the disk
        byte[] bytes = File.ReadAllBytes(originalFile);
        File.WriteAllBytes(targetNewFile, bytes);
    }
}

Two lines. No mission tracker, no heap promotion, no callback, no state machine, no second thread. One thread walks straight down the method, waits on the disk at line 1, and continues at line 2 — and the local variable bytes lives safely on the stack the whole time, because the thread never leaves.

Put the two side by side and the real nature of async comes into focus. The synchronous version is not missing a feature. The asynchronous version is not an upgrade. They do the exact same job. The only difference is what happens during the disk read: sync keeps one thread parked and waiting; async performs all that orchestration so that no thread waits at all.

That is the entire trade, in two code samples. Every line of machinery in this section buys you one thing and one thing only — a freed thread during the wait. Whether that thread is worth freeing is not a question this article can answer; it depends entirely on how many threads you have and how long the waits are. (That question has its own article: The Async Cliff.) But you can now see, concretely, exactly what you are buying and exactly what it costs.

The rest of this article proves the one load-bearing claim the whole orchestration rests on: that the “overlapped” OS call and its “pending” return are real. For that, we go to the bare metal.

Part 1: The bottom of the stack, with nothing left to trust

Every library example just relocates your trust. File.ReadAllBytesAsync trusts FileStream, which trusts the runtime, which trusts a syscall. You can keep asking “but how do you know that one is real?” until you reach the operating system boundary — and the only honest way to see real async is to stand at that boundary and call it yourself.

Here is a file read written with raw Win32 P/Invoke. It does the exact work File.ReadAllBytesAsync does under the hood, with every comfortable wrapper stripped off.

using System;
using System.IO;
using System.Runtime.InteropServices;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Win32.SafeHandles;

public class NativeAsyncFileReader
{
    // ── STEP 1: Import the OS functions directly from the kernel's DLL ──
    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
    private static extern SafeFileHandle CreateFile(
        string lpFileName, uint dwDesiredAccess, uint dwShareMode,
        IntPtr lpSecurityAttributes, uint dwCreationDisposition,
        uint dwFlagsAndAttributes, IntPtr hTemplateFile);

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern unsafe bool ReadFile(
        SafeFileHandle hFile, byte* lpBuffer, uint nNumberOfBytesToRead,
        IntPtr lpNumberOfBytesRead, NativeOverlapped* lpOverlapped);

    private const uint GENERIC_READ          = 0x80000000;
    private const uint FILE_SHARE_READ       = 1;
    private const uint OPEN_EXISTING         = 3;
    private const uint FILE_FLAG_OVERLAPPED  = 0x40000000; // the bit that means "async"
    private const int  ERROR_IO_PENDING      = 997;        // the kernel saying "I took it"

    public unsafe Task<byte[]> ReadFileNativeAsync(string filePath, int bytesToRead)
    {
        // A hand-made container we will hand to the caller now and fill in later.
        var tcs = new TaskCompletionSource<byte[]>();

        // ── STEP 2: Open the file in async-capable mode ──
        // FILE_FLAG_OVERLAPPED tells the KERNEL this handle behaves asynchronously.
        SafeFileHandle handle = CreateFile(
            filePath, GENERIC_READ, FILE_SHARE_READ, IntPtr.Zero,
            OPEN_EXISTING, FILE_FLAG_OVERLAPPED, IntPtr.Zero);

        if (handle.IsInvalid)
            throw new IOException($"Open failed. Win32 error: {Marshal.GetLastWin32Error()}");

        byte[] managedBuffer = new byte[bytesToRead];

        // ── STEP 3: Wire the handle to the OS completion queue (IOCP) ──
        ThreadPool.BindHandle(handle);

        // ── STEP 4: Register the "after the read finishes" callback WITH THE KERNEL ──
        // It receives the RESULT of the read (error code, bytes moved) — not the handle.
        // It does NOT run now. The OS will run it later, on a thread we never started.
        var overlapped = new Overlapped();
        NativeOverlapped* native = overlapped.Pack((errorCode, numBytes, ov) =>
        {
            try
            {
                if (errorCode == 0)
                    tcs.SetResult(managedBuffer);   // ← fills the container handed out earlier
                else
                    tcs.SetException(new IOException($"Async read failed: {errorCode}"));
            }
            finally
            {
                Overlapped.Free(ov);
                handle.Dispose();
            }
        }, managedBuffer);

        fixed (byte* pBuffer = managedBuffer)   // pin so the kernel can write straight into it
        {
            // ── STEP 5: Issue the read — THE HAND-OFF ──
            // Because of the overlapped flag, ReadFile does NOT wait for the disk.
            bool immediate = ReadFile(handle, pBuffer, (uint)bytesToRead, IntPtr.Zero, native);
            int err = Marshal.GetLastWin32Error();

            if (!immediate && err != ERROR_IO_PENDING)
            {
                Overlapped.Free(native);
                handle.Dispose();
                throw new IOException($"Read init failed. Win32 error: {err}");
            }
            // err == ERROR_IO_PENDING → the kernel owns the operation now.
            // This thread is completely free. Nobody is waiting on the disk.
        }

        // Return the not-yet-filled container immediately. Zero threads are blocked.
        return tcs.Task;
    }
}

Read the comments in order — they are the six steps. The thing to notice is Step 5 and what comes after it. ReadFile returns instantly with ERROR_IO_PENDING. That return code is the kernel saying, in effect, “I have accepted the work and given you your thread back; I will call you when it’s done.” The method then flows straight to return tcs.Task and ends. No waiting happened anywhere in your code.

That is real async, with nothing left to trust. There is no Async method here to take on faith — ReadFile is a syscall, FILE_FLAG_OVERLAPPED is a bit the kernel checks, and ERROR_IO_PENDING is the kernel returning your thread. Past this line there is no more C#; there is only the kernel and the disk controller.

Part 2: The method that exits twice

Here is the realization that unlocks everything. Look at ReadFileNativeAsync and ask: how many times does control leave this method?

The answer is two, and they are completely different events separated in time.

🟢 Metaphor. The method is a coat-check counter. The first exit is you handing over your coat and walking away with a numbered ticket (the Task) — the coat isn’t ready, but you’re free to go do other things. The second exit is, much later, the attendant hanging your actual coat on the hook that matches your ticket number. You weren’t standing there the whole time. The ticket held your place.

🔵 Precise. The first exit is return tcs.Task — the method returns an incomplete Task<byte[]> to the caller and ends, releasing its thread. The second “exit” is not a return from this method at all (that already happened); it is the registered callback firing later, on an OS I/O completion thread, executing tcs.SetResult(managedBuffer) — which transitions the previously-returned Task from incomplete to complete and publishes the data into it.

The two timelines, drawn out:

First exit  (Timeline A — instant, on your calling thread):
    Step 5 fires the read → kernel says PENDING → return tcs.Task → thread released

         ... meanwhile, outside your program entirely:
             the disk controller reads the bytes, the kernel waits on hardware ...

Second exit (Timeline B — later, on an OS completion thread you never created):
    kernel posts completion → OS thread runs the callback → tcs.SetResult(bytes)
    → the Task handed out in Timeline A is now full

This is the whole secret in one sentence: the method hands out an empty container and leaves; something else fills the container later. Control flow (your thread leaving) and data flow (the bytes arriving) have been split into two independent events. The Task is the only thing that connects them — a placeholder that exists because the data and the thread no longer travel together.

Part 3: What Task and TaskCompletionSource actually are

There is a temptation to imagine Task as something alive — a little engine running your work in the background. It is nothing of the sort.

🟢 Metaphor. TaskCompletionSource is a parcel locker. You’re given an empty locker and its key (tcs.Task) right now. The locker just sits there. Later, a delivery driver (the OS completion thread) opens it with their copy of the key and drops the parcel in. The locker never did anything — it held a space.

🔵 Precise. Task and TaskCompletionSource are ordinary managed objects living on the heap. They hold fields: a status flag (IsCompleted), a result slot, and a list of continuations (callbacks to run when status flips to complete). They consume zero CPU and hold zero threads while “waiting.” A Task is not a unit of execution; it is a state cell with a notification list.

When the caller does await readTask and the task is not yet complete, here is what physically happens: the caller registers a continuation (“when this flips to complete, run the rest of my method”) onto that list, and then the caller’s own execution path also stops and releases its thread. Now there are zero threads anywhere associated with this read. The Task sits dormant on the heap. The bytes are being moved by the disk. Nobody is waiting in the programmatic sense — no thread is parked in a wait state burning a stack.

When tcs.SetResult(bytes) finally runs on the OS completion thread, it does two mechanical things: drops the bytes into the result slot, and flips IsCompleted to true. Flipping that flag is what triggers the notification list — the runtime grabs any pool thread, hands it the now-complete Task, and runs the continuation the caller left behind.

This is why the TaskCompletionSource can be described as a placeholder that simply parks until the data returns and fills it in — an object on a shelf, filled by whoever finishes the work.

Part 4: How a method pauses in the middle and resumes from the exact spot

The manual example used a hand-written TaskCompletionSource. But when you write a normal async method, you don’t write any of that — you just write await. So where does the “park and resume” machinery come from?

This is the deepest part, and the most surprising: the C# compiler deletes your method and rewrites it as a class.

The problem it must solve: in synchronous code, “where am I in this method” and “what are my local variables” live on the thread’s stack. Release the thread and the stack is gone — you lose your place and your data. So to survive a thread release, your place and your data must move somewhere that outlives the thread.

🟢 Metaphor. The compiler turns your method into a board game with a save-game file. Your local variables become slots on the save file. A little number records which square you were on. When you have to leave the table, you don’t lose progress — you saved the game to disk. Anyone can sit down later, load the save, and continue from the exact square, with all your pieces where you left them.

🔵 Precise. The compiler generates a hidden state-machine type. Every local variable becomes a field on that type (so it lives on the heap, not the stack). An integer _state field records which await was last reached. The method body is chopped into segments between awaits, wrapped in a MoveNext() method that branches on _state. Because the variables are now heap fields, they survive indefinitely with no thread attached.

Here is the shape of what the compiler produces — simplified for teaching, not literal compiler output:

// You write:
public async Task<string> ProcessFileAsync()
{
    int userId = 42;
    string path = "config.dat";
    byte[] data = await FetchNativeAsync(path);     // ← the suspension point
    return $"User {userId} processed {data.Length} bytes";
}

// The compiler generates (conceptually) a state machine like this:
private class ProcessFileAsync_StateMachine
{
    // 1. Local variables become FIELDS — they now live on the heap and survive.
    public int    userId;
    public string path;
    public byte[] data;

    // 2. The bookkeeping.
    public int _state = 0;                              // which segment are we on
    public AsyncTaskMethodBuilder<string> builder;      // the real "result container" wiring
    private TaskAwaiter<byte[]> _awaiter;

    // 3. The engine. Called once to start, then AGAIN each time an await completes.
    public void MoveNext()
    {
        if (_state == 0)
        {
            userId = 42;
            path   = "config.dat";

            _awaiter = FetchNativeAsync(path).GetAwaiter();
            if (!_awaiter.IsCompleted)
            {
                _state = 1;                             // SAVE: remember we paused here
                // "When the inner task completes, call MoveNext again."
                builder.AwaitUnsafeOnCompleted(ref _awaiter, ref this);
                return;                                 // 🚪 FIRST EXIT — thread released
            }
        }

        if (_state == 1)                                // RESUME lands here next time
        {
            data = _awaiter.GetResult();                // userId is STILL 42 — it's a field
            builder.SetResult($"User {userId} processed {data.Length} bytes");
        }
    }
}

Trace it:

  1. Start. You call ProcessFileAsync(). The runtime creates a state-machine instance, sets _state = 0, and calls MoveNext() once.
  2. First segment. It runs your code up to the await, fires the inner async operation, sees it isn’t done, saves _state = 1, registers MoveNext as the thing to call on completion, and returns. The thread is released.
  3. The park. No thread exists for this work. But userId = 42 and path are safe — they’re fields on a heap object, not stack slots.
  4. Wake-up. The inner operation completes (ultimately because the OS posted a completion, exactly as in Part 1). The runtime grabs any pool thread and calls MoveNext() again.
  5. Resume. _state is 1, so the first block is skipped entirely. Execution lands in the second segment. userId is still 42, because it was never on a stack that could be wiped. The method finishes and publishes its result.

That is “pause in the middle and resume from the exact spot.” Nothing actually paused. The method was sliced into segments, your progress and variables were saved into a heap object, the method exited early to free the thread, and the OS-driven completion called back in to run the next slice.

await is the keyword that tells the compiler where to put the slice boundaries. That is all it is.

Part 5: When is the state machine created? (And what it costs)

A natural question once you see the machinery: is one of these state machines built on every async call?

Yes. Every invocation of an async method creates its own state-machine instance. A web server handling 10,000 concurrent requests, each calling five nested async methods, has roughly 50,000 of these objects alive at once. They are small and idle, but they are real allocations.

The runtime works hard to make this cheap:

🟢 Metaphor. The save-game starts as a scribble on a sticky note on your desk (fast, free, thrown away when you stand up). Only if you actually have to leave the table does someone bother copying it into the permanent filing cabinet.

🔵 Precise. For methods that complete synchronously (the awaited thing was already done, no real suspension), the compiler can keep the state machine as a struct on the stack — nearly free, no heap allocation, collected for free when the frame returns. Only at the first genuine suspension does the runtime promote the state machine onto the heap (allocating the Task and copying the struct’s fields into a heap object) so it can outlive the released thread. (A common shorthand calls this promotion “boxing” — that word is technically wrong; boxing is a specific value-type-to-object conversion. This is the async builder lifting the state machine to the heap, which is a different mechanism with a similar shape.)

And here is the part that ties this article back to engineering judgment: that heap promotion is a cost, paid per suspended async call, in allocations the garbage collector must later clean up.

Write a hot loop that awaits a tiny operation a million times, and you have created a million heap objects in milliseconds — feeding the GC a workload that synchronous code would never generate, because synchronous code keeps its state on the stack for free. The orchestration is not free. You are trading the simple, zero-allocation thread stack of synchronous code for an object-allocation machine that builds and discards state on every suspended call.

When you genuinely need to hold thousands of concurrent waits without thousands of blocked threads, that trade is a bargain — the allocations are trivial next to the threads you saved. When you don’t, you are paying a memory-and-GC tax to solve a problem you do not have.

What async actually is

Put the five parts together and the definition writes itself:

Async in C# is an orchestration — an invented pattern, not a primitive. No single entity “does” the asynchrony. It is a coordinated dance between three ordinary things: a compiler-generated state machine that slices your method into segments and saves your variables on the heap; a plain Task object that holds a place for a result that does not exist yet; and a single non-blocking system call that hands the real waiting to the operating-system kernel, which alone performs the wait with no thread at all and calls back when the hardware is done.

The keyword await is not a verb that does something to a thread. It is a marker telling the compiler where to cut your method, and a promise that the cut pieces will be sewn back together when a result arrives. The thread is not paused — it leaves. The method is not suspended — it exits and is later re-entered. The wait is not performed by C# — it is performed by the OS, the disk controller, the network card.

Once you see this, the famous difficulty of async dissolves into a different question. The hard part was never “how does it work.” The hard part is “is the orchestration worth its price for this workload?” — the allocations, the state machines, the viral signatures, the lost simplicity of a linear stack. That is a question of measurement and judgment, not mechanism.

And that question has its own article: The Async Cliff: When Synchronous Code Is the Right Engineering Choice — which begins exactly where this one ends, with the machinery understood and the bill itemized, and asks the only question left: which side of the cliff does your system live on?

This article reconstructs async from the operating system upward, the way it was assembled in a long conversation that refused to accept “trust me, it’s async” at any layer — and kept asking, at each level, “but where is the thread, and who is actually doing the waiting?” The answer, every time, was the same: the OS does the waiting; C# only orchestrates the question.

aspnet-club.com | Github | Youtube | X.com | Facebook

© adriancs.com. All Rights Reserved.