C# Task: Task.Run, WhenAll, WhenAny, Cancellation and Threads

A Task is an object that stands for work in progress. It might be running on a thread pool thread, waiting on a timer, or waiting for a network reply; either way you can ask whether it is done, get its result, wait for it, or attach more work to it. async and await are the language syntax over tasks. This page covers the Task API itself, and threads.

Task.Run: work on the thread pool

Task.Run takes a lambda and queues it on the thread pool, a set of threads .NET keeps around so it does not create a new one for every job. It returns a Task, or a Task<T> if the lambda returns a value.

using System;
using System.Threading.Tasks;

class Program
{
    static int CountPrimes(int max)
    {
        int count = 0;
        for (int n = 2; n <= max; n++)
        {
            bool prime = true;
            for (int d = 2; d * d <= n; d++)
            {
                if (n % d == 0) { prime = false; break; }
            }
            if (prime) count++;
        }
        return count;
    }

    static void Main()
    {
        Task<int> task = Task.Run(() => CountPrimes(200000));
        Console.WriteLine("Started, completed yet: " + task.IsCompleted);

        int primes = task.Result;   // blocks until the task finishes
        Console.WriteLine("Primes up to 200,000: " + primes);
        Console.WriteLine("Status: " + task.Status);
    }
}

Output:

Started, completed yet: False
Primes up to 200,000: 17984
Status: RanToCompletion

Result blocks the calling thread until the task is done. That is acceptable in a console program's Main, but inside async code you would write int primes = await task;, which waits without blocking. The same applies to task.Wait() for a Task with no result.

Task.Run is for CPU-bound work: calculations that keep a core busy. For I/O, such as reading a file or calling a web API, use the async method the library already provides (File.ReadAllTextAsync, HttpClient.GetStringAsync) and await it directly. While the I/O is pending, an awaited async call holds no thread at all, so wrapping it in Task.Run gains nothing and only adds a hop through the thread pool. The case that does tie up a pool thread is Task.Run around a synchronous blocking call such as File.ReadAllText: that thread sits idle until the disk or network answers.

Several tasks at once: WhenAll

Split independent work into tasks, start them all, and combine the results with Task.WhenAll. On a machine with several cores the pieces run in parallel.

using System;
using System.Linq;
using System.Threading.Tasks;

class Program
{
    static long SumRange(int from, int to)
    {
        long sum = 0;
        for (int i = from; i < to; i++) sum += i % 7;
        return sum;
    }

    static void Main()
    {
        int chunks = 4, size = 5000000;

        Task<long>[] parts = Enumerable.Range(0, chunks)
            .Select(c => Task.Run(() => SumRange(c * size, (c + 1) * size)))
            .ToArray();

        long[] results = Task.WhenAll(parts).Result;
        Console.WriteLine("Parts: " + string.Join(", ", results));
        Console.WriteLine("Total: " + results.Sum());
    }
}

Output:

Parts: 14999995, 14999999, 15000003, 15000000
Total: 59999997

Each chunk works on its own range and returns its own sum, so the tasks share nothing and need no locking. WhenAll returns the results in the order of the tasks, however the threads happened to finish. When tasks do need to update shared state, see lock.

WhenAny and timeouts

Task.WhenAny completes when the first of its tasks does and returns that task. Racing the real work against Task.Delay gives a timeout:

using System;
using System.Threading.Tasks;

class Program
{
    static async Task<string> QueryServerAsync(string name, int ms)
    {
        await Task.Delay(ms);
        return name + " answered after " + ms + " ms";
    }

    static async Task RunAsync()
    {
        Task<string> fast = QueryServerAsync("fast mirror", 100);
        Task<string> slow = QueryServerAsync("main server", 800);
        Task<string> first = await Task.WhenAny(fast, slow);
        Console.WriteLine(await first);

        Task<string> work = QueryServerAsync("report service", 2000);
        Task timeout = Task.Delay(300);
        if (await Task.WhenAny(work, timeout) == timeout)
        {
            Console.WriteLine("Timed out after 300 ms");
        }
    }

    static void Main()
    {
        RunAsync().GetAwaiter().GetResult();
    }
}

Output:

fast mirror answered after 100 ms
Timed out after 300 ms

WhenAny returns the winning task itself, not its result, so you await it again to get the value (or the exception, if it failed). Note that the losing tasks keep running; WhenAny does not stop them. To actually stop the slow work, cancel it with a token as shown below. In .NET 6 and later, await work.WaitAsync(TimeSpan.FromMilliseconds(300)) expresses the same timeout in one call.

Continuations with ContinueWith

Before await, the way to run code after a task finished was ContinueWith. You will still see it in older code:

using System;
using System.Threading.Tasks;

