📝 Lesson 3.1: Cancellation and Timeouts

Cooperative Cancellation

.NET does not forcibly kill running work — abruptly aborting a thread could leave data half-written and locks held, corrupting state. Instead it uses cooperative cancellation: cancellation is a request, and the running code chooses safe points to notice it and stop cleanly.

Two types work together: a CancellationTokenSource (the caller holds it and triggers cancellation) and a CancellationToken (a lightweight handle passed into the operation, which it observes).

Token and Source

The caller creates a source, passes its Token to the operation, and calls Cancel() when it wants to stop:

using var cts = new CancellationTokenSource();

// Start the work, giving it the token
Task work = DoWorkAsync(cts.Token);

// Later — e.g. user pressed a button — request cancellation
cts.Cancel();

try
{
    await work;
}
catch (OperationCanceledException)
{
    Console.WriteLine("Work was cancelled.");
}

Observing the Token

An operation must actively check the token to be cancellable. There are two idioms.

Throw at a check point

ThrowIfCancellationRequested() throws an OperationCanceledException if cancellation was requested — the cleanest way to bail out of a loop:

async Task ProcessAsync(IEnumerable<string> items, CancellationToken token)
{
    foreach (string item in items)
    {
        token.ThrowIfCancellationRequested();   // stop point
        await ProcessOneAsync(item);
    }
}

Check the flag

Or inspect IsCancellationRequested to stop without throwing (e.g. to return partial results):

while (!token.IsCancellationRequested)
{
    DoOneStep();
}

Pass it to async calls

Most importantly, forward the token to the async operations you call. They'll honor it internally — cancelling a slow HTTP request or delay promptly, rather than waiting for the next manual check:

async Task<string> FetchAsync(string url, CancellationToken token)
{
    // The token cancels the wait/request itself
    await Task.Delay(5000, token);                       // cancellable delay
    return await _client.GetStringAsync(url, token);     // cancellable request
}

Handling Cancellation

When cancellation fires, the operation throws OperationCanceledException (its TaskCanceledException subclass, which you saw around timeouts in Intermediate, derives from it). Catch OperationCanceledException to cover both:

try
{
    await ProcessAsync(items, cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Cancelled — cleaning up partial work.");
}

Timeouts

A timeout is just cancellation on a timer — the same mechanism. A CancellationTokenSource can cancel itself automatically after a delay.

// Cancel automatically after 3 seconds
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(3));

try
{
    string result = await FetchAsync(url, cts.Token);
    Console.WriteLine(result);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Timed out after 3 seconds.");
}

You can also arm the timer after creating the source, or add a timeout to an existing task without threading a token through it, using WaitAsync (modern .NET):

// Arm later:
cts.CancelAfter(TimeSpan.FromSeconds(5));

// Add a timeout to any task:
try
{
    string result = await SomeTask.WaitAsync(TimeSpan.FromSeconds(2));
}
catch (TimeoutException)
{
    Console.WriteLine("The operation took too long.");
}

Linked Tokens

Sometimes an operation should stop if any of several conditions occurs — e.g. the user cancels or a timeout elapses or a parent operation is aborted. CreateLinkedTokenSource combines tokens: the linked token is cancelled when any of its sources is.

// One source for the user, one for a timeout
using var userCts = new CancellationTokenSource();
using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(10));

// Linked: cancels if the user cancels OR the 10s timeout fires
using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
    userCts.Token, timeoutCts.Token);

await DoWorkAsync(linkedCts.Token);   // honors both triggers

using var registration = token.Register(() => Console.WriteLine("Cancelling!"));

Exercise & Quiz

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));

try
{
    int reached = await CountSlowlyAsync(100, cts.Token);
    Console.WriteLine($"Finished at {reached}");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Stopped early (cancelled or timed out).");
}

static async Task<int> CountSlowlyAsync(int to, CancellationToken token)
{
    // TODO: loop 1..to, await Task.Delay(200, token), print each
    // return how far it got
    return 0;
}

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));

try
{
    int reached = await CountSlowlyAsync(100, cts.Token);
    Console.WriteLine($"Finished at {reached}");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Stopped early (cancelled or timed out).");
}

static async Task<int> CountSlowlyAsync(int to, CancellationToken token)
{
    int i = 0;
    for (i = 1; i <= to; i++)
    {
        token.ThrowIfCancellationRequested();   // optional explicit check
        await Task.Delay(200, token);           // cancellable wait
        Console.WriteLine(i);
    }
    return i - 1;
}

// Manual-cancel variant: start the task, then in another task Cancel() after 1s:
// _ = Task.Run(async () => { await Task.Delay(1000); cts.Cancel(); });

Summary

📚 Additional Resources

• Cancellation in managed threads — Microsoft Docs
• CancellationToken — API reference
• Task cancellation

🚀 What's Next?

You can start, await, and now stop async work. Next, we produce async data over time. In Lesson 3.2: Async Streams and Channels, you'll use IAsyncEnumerable and channels to stream results as they arrive.