How does cooperative cancellation with CancellationToken work in .NET, and how do you design APIs that support it?

1. Why cooperative

Thread.Abort could stop code anywhere: inside a lock, halfway through updating shared state, during a static constructor. Cooperative cancellation lets code stop only at points it chooses, and finally blocks run normally as the OperationCanceledException propagates.

2. What happens inside Cancel()

cts.Cancel():
    set state = cancelled (once)
    run registered callbacks synchronously, on THIS thread
    (exceptions from callbacks are aggregated; Cancel(throwOnFirstException) controls behaviour)

cts.CancelAsync() (.NET 8+):
    set state, then run callbacks asynchronously so the caller isn't blocked by them

Because callbacks run inline, a slow or blocking callback delays whoever called Cancel(), which might be a request thread or a timer. Keep callbacks tiny and non-throwing, and don't depend on the order in which callbacks run.

3. Registrations and leaks

public async Task<Reply> SendAsync(Request r, CancellationToken ct)
{
    var tcs = new TaskCompletionSource<Reply>(TaskCreationOptions.RunContinuationsAsynchronously);
    _pending[r.Id] = tcs;
    using CancellationTokenRegistration reg = ct.Register(() =>
    {
        if (_pending.TryRemove(r.Id, out var t)) t.TrySetCanceled(ct);
    });
    await _socket.SendAsync(r.Bytes, ct);
    return await tcs.Task;
}   // reg disposed: no callback left on a long-lived token

If ct is long-lived (e.g. the host's stopping token) and registrations aren't disposed, callbacks and their captured state accumulate: a memory leak.

4. CPU loops: how often to check

for (int i = 0; i < rows.Length; i++)
{
    if ((i & 0x3FF) == 0) ct.ThrowIfCancellationRequested();   // every 1,024 rows
    Process(rows[i]);
}

Checking is cheap (a volatile read), but not free in the tightest loops; aim for responsiveness in the tens of milliseconds.

5. Points of no return

public async Task<OrderResult> CheckoutAsync(Cart cart, CancellationToken ct)
{
    var quote = await _pricing.QuoteAsync(cart, ct);           // cancellable
    var payment = await _payments.ChargeAsync(quote, ct);      // last cancellable step

    // Point of no return: money moved. Finish consistently even if the client disconnects.
    var order = await _orders.CreateAsync(cart, payment, CancellationToken.None);
    await _outbox.EnqueueAsync(new OrderPlaced(order.Id), CancellationToken.None);
    return new OrderResult(order.Id);
}

Pair this with idempotency keys so retries after a disconnect don't double-charge.

6. Disposal of sources

• Dispose sources you create, especially with CancelAfter/timeouts (they own a timer) and linked sources (they register on parent tokens).
• Don't dispose a source while other code may still call Cancel() on it.
• TryReset() (.NET 6+) allows reuse of a source that hasn't been cancelled, useful in pooled scenarios.

7. Version notes

8. Try it yourself

1. Run the code example and observe the callback and the Cancelled as requested message.
2. Remove the token from Task.Delay and see cancellation become slower (only checked per batch).
3. Add a Register callback that sleeps 2 s and measure how long Cancel() takes; compare with CancelAsync().
4. In a minimal API, accept a CancellationToken, await Task.Delay(10_000, ct), call it with curl and press Ctrl+C: observe the cancellation.
5. Register 100,000 callbacks on a long-lived token without disposing them and watch memory.
6. Enable CA2016 and fix the warnings in a sample service.

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromMilliseconds(200));

try
{
    long total = await SumAsync(cts.Token);
    Console.WriteLine($"Total {total}");
}
catch (OperationCanceledException) when (cts.IsCancellationRequested)
{
    Console.WriteLine("Cancelled as requested"); // expected, not an error
}

static async Task<long> SumAsync(CancellationToken cancellationToken = default)
{
    using var registration = cancellationToken.Register(() => Console.WriteLine("Cancel callback ran"));
    long sum = 0;
    for (int batch = 0; batch < 1_000; batch++)
    {
        cancellationToken.ThrowIfCancellationRequested();     // CPU loop check
        for (int i = 0; i < 100_000; i++) sum += i;
        await Task.Delay(1, cancellationToken);               // pass the token down
    }
    return sum;
}

// ASP.NET Core: the token is bound to HttpContext.RequestAborted.
// app.MapGet("/orders", async (OrdersDb db, CancellationToken ct) =>
//     await db.Orders.Where(o => o.Open).ToListAsync(ct));