Cancellation in .NET in Depth: Tokens, Callbacks and Linking

A CancellationToken isn't a flag you poll — it's a subscription list, and Cancel() is what fires every callback on it.

Lesson 153 taught you the cooperative cancellation pattern: a CancellationTokenSource creates a CancellationToken, you pass the token down through your async call chain, and the operation checks it and stops cleanly. That's the pattern you'll use in practically every real method. What that lesson didn't open up is the machinery underneath — how a token actually notices it's been canceled without polling in a loop somewhere, what happens when you combine a caller's token with your own internal timeout, and a real disposal gotcha that catches experienced developers.

In this lesson, you'll learn how CancellationTokenSource actually works internally — the callback registry that token.Register(...) adds to and Cancel() walks — timer-based cancellation with CancelAfter(...), linking multiple cancellation sources together with CreateLinkedTokenSource(...), a disposal-ordering gotcha worth knowing before it bites you in production, and solid patterns for checking cancellation at the right points inside your own long-running loops.

What Is It?

The Simple Explanation, Revisited

You already know the shape: a CancellationTokenSource is the trigger, a CancellationToken is the listener, and calling Cancel() flips every token the source produced into a canceled state. What this lesson adds is how that flip actually reaches code that's waiting on it — and the answer is not "something polls a flag in a loop somewhere in the background." It's closer to a subscription list.

The Technical Definition — the Callback Registry

Internally, a CancellationTokenSource maintains a registry of callbacks — delegates that code has asked to be invoked at the exact moment Cancel() is called. token.Register(Action callback) adds an entry to that registry and returns a CancellationTokenRegistration — itself a handle you can use to remove that specific registration later (via Dispose() on it), if the code that registered it no longer cares. When Cancel() runs, the source walks its entire registry and invokes every callback still registered, synchronously, one after another, on the thread that called Cancel() — token.IsCancellationRequested flipping to true and every awaiting Task from a cancellation-aware API throwing OperationCanceledException are themselves implemented as consequences of this same registry mechanism, not a separate, parallel system.

Why Does It Exist?

The Problem — Lesson 153's Pattern Doesn't Cover Every Real Scenario

The basic "pass the token, check it periodically" pattern handles the common case well. But real systems need more: what if you want an operation to cancel itself automatically after a timeout, with no external trigger at all? What if a method needs to combine two reasons to cancel — a caller's explicit token and its own internal timeout, so that either one stops the work? What if you need code to run reactively the instant cancellation happens — closing a socket, releasing a lock — rather than only at the next point your own loop happens to check the flag?

The Solution — a Richer Toolkit Built on the Same Token/Source Foundation

CancellationTokenSource provides exactly these tools, all built on the same registry idea: CancelAfter(...) for automatic, timer-based cancellation with no external caller needed; CreateLinkedTokenSource(...) for combining multiple independent cancellation signals into one token that fires when any of them does; and Register(...) for reactive, callback-driven cleanup the instant cancellation happens, rather than only at your next manual check.

Big Picture

How It Works

Part 1 — CancelAfter: Timer-Based Automatic Cancellation

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(10)); // auto-cancel if not finished within 10 seconds

await LongRunningOperationAsync(cts.Token);

CancelAfter(...) starts an internal timer; if that timer elapses before anything else cancels the source first, it calls Cancel() automatically — no separate Task.Delay race or manual timer code needed. It can also be called more than once to reset the countdown (each call restarts the timer), and calling Cancel() manually before the timer fires cancels the source immediately, exactly as if CancelAfter had never been called.

Part 2 — CreateLinkedTokenSource: Combining Multiple Cancellation Reasons

A very common real scenario: a method receives a caller's CancellationToken (they might cancel for their own reasons), but the method also wants its own internal timeout — either signal should stop the operation.

public async Task<Report> GenerateReportAsync(CancellationToken callerToken)
{
    using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(30)); // internal timeout
    using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(callerToken, timeoutCts.Token);

    // linkedCts.Token is canceled if EITHER callerToken is canceled OR the 30-second timeout elapses
    return await BuildReportAsync(linkedCts.Token);
}

CreateLinkedTokenSource returns a brand-new CancellationTokenSource whose token becomes canceled the moment any of the source tokens passed into it become canceled — internally, it does this by registering its own callback (via the exact Register(...) mechanism from Part 1) on each of the tokens you hand it, so that when any one of them fires, that callback cancels the linked source in turn. From the caller of BuildReportAsync's point of view, there's just one token to check — the fact that it represents "either of two independent reasons" is entirely hidden behind that single linked token.

Simple Example

Registering a callback directly, to see the notification-driven path in action rather than polling:

using var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;

using CancellationTokenRegistration registration = token.Register(() =>
{
    Console.WriteLine("Cancellation requested — releasing the connection now.");
    connection.Close();
});

Console.WriteLine("Waiting...");
cts.Cancel(); // synchronously invokes every registered callback, including the one above, right now
Console.WriteLine("Cancel() has returned — the callback above already ran.");

Code → Meaning → Result: The lambda passed to Register is added to the source's registry. Nothing runs it — nothing polls anything — until Cancel() is actually called. At that exact moment, the source walks its registry and invokes the callback synchronously, before Cancel() itself returns. This is why the order of the two console lines is guaranteed: "Cancellation requested..." always prints before "Cancel() has returned...", because Cancel() doesn't return until every registered callback has finished running.

Real-World Example — Cooperative Cancellation Inside Your Own Long-Running Loop

A background service processing a large batch of records is exactly where cooperative cancellation design decisions matter — checking at the wrong points can make cancellation feel unresponsive, or worse, leave data half-processed at an inconsistent point:

public async Task ProcessBatchAsync(IReadOnlyList<Order> orders, CancellationToken token)
{
    foreach (var order in orders)
    {
        token.ThrowIfCancellationRequested(); //  checked at the TOP of every iteration — a sensible, regular point

        await ValidateAsync(order, token);     //  token passed down into every cancellation-aware call
        await ChargePaymentAsync(order, token); // if this throws OperationCanceledException, the record is left
                                                 // in a known, safe state — not partially charged and partially shipped
        await ShipOrderAsync(order, token);

        // NOT checked again mid-record — each record is treated as an atomic unit here,
        // so cancellation takes effect between records, not partway through one
    }
}

Notice the check happens once per iteration, at a point where stopping leaves the system in a clean, well-defined state — not, say, in the middle of charging a payment. This is the real design skill cooperative cancellation requires: checking often enough that cancellation feels responsive, but only at points where "stop here" is actually safe to do.

Analogy

Under the Hood

Common Confusion

1. "Cancellation is like an exception thrown from the outside" — no, it's entirely cooperative

Lesson 153 already made this point, and it's worth repeating with the registry mechanism now visible: nothing about Cancel() forcibly interrupts running code the way a thread-abort would. It flips a flag and runs registered callbacks — but a piece of code that never checks IsCancellationRequested, never calls ThrowIfCancellationRequested(), and never uses a cancellation-aware API keeps right on running, completely unaffected, no matter how many times Cancel() is called.

2. "A linked token source's token is the same object as the tokens it was created from" — no, it's a new, independent token

CreateLinkedTokenSource(a, b) returns a brand-new CancellationTokenSource with its own, distinct token — one that happens to be wired, via registered callbacks, to become canceled when a or b does. Canceling the linked source directly does not cancel a or b themselves — the relationship only flows one direction, from the originals into the linked source, never back out.

Common Mistakes

Mistake 1 — Only checking cancellation at the very start of a long-running method

Wrong:

public async Task ProcessAllAsync(List<Item> items, CancellationToken token)
{
    token.ThrowIfCancellationRequested(); // checked once, at the top — then never again
    foreach (var item in items)
        await ProcessItemAsync(item); // could run for minutes across thousands of items with no way to stop
}

Fix: check at sensible, regular points throughout the loop — as the Real-World Example demonstrated, once per iteration is usually the right granularity for per-item work.

Mistake 2 — Checking cancellation so often it hurts readability or performance for no real benefit

Calling ThrowIfCancellationRequested() after every single line inside a tight, fast inner loop that completes in microseconds anyway. Match the check frequency to how long each unit of work actually takes — checking once per outer-loop iteration over meaningful units of work (a record, a file, a batch) is almost always the right granularity; checking inside a sub-millisecond inner loop adds noise without meaningfully improving responsiveness.

Mistake 3 — Disposing a CancellationTokenSource from a different thread than the one that might still be canceling it

Manually calling .Dispose() on a shared CancellationTokenSource from one thread while another thread might concurrently call .Cancel() on it or still be running a registered callback — exactly the race Under the Hood point 2 described. Prefer a using declaration scoped to the code that owns the source, so disposal happens after the operation (and any cancellation triggered during it) has already fully completed — the pattern used throughout this lesson's examples.

When Should I Use It?

Mental Model

Key Takeaway

Check Your Understanding

You've gone past the basic pattern from lesson 153 into the actual mechanics of cancellation. Let's check your understanding.

You've completed the internals half of Part IV — Task, SynchronizationContext, ThreadPool, ValueTask, and Cancellation. Next: putting concurrency itself to work, with Parallel programming and thread-safe collections.