What are linked cancellation tokens, and how do you combine a caller's token with your own timeout safely?

1. How linking works internally

CreateLinkedTokenSource(a, b):
    linked = new CancellationTokenSource()
    regA = a.UnsafeRegister(s => ((CTS)s).Cancel(), linked)
    regB = b.UnsafeRegister(...)
    (if any parent is already cancelled -> linked is cancelled immediately)

linked.Dispose():
    regA.Dispose(); regB.Dispose()     // removes callback nodes from a and b
    dispose own timer (if CancelAfter was used)

Each link is one callback registration per parent. The parent holds a reference to the linked source until the registration is disposed, which is the leak mechanism.

2. Layered deadlines

ASP.NET Core request (RequestAborted)
  └─ endpoint: total budget 2 s  (linked: RequestAborted + 2 s)
        └─ pricing call: 800 ms   (linked: endpoint token + 800 ms)
        └─ stock call:   800 ms   (linked: endpoint token + 800 ms)

Each layer links to its parent's token, never to a fresh one, so cancellation still flows from the top. Inner timeouts should be shorter than outer budgets, otherwise the inner timeout never fires and the outer one masks which dependency was slow.

3. Retries with total and per-attempt timeouts

using var total = CancellationTokenSource.CreateLinkedTokenSource(ct);
total.CancelAfter(TimeSpan.FromSeconds(5));

for (int attempt = 1; attempt <= 3; attempt++)
{
    using var perAttempt = CancellationTokenSource.CreateLinkedTokenSource(total.Token);
    perAttempt.CancelAfter(TimeSpan.FromSeconds(1.5));
    try { return await CallAsync(perAttempt.Token); }
    catch (OperationCanceledException) when (!total.IsCancellationRequested) { /* attempt timed out; retry */ }
    catch (HttpRequestException) when (attempt < 3) { await Task.Delay(200 * attempt, total.Token); }
}

In production I'd use the standard resilience handler instead of hand-writing this, but it shows the structure.

4. Testing timeouts deterministically

var time = new FakeTimeProvider();
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5), time);
var task = service.DoAsync(cts.Token);
time.Advance(TimeSpan.FromSeconds(6));          // no real waiting
await Assert.ThrowsAsync<TimeoutException>(() => task);

The code under test must also use TimeProvider (e.g. Task.Delay(delay, timeProvider, ct)) for fully deterministic tests.

5. Detecting the leak

• dotnet-counters: GC heap growing steadily.
• dotnet-gcdump / dumpheap -stat: many CallbackNode / CancellationTokenSource instances.
• gcroot on one: path through the long-lived parent token's callback list.

6. Version notes

7. Try it yourself

1. Run the code example: first call times out (TimeoutException), second is cancelled by the caller.
2. Remove using and create 1,000,000 linked sources from one long-lived token; watch memory with dotnet-counters.
3. Take a gcdump and find the CallbackNode objects.
4. Build a three-level deadline chain (request → endpoint → call) and log which level fired.
5. Rewrite a timeout test using FakeTimeProvider so it runs instantly.
6. Compare WaitAsync(timeout) with a linked token by checking whether the underlying operation keeps running.

using var callerCts = new CancellationTokenSource();

try
{
    await PricingClient.GetPriceAsync("SKU-1", TimeSpan.FromMilliseconds(100), callerCts.Token);
}
catch (TimeoutException ex)
{
    Console.WriteLine($"Timeout: {ex.Message}");
}

callerCts.CancelAfter(10);
try
{
    await PricingClient.GetPriceAsync("SKU-1", TimeSpan.FromSeconds(5), callerCts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Caller cancelled");
}

public static class PricingClient
{
    public static async Task<decimal> GetPriceAsync(string sku, TimeSpan timeout, CancellationToken ct)
    {
        // Dispose the linked source: it registers callbacks on ct.
        using var linked = CancellationTokenSource.CreateLinkedTokenSource(ct);
        linked.CancelAfter(timeout);

        try
        {
            await Task.Delay(1000, linked.Token); // stands in for a slow HTTP call
            return 42m;
        }
        catch (OperationCanceledException) when (!ct.IsCancellationRequested)
        {
            // Only our timeout fired: report it as a timeout, not a caller cancellation.
            throw new TimeoutException($"Pricing for {sku} exceeded {timeout.TotalMilliseconds} ms");
        }
    }
}