class Program
{
    static void Main()
    {
        Task<int> load = Task.Run(() => 21);

        Task<string> report = load
            .ContinueWith(t => t.Result * 2)
            .ContinueWith(t => "Report total: " + t.Result);

        Console.WriteLine(report.Result);
    }
}

Output:

Report total: 42

Each continuation receives the previous task and runs when it completes. await does the same thing with far less ceremony, handles exceptions naturally, and returns to the right context, so prefer it in new code. ContinueWith runs even when the previous task failed or was cancelled, so older code has to inspect t.IsFaulted or pass TaskContinuationOptions to avoid calling .Result on a failed task.

Cancellation with CancellationToken

Tasks are cancelled cooperatively. A CancellationTokenSource issues a token; the code doing the work checks the token and stops itself. Nothing is forcibly aborted.

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task<int> ProcessOrdersAsync(int count, CancellationToken token)
    {
        int done = 0;
        for (int i = 0; i < count; i++)
        {
            token.ThrowIfCancellationRequested();   // stop between items
            await Task.Delay(100, token);           // pass the token on
            done++;
        }
        return done;
    }

    static async Task RunAsync()
    {
        using (var cts = new CancellationTokenSource())
        {
            cts.CancelAfter(350);                   // cancel in 350 ms
            try
            {
                int n = await ProcessOrdersAsync(10, cts.Token);
                Console.WriteLine("Processed " + n);
            }
            catch (OperationCanceledException)
            {
                Console.WriteLine("Cancelled before finishing all 10 orders");
            }
        }

        using (var cts = new CancellationTokenSource())
        {
            int n = await ProcessOrdersAsync(3, cts.Token); // never cancelled
            Console.WriteLine("Processed " + n);
        }
    }

    static void Main()
    {
        RunAsync().GetAwaiter().GetResult();
    }
}

Output:

Cancelled before finishing all 10 orders
Processed 3

The token is passed down through every layer, and async APIs such as Task.Delay, HttpClient and database calls accept it too, so a cancellation stops them mid-wait. Catch OperationCanceledException; the TaskCanceledException that some APIs throw derives from it. CancellationTokenSource is IDisposable, hence the using.

Thread vs Task

A Thread is an operating system thread you create yourself. It is heavier: each has its own stack (1 MB by default on Windows), starting one takes measurable time, and it gives you no result or exception handling.

using System;
using System.Threading;

class Program
{
    static void Main()
    {
        int result = 0;
        var worker = new Thread(() =>
        {
            Thread.Sleep(100);
            result = 6 * 7;
        });
        worker.Start();
        Console.WriteLine("Thread started");
        worker.Join();          // wait for it to finish
        Console.WriteLine("Result: " + result);
    }
}

Output:

Thread started
Result: 42

Reach for Thread only when you need something the pool does not give you: a long-running loop that should never borrow a pool thread, a specific priority, or a single-threaded apartment for COM. For long-running tasks, Task.Factory.StartNew(work, TaskCreationOptions.LongRunning) gets a dedicated thread while keeping the task API.

Parallel.For and Parallel.ForEach

For "do this to every item, using all cores", System.Threading.Tasks.Parallel is simpler than creating tasks by hand. It partitions the range across threads and returns when all iterations are done:

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static void Main()
    {
        int[] sizes = { 120, 340, 90, 410, 275, 60 };
        long totalPixels = 0;

        Parallel.For(0, sizes.Length, i =>
        {
            long pixels = (long)sizes[i] * sizes[i];      // "process" image i
            Interlocked.Add(ref totalPixels, pixels);      // thread-safe add
            Console.WriteLine("image " + i + " on thread " + Thread.CurrentThread.ManagedThreadId);
        });

        Console.WriteLine("Total pixels: " + totalPixels);
    }
}

Example output:

image 4 on thread 7
image 3 on thread 6
image 5 on thread 8
image 0 on thread 1
image 1 on thread 4
image 2 on thread 5
Total pixels: 385425

The per-image lines come out in whatever order the threads ran them, and the thread IDs vary from run to run; only the total is fixed. That is the nature of parallel loops: iterations must not depend on each other's order, and any shared state needs synchronization (Interlocked.Add here). Parallel.ForEach does the same over any collection, and .NET 6 adds Parallel.ForEachAsync for async bodies.

Common mistakes

• .Result or .Wait() inside async code. Blocks a thread and can deadlock in UI apps; await instead.
• Catching the original exception type around .Result. Failures arrive wrapped in AggregateException; await unwraps them.
• Fire and forget. Task.Run(...) without awaiting or storing the task loses its exceptions.
• Task.Run around I/O. Around an async method it only adds a thread pool hop; around a blocking method such as File.ReadAllText it parks a pool thread for the whole wait. Await the async I/O method directly.
• Ignoring the token. Passing a CancellationToken does nothing unless the work checks it.
• Unsynchronized shared state in parallel code. Use Interlocked, lock, or give each task its own data.