Docs ejecutables de C#: Tareas

Q: ¿Qué es un Task en C#?

Un Task representa una operación que puede terminar en el futuro: código ejecutándose en el pool de hilos, un temporizador, una petición de E/S. Se puede esperar, indica si terminó, falló o se canceló, y Task además lleva un resultado. Las tareas son la pieza sobre la que se construyen async/await.

Q: ¿Qué diferencia hay entre un Task y un Thread en C#?

Un Thread es un hilo del sistema operativo que creas y gestionas tú, con su propia pila; es caro de iniciar y no devuelve ningún valor. Un Task describe un trabajo, y Task.Run lo programa en un pool compartido de hilos reutilizables; puede devolver un resultado, propagar excepciones, cancelarse y esperarse. Usa tareas salvo que necesites un hilo dedicado de larga vida con una configuración especial.

Q: ¿Cómo cancelo un Task en C#?

Crea un CancellationTokenSource, pasa su Token al trabajo y llama a Cancel() (o a CancelAfter(timeout)) sobre el origen. El trabajo debe colaborar: comprobar token.IsCancellationRequested o llamar a token.ThrowIfCancellationRequested() en su bucle, y pasar el token a las API async como Task.Delay. Esperar una tarea cancelada lanza OperationCanceledException.

Q: ¿Qué diferencia hay entre Task.WhenAll y Task.WhenAny?

Task.WhenAll termina cuando han terminado todas las tareas y te da todos los resultados. Task.WhenAny termina en cuanto termina la primera tarea y devuelve esa tarea. WhenAny es la forma habitual de añadir un tiempo límite: haz competir el trabajo con un Task.Delay.

Q: ¿Por qué Task.Result lanza AggregateException?

.Result y .Wait() envuelven cualquier fallo en una AggregateException, porque en general una tarea puede contener varias excepciones. await la desenvuelve y vuelve a lanzar directamente la primera excepción interna, lo que es un motivo para preferir await. Si tienes que bloquear, .GetAwaiter().GetResult() también lanza la excepción original.

Un Task es un objeto que representa un trabajo en curso. Puede estar ejecutándose en un hilo del pool, esperando a un temporizador o esperando una respuesta de la red; en cualquier caso, puedes preguntar si ha terminado, obtener su resultado, esperarlo o añadirle más trabajo. async y await son la sintaxis del lenguaje sobre las tareas. Esta página trata la propia API de Task, y los hilos.

Task.Run: trabajo en el pool de hilos

Task.Run recibe una lambda y la pone en cola en el pool de hilos, un conjunto de hilos que .NET mantiene disponibles para no crear uno nuevo para cada trabajo. Devuelve un Task, o un Task<T> si la lambda devuelve un valor.

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);
    }
}

Salida:

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

Result bloquea el hilo que llama hasta que la tarea termina. Eso es aceptable en el Main de un programa de consola, pero dentro de código async escribirías int primes = await task;, que espera sin bloquear. Lo mismo vale para task.Wait() en un Task sin resultado.

Task.Run es para trabajo que depende de la CPU: cálculos que mantienen ocupado un núcleo. Para la E/S, como leer un archivo o llamar a una API web, usa el método async que ya ofrece la biblioteca (File.ReadAllTextAsync, HttpClient.GetStringAsync) y espéralo directamente con await. Mientras la E/S está pendiente, una llamada async esperada no retiene ningún hilo, así que envolverla en Task.Run no aporta nada y solo añade un salto por el pool de hilos. Lo que sí ocupa un hilo del pool es Task.Run alrededor de una llamada síncrona bloqueante como File.ReadAllText: ese hilo queda parado hasta que responden el disco o la red.

Varias tareas a la vez: WhenAll

Divide el trabajo independiente en tareas, inícialas todas y combina los resultados con Task.WhenAll. En una máquina con varios núcleos, las partes se ejecutan en paralelo.

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());
    }
}

Salida:

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

Cada trozo trabaja sobre su propio rango y devuelve su propia suma, así que las tareas no comparten nada y no necesitan bloqueos. WhenAll devuelve los resultados en el orden de las tareas, terminen los hilos como terminen. Cuando las tareas sí necesitan actualizar un estado compartido, consulta lock.

WhenAny y tiempos límite

Task.WhenAny termina cuando termina la primera de sus tareas y devuelve esa tarea. Hacer competir el trabajo real con Task.Delay da un tiempo límite:

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();
    }
}

Salida:

fast mirror answered after 100 ms
Timed out after 300 ms

WhenAny devuelve la propia tarea ganadora, no su resultado, así que vuelves a hacer await sobre ella para obtener el valor (o la excepción, si falló). Ten en cuenta que las tareas perdedoras siguen ejecutándose; WhenAny no las detiene. Para detener de verdad el trabajo lento, cancélalo con un token como se muestra más abajo. En .NET 6 y posteriores, await work.WaitAsync(TimeSpan.FromMilliseconds(300)) expresa el mismo tiempo límite en una sola llamada.

Continuaciones con ContinueWith

Antes de await, la forma de ejecutar código después de que terminara una tarea era ContinueWith. Todavía lo verás en código antiguo:

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);
    }
}

Salida:

Report total: 42

Cada continuación recibe la tarea anterior y se ejecuta cuando esta termina. await hace lo mismo con mucha menos ceremonia, maneja las excepciones de forma natural y vuelve al contexto correcto, así que prefiérelo en el código nuevo. ContinueWith se ejecuta incluso cuando la tarea anterior falló o se canceló, así que el código antiguo tiene que revisar t.IsFaulted o pasar TaskContinuationOptions para no llamar a .Result sobre una tarea fallida.

Cancelación con CancellationToken

Las tareas se cancelan de forma cooperativa. Un CancellationTokenSource emite un token; el código que hace el trabajo comprueba el token y se detiene él mismo. Nada se aborta a la fuerza.

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();
    }
}

Salida:

Cancelled before finishing all 10 orders
Processed 3

El token se pasa a través de todas las capas, y las API async como Task.Delay, HttpClient y las llamadas a bases de datos también lo aceptan, así que una cancelación las detiene en mitad de la espera. Captura OperationCanceledException; la TaskCanceledException que lanzan algunas API deriva de ella. CancellationTokenSource es IDisposable, de ahí el using.

Thread frente a Task

Un Thread es un hilo del sistema operativo que creas tú. Es más pesado: cada uno tiene su propia pila (1 MB por defecto en Windows), iniciarlo lleva un tiempo apreciable y no te da ni resultado ni manejo de excepciones.

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);
    }
}

Salida:

Thread started
Result: 42

	`Thread`	`Task`
Se ejecuta en	Un hilo del SO nuevo y dedicado	Un hilo del pool (o ningún hilo, en la E/S)
Coste de inicio	Alto	Bajo
Valor de resultado	No, comparte una variable	`Task<T>.Result` / `await`
Excepciones	Las no manejadas hacen caer el proceso	Se guardan en la tarea y se vuelven a lanzar en `await`
Cancelación	Indicadores manuales	`CancellationToken` incorporado
Esperarlo	`Join()`	`await`, `Wait()`, `WhenAll`

Recurre a Thread solo cuando necesitas algo que el pool no te da: un bucle de larga duración que nunca debe tomar prestado un hilo del pool, una prioridad concreta o un apartamento de un solo hilo para COM. Para tareas de larga duración, Task.Factory.StartNew(work, TaskCreationOptions.LongRunning) obtiene un hilo dedicado conservando la API de tareas.

Parallel.For y Parallel.ForEach

Para "haz esto con cada elemento usando todos los núcleos", System.Threading.Tasks.Parallel es más sencillo que crear tareas a mano. Reparte el rango entre hilos y vuelve cuando todas las iteraciones han terminado:

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);
    }
}

Salida de ejemplo:

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

Las líneas de cada imagen salen en el orden en que los hilos las ejecutaron, y los ID de hilo cambian de una ejecución a otra; solo el total es fijo. Así son los bucles paralelos: las iteraciones no deben depender del orden de las demás, y cualquier estado compartido necesita sincronización (Interlocked.Add aquí). Parallel.ForEach hace lo mismo sobre cualquier colección, y .NET 6 añade Parallel.ForEachAsync para cuerpos async.

Errores comunes

.Result o .Wait() dentro de código async. Bloquea un hilo y puede provocar interbloqueos en aplicaciones con interfaz; usa await.
Capturar el tipo de excepción original alrededor de .Result. Los fallos llegan envueltos en AggregateException; await los desenvuelve.
Lanzar y olvidar. Task.Run(...) sin esperar ni guardar la tarea pierde sus excepciones.
Task.Run alrededor de E/S. Alrededor de un método async solo añade un salto por el pool de hilos; alrededor de un método bloqueante como File.ReadAllText retiene un hilo del pool durante toda la espera. Espera con await directamente el método de E/S async.
Ignorar el token. Pasar un CancellationToken no sirve de nada salvo que el trabajo lo compruebe.
Estado compartido sin sincronizar en código paralelo. Usa Interlocked, lock o da a cada tarea sus propios datos.

Preguntas frecuentes

¿Qué es un Task en C#?

Un Task representa una operación que puede terminar en el futuro: código ejecutándose en el pool de hilos, un temporizador, una petición de E/S. Se puede esperar, indica si terminó, falló o se canceló, y Task<T> además lleva un resultado. Las tareas son la pieza sobre la que se construyen async/await.

¿Qué diferencia hay entre un Task y un Thread en C#?

Un Thread es un hilo del sistema operativo que creas y gestionas tú, con su propia pila; es caro de iniciar y no devuelve ningún valor. Un Task describe un trabajo, y Task.Run lo programa en un pool compartido de hilos reutilizables; puede devolver un resultado, propagar excepciones, cancelarse y esperarse. Usa tareas salvo que necesites un hilo dedicado de larga vida con una configuración especial.

¿Cuándo debo usar Task.Run?

Para el trabajo que depende de la CPU y que quieres sacar del hilo actual: procesar imágenes, un cálculo grande, parsear en memoria un archivo grande, sobre todo para mantener una interfaz receptiva. No envuelvas la E/S en Task.Run: los métodos de E/S async como ReadAllTextAsync ya liberan el hilo mientras esperan.

¿Cómo cancelo un Task en C#?

Crea un CancellationTokenSource, pasa su Token al trabajo y llama a Cancel() (o a CancelAfter(timeout)) sobre el origen. El trabajo debe colaborar: comprobar token.IsCancellationRequested o llamar a token.ThrowIfCancellationRequested() en su bucle, y pasar el token a las API async como Task.Delay. Esperar una tarea cancelada lanza OperationCanceledException.

¿Qué diferencia hay entre Task.WhenAll y Task.WhenAny?

Task.WhenAll termina cuando han terminado todas las tareas y te da todos los resultados. Task.WhenAny termina en cuanto termina la primera tarea y devuelve esa tarea. WhenAny es la forma habitual de añadir un tiempo límite: haz competir el trabajo con un Task.Delay.

¿Por qué Task.Result lanza AggregateException?

.Result y .Wait() envuelven cualquier fallo en una AggregateException, porque en general una tarea puede contener varias excepciones. await la desenvuelve y vuelve a lanzar directamente la primera excepción interna, lo que es un motivo para preferir await. Si tienes que bloquear, .GetAwaiter().GetResult() también lanza la excepción original.

Conceptos relacionados