Skip to content

9. Programação assíncrona

O capítulo anterior apresentou as threads: podemos executar vários trechos de código “ao mesmo tempo”, sincronizá-los e atribuir tarefas ao pool de threads. Este capítulo, que não constava do curso de 2008, trata de uma questão relacionada, porém distinta: como escrever um programa que espera por muito tempo (pelo disco, pela rede ou por um banco de dados) sem bloquear threads durante essas esperas. A resposta, no .NET, está em duas palavras-chave da linguagem C#, [async] e [await], e em um tipo, [Task]. Elas estão por toda parte hoje: os próximos capítulos as usarão para acessar bancos de dados ([OpenAsync], [ExecuteReaderAsync], [ToListAsync], [SaveChangesAsync]), escrever servidores TCP ([AcceptTcpClientAsync]), clientes web ([HttpClient]) e serviços web com ASP.NET Core.

Todos os exemplos deste capítulo são aplicações de arquivo único ([async-01.cs], [async-02.cs]…) executadas com [dotnet run async-NN.cs] na pasta [09-async]. Muitos deles medem durações com um cronômetro ([Stopwatch]): os milissegundos exibidos variam de uma execução para outra e de uma máquina para outra (os exemplos foram executados em uma máquina de dois processadores). O que importa são as ordens de grandeza: 1 segundo ou 3 segundos, 300 ms ou 0 ms.

9.1. Por que a assincronia

9.1.1. Operações que esperam

Um programa realiza dois tipos de trabalho:

  • tarefas de cálculo, que ocupam o processador: ordenar uma lista, calcular um imposto, analisar um texto;
  • entrada/saída (E/S), que consiste essencialmente em esperar por um dispositivo periférico: ler um arquivo do disco, enviar uma requisição a um servidor web e esperar sua resposta, executar uma consulta SQL em um servidor de banco de dados.

As ordens de grandeza são muito diferentes. Um processador executa alguns bilhões de instruções por segundo. Uma operação de leitura em um disco (SSD) leva da ordem de um décimo de milissegundo; uma viagem de ida e volta em uma rede local leva uma fração de milissegundo; uma viagem de ida e volta até um servidor do outro lado do país leva algumas dezenas de milissegundos; e uma requisição SQL um pouco mais complexa pode às vezes levar vários segundos. Durante essas esperas, o processador poderia ter executado milhões de instruções.

Quando um programa lê uma linha em uma conexão de rede usando um método síncrono (bloqueante), a thread que faz essa leitura fica bloqueada: ela não faz nada, mas continua existindo. Ela ocupa memória (sua pilha, da ordem de um megabyte), é reconhecida pelo sistema operacional e, principalmente, deixa de estar disponível para fazer qualquer outra coisa. Isso não é um problema em um pequeno programa de console que faz uma coisa de cada vez. Torna-se um problema muito maior em duas situações:

  • em um servidor: cada cliente atendido por uma thread bloqueada imobiliza essa thread. O curso de 2008 já explicava isso na conclusão de sua discussão sobre o cliente TCP assíncrono: se o pool de threads tem N threads e todas as N estão executando uma operação bloqueante, não resta nenhuma thread disponível para um novo cliente. Um servidor web moderno atende milhares de requisições simultâneas com apenas algumas dezenas de threads: isso é possível porque suas threads nunca ficam bloqueadas em operações de E/S;
  • em uma interface gráfica de usuário: uma única thread (a thread de UI) trata os cliques e redesenha as janelas. Se ela fica bloqueada por um download, a janela congela.

A assincronia consiste em iniciar a operação de E/S, liberar a thread enquanto ela é executada (o hardware e o sistema operacional não precisam dela para transferir os dados) e retomar o trabalho quando a operação termina, possivelmente em outra thread:

Image

  • Em [1], a thread T1 inicia a E/S e permanece bloqueada até que ela termine;
  • em [2], a thread T1 inicia a E/S e retorna ao pool de threads, onde pode atender outras requisições. Quando a operação de E/S termina, o sistema avisa o .NET, que faz uma thread do pool, T2 (ou T1, se estiver disponível), executar o restante do processamento.

O programa [async-01.cs] mede a diferença em 100 operações, cada uma das quais espera por um segundo (a espera simula E/S). Ele usa instruções que explicaremos mais adiante neste capítulo ([Task.Run], [Task.Delay], [await]); aqui, interessam-nos apenas os resultados.

// por que assincronia: 100 operações que esperam um segundo cada
// (uma espera simula uma E/S: leitura de disco, requisição de rede, consulta SQL…)
using System.Diagnostics;

const int nbOperations = 100;
Console.WriteLine($"{nbOperations} operations of one second, {Environment.ProcessorCount} processors");

// 1 - uma thread por operação, cada thread fica bloqueada durante a espera
var stopwatch = Stopwatch.StartNew();
var threads = new Thread[nbOperations];
for (int i = 0; i < nbOperations; i++)
{
    threads[i] = new Thread(() => Thread.Sleep(1000));
    threads[i].Start();
}
Display("1 - one thread per operation", ProcessThreads());
foreach (var thread in threads)
{
    thread.Join();
}
Display("    end");

// 2 - as operações são entregues ao pool de threads, mas o bloqueiam
stopwatch.Restart();
var tasks = new Task[nbOperations];
for (int i = 0; i < nbOperations; i++)
{
    tasks[i] = Task.Run(() => Thread.Sleep(1000));
}
Display("2 - thread pool, blocking waits", ProcessThreads());
Task.WaitAll(tasks);
Display("    end");

// 3 - esperas assíncronas: nenhuma thread fica bloqueada durante a espera
stopwatch.Restart();
for (int i = 0; i < nbOperations; i++)
{
    tasks[i] = Task.Delay(1000);
}
Display("3 - asynchronous waits", ProcessThreads());
await Task.WhenAll(tasks);
Display("    end");

// número de threads do processo, meio segundo depois do lançamento das operações
int ProcessThreads()
{
    if (stopwatch.ElapsedMilliseconds < 500)
    {
        Thread.Sleep(500 - (int)stopwatch.ElapsedMilliseconds);
    }
    using var process = Process.GetCurrentProcess();
    return process.Threads.Count;
}

// exibição do tempo decorrido e, se informado, do número de threads
void Display(string message, int? nbThreads = null)
{
    string threadsInfo = nbThreads is null ? "" : $", {nbThreads,3} threads in the process";
    Console.WriteLine($"{message,-42} : {stopwatch.ElapsedMilliseconds,5} ms{threadsInfo}");
}

Resultados:

1
2
3
4
5
6
7
8
> dotnet run async-01.cs
100 operations of one second, 2 processors
1 - one thread per operation               :   526 ms, 110 threads in the process
    end                                    :  1012 ms
2 - thread pool, blocking waits            :   501 ms,  13 threads in the process
    end                                    : 24007 ms
3 - asynchronous waits                     :   501 ms,  17 threads in the process
    end                                    :  1002 ms

Comentários:

  • linhas 8–21: a solução do curso de 2008, uma thread por operação. Cada thread executa [Thread.Sleep(1000)]: ela fica bloqueada por um segundo. As 100 esperas ocorrem simultaneamente, e o processo inteiro leva exatamente um segundo (linha 4), mas ao custo de 100 threads adicionais: o processo passa a ter mais de 100 threads (linha 3). Com 10.000 operações, seriam necessárias 10.000 threads;
  • linhas 23–31: as operações são delegadas ao pool de threads ([Task.Run]), apresentado no capítulo anterior. O pool começa com tantas threads quanto processadores (2, neste caso) e só acrescenta outras gradualmente quando todas estão ocupadas, pois supõe que suas threads estão fazendo cálculos e que não há necessidade de ter muito mais threads do que processadores. Mas aqui suas threads não estão calculando: estão ociosas. As operações esperam por uma thread livre, e o processo inteiro leva… mais de vinte segundos (linha 6). Isso é conhecido como “inanição do pool de threads” (thread pool starvation), a falha mais comum em servidores que combinam pools de threads com E/S bloqueante;
  • linhas 34–41: as esperas são assíncronas ([Task.Delay] em vez de [Thread.Sleep]). Nenhuma thread fica bloqueada durante a espera: um temporizador do sistema acordará o .NET após um segundo. O processo inteiro dura um segundo, e o número de threads não aumenta (as threads exibidas na linha 7 são as que o pool criou durante a etapa 2; elas estão ociosas);
  • linha 51: [Process.GetCurrentProcess()] dá acesso ao processo em execução; sua propriedade [Threads] é a coleção de suas threads (as do .NET e as do sistema).

Guardemos a lição: para esperar, não se deve bloquear uma thread. A assincronia não torna a E/S mais rápida; ela permite tratar muitas operações de E/S simultaneamente com poucas threads e manter disponíveis as threads de que a aplicação precisa (a thread da GUI, as threads do pool de um servidor).

9.1.2. Três modelos sucessivos

O .NET propôs três maneiras de escrever código assíncrono. Os dois primeiros ainda são encontrados em código legado e em artigos mais antigos, por isso é útil reconhecê-los.

Modelo
Origem
Princípio
APM (“Asynchronous Programming Model”)
.NET 1.0 (2002)
um par de métodos: [BeginXxx] e [EndXxx]. [BeginXxx] inicia a operação e recebe um método de retorno de chamada ([AsyncCallback]); o método de retorno de chamada, executado por uma thread do pool ao final da operação, chama [EndXxx] para obter o resultado ou a exceção. Exemplo: [Socket.BeginConnect] / [EndConnect], usados pelo cliente TCP assíncrono do curso de 2008.
EAP (“Event-based Asynchronous Pattern”)
.NET 2.0 (2005)
um método [XxxAsync] que inicia a operação e um evento [XxxCompleted] disparado ao seu término. Exemplos: [WebClient.DownloadStringAsync] e [DownloadStringCompleted], a classe [BackgroundWorker] (eventos [DoWork], [ProgressChanged], [RunWorkerCompleted]) estudada no curso de 2008.
TAP (“Task-based Asynchronous Pattern”)
.NET 4.0 (2010), C# 5 (2012)
um método [XxxAsync] que retorna uma tarefa ([Task] ou [Task<T>]) que representa a operação em andamento. O código chamador espera pela tarefa usando a palavra-chave [await]. Este é o modelo atual, o único usado no restante do curso.

Os padrões APM e EAP compartilham a mesma falha: o código é fragmentado. O que naturalmente se lê como “conectar, depois ler, depois exibir” vira um método que inicia a conexão, um método de retorno de chamada que começa a leitura e outro método de retorno de chamada que exibe os dados; as variáveis precisam ser compartilhadas entre esses métodos, as exceções são tratadas em lugares diferentes, e um simples laço (“ler enquanto houver dados”) vira um método de retorno de chamada que chama a si mesmo recursivamente, como o método de leitura ([lecture]) do curso de 2008. O padrão TAP, junto com [async] e [await], permite escrever código assíncrono com o aspecto de código síncrono.

O programa [async-02.cs] escreve o mesmo cliente TCP segundo os dois modelos extremos, APM e TAP. Ele também contém um pequeno servidor, executado por uma thread, que responde a dois clientes (a programação de rede será tratada em detalhes no Capítulo 12; por ora, basta saber que um cliente se conecta ao servidor e lê a mensagem que o servidor lhe envia).

// o mesmo cliente TCP escrito com o modelo APM de 2008 e depois com o modelo TAP atual
using System.Net;
using System.Net.Sockets;
using System.Text;

const int port = 27500;
// um servidor mínimo, executado por uma thread: atende dois clientes e depois para
var listener = new TcpListener(IPAddress.Loopback, port);
listener.Start();
var server = new Thread(() =>
{
    for (int i = 1; i <= 2; i++)
    {
        using Socket service = listener.AcceptSocket();
        // o servidor demora para responder
        Thread.Sleep(500);
        service.Send(Encoding.UTF8.GetBytes($"Hello client no. {i}"));
    }
    listener.Stop();
});
server.Start();
Display("start of the program");

// 1 - o modelo APM (Asynchronous Programming Model): métodos BeginXxx / EndXxx e métodos de callback
var end = new ManualResetEventSlim(false);
byte[] buffer = new byte[1024];
var client = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);
// iniciamos a conexão, informando o método a chamar de volta quando ela terminar
client.BeginConnect(IPAddress.Loopback, port, Connected, client);
Display("APM: connection launched, the program goes on");
// a thread principal não tem mais nada a fazer: espera o sinal do último método de callback
end.Wait();

// método de callback nº 1: a conexão foi estabelecida
void Connected(IAsyncResult result)
{
    // recuperamos o objeto passado como último parâmetro de BeginConnect
    var socket = (Socket)result.AsyncState!;
    // encerramos a operação (é EndConnect que lançaria a exceção em caso de falha)
    socket.EndConnect(result);
    Display("APM: connected, read launched");
    // iniciamos a leitura da resposta do servidor com outro método de callback
    socket.BeginReceive(buffer, 0, buffer.Length, SocketFlags.None, Received, socket);
}

// método de callback nº 2: os dados chegaram
void Received(IAsyncResult result)
{
    var socket = (Socket)result.AsyncState!;
    int nbBytes = socket.EndReceive(result);
    Display($"APM: received [{Encoding.UTF8.GetString(buffer, 0, nbBytes)}]");
    socket.Close();
    // notificamos a thread principal
    end.Set();
}

// 2 - o modelo TAP (Task-based Asynchronous Pattern): XxxAsync e await
using (var client2 = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp))
{
    await client2.ConnectAsync(IPAddress.Loopback, port);
    Display("TAP: connected, read launched");
    int nbBytes = await client2.ReceiveAsync(buffer);
    Display($"TAP: received [{Encoding.UTF8.GetString(buffer, 0, nbBytes)}]");
}
server.Join();

// exibição prefixada pelo número da thread que a executa
static void Display(string message)
{
    Console.WriteLine($"[thread {Environment.CurrentManagedThreadId,2}] {message}");
}

Resultados:

1
2
3
4
5
6
7
> dotnet run async-02.cs
[thread  1] start of the program
[thread  1] APM: connection launched, the program goes on
[thread  6] APM: connected, read launched
[thread  6] APM: received [Hello client no. 1]
[thread  6] TAP: connected, read launched
[thread  6] TAP: received [Hello client no. 2]

Comentários:

  • linhas 8–21: o servidor. Ele escuta na porta 27500 da máquina local ([IPAddress.Loopback], isto é, 127.0.0.1), aceita duas conexões, uma após a outra, e envia a cada cliente uma mensagem de boas-vindas após meio segundo;
  • linhas 24–54: o cliente escrito segundo o padrão APM, como no curso de 2008:
    • linha 29: [BeginConnect] inicia a conexão e devolve imediatamente o controle (linha 3 dos resultados). Seus dois últimos parâmetros são o método de retorno de chamada a ser invocado ao final da conexão, [Connected], e um objeto arbitrário que esse método encontrará na propriedade [AsyncState] de seu parâmetro [IAsyncResult]: neste caso, o próprio socket;
    • linha 32: a thread principal não tem mais nada a fazer. Para impedir que o programa termine antes de a troca ser concluída, ela espera por um sinal que será enviado pelo último método de retorno de chamada: um objeto [ManualResetEventSlim], cujo método [Wait] bloqueia a thread que o chama até que outra thread chame seu método [Set] (é uma versão leve das barreiras [AutoResetEvent] vistas com as threads);
    • linhas 35–43: o método de retorno de chamada da conexão. Ele deve chamar [EndConnect] com o parâmetro recebido: essa chamada conclui a operação e lançaria uma exceção se a conexão tivesse falhado. Em seguida, ele inicia a operação de leitura com [BeginReceive], especificando um segundo método de retorno de chamada, [Received];
    • linhas 47–54: o retorno de chamada de leitura obtém o número de bytes recebidos com [EndReceive], exibe a mensagem, fecha o socket e libera a thread principal;
    • os resultados mostram que os métodos de retorno de chamada são executados por uma thread diferente da principal (uma thread do pool, não a thread 1);
  • linhas 57–65: o mesmo cliente usando o modelo TAP. [ConnectAsync] e [ReceiveAsync] retornam tarefas, e [await] espera que elas terminem sem bloquear a thread: o código se lê de cima para baixo como um código síncrono; as variáveis são variáveis locais comuns; não há métodos de retorno de chamada nem sinais para gerenciar. A thread que executa o restante do código geralmente não é mais a thread 1: explicaremos por quê na seção “Qual thread executa o restante?”;
  • linha 68: cada exibição é prefixada com o número da thread que a executa, [Environment.CurrentManagedThreadId].

Não é necessário memorizar o padrão APM. Se você precisar usar uma biblioteca mais antiga que só oferece esse padrão, o método [Task.Factory.FromAsync] converte um par [BeginXxx] / [EndXxx] em um método que retorna uma [Task]; e veremos na seção sobre [TaskCompletionSource] como converter uma API baseada em eventos (modelo EAP) em uma tarefa.

9.2. Tarefas: Task e Task<T>

Uma tarefa é um objeto que representa uma operação em andamento ou concluída:

  • [Task] representa uma operação que não retorna resultado;
  • [Task<T>] representa uma operação que retornará um resultado do tipo [T]. [Task<T>] deriva de [Task].

Uma tarefa não é uma thread. Uma tarefa pode ser executada por uma thread do pool (como é o caso das tarefas criadas por [Task.Run]), mas muitas tarefas não são executadas por nenhuma thread: a tarefa retornada por [Task.Delay(1000)] é simplesmente “concluída” por um temporizador após um segundo; a tarefa retornada por [ReceiveAsync] é concluída quando o sistema sinaliza que dados chegaram. Uma tarefa é uma promessa de resultado, que pode ser consultada (terminou? teve êxito?) e aguardada.

O programa [async-03.cs] demonstra as principais maneiras de criar e aguardar uma tarefa:

// tarefas: criação, espera, status, resultado, continuação

// 1 - Task.Run entrega um processamento ao pool de threads e retorna uma tarefa Task<T>
Task<long> task1 = Task.Run(() =>
{
    // um cálculo de algumas décimas de segundo
    long sum = 0;
    for (int i = 1; i <= 200_000_000; i++)
    {
        sum += i % 7;
    }
    return sum;
});
Console.WriteLine($"task1 launched, status: {task1.Status}");
// await suspende o programa até o fim da tarefa e retorna seu resultado
long result = await task1;
Console.WriteLine($"task1 finished, status: {task1.Status}, result: {result}");

// 2 - Task.Delay retorna uma tarefa que termina após um atraso, sem ocupar uma thread
Task task2 = Task.Delay(300);
Console.WriteLine($"task2 launched, status: {task2.Status}");
await task2;
Console.WriteLine($"task2 finished, status: {task2.Status}");

// 3 - tarefas que já estão concluídas
Task<int> task3 = Task.FromResult(42);
Task task4 = Task.CompletedTask;
Console.WriteLine($"task3: status {task3.Status}, result {await task3} ; task4: status {task4.Status}");

// 4 - uma tarefa que falha: await relança sua exceção
Task<int> task5 = Task.Run(() => int.Parse("abc"));
try
{
    await task5;
}
catch (FormatException e)
{
    Console.WriteLine($"task5: status {task5.Status}, {e.GetType().Name}: {e.Message}");
}

// 5 - as formas bloqueantes Wait() e Result: a thread atual fica bloqueada durante a espera
Task<string> task6 = Task.Run(() =>
{
    Thread.Sleep(300);
    return "done";
});
task6.Wait();
Console.WriteLine($"task6: Wait() then Result = {task6.Result}");

// 6 - uma continuação: o que fazer quando a tarefa terminar
Task<int> task7 = Task.Delay(300).ContinueWith(t => 2 * 21);
Console.WriteLine($"task7: result of the continuation = {await task7}");

// 7 - IsCompleted, IsCompletedSuccessfully, IsFaulted, IsCanceled
Console.WriteLine($"task1: IsCompletedSuccessfully={task1.IsCompletedSuccessfully}, task5: IsCompleted={task5.IsCompleted}, IsFaulted={task5.IsFaulted}");
Console.WriteLine($"task5.Exception: {task5.Exception?.GetType().Name}, {task5.Exception?.InnerException?.GetType().Name}");

Resultados:

> dotnet run async-03.cs
task1 launched, status: WaitingToRun
task1 finished, status: RanToCompletion, result: 599999998
task2 launched, status: WaitingForActivation
task2 finished, status: RanToCompletion
task3: status RanToCompletion, result 42 ; task4: status RanToCompletion
task5: status Faulted, FormatException: The input string 'abc' was not in a correct format.
task6: Wait() then Result = done
task7: result of the continuation = 42
task1: IsCompletedSuccessfully=True, task5: IsCompleted=True, IsFaulted=True
task5.Exception: AggregateException, FormatException

Comentários:

  • linhas 4–12: [Task.Run] atribui uma função ao pool de threads e retorna imediatamente uma tarefa que representa sua execução. A função retorna um [long], portanto a tarefa é do tipo [Task<long>]. [Task.Run] é a ferramenta para os cálculos a serem executados em segundo plano; ela não deve ser usada para “tornar assíncrona” uma operação de E/S bloqueante (que foi o que a etapa 2 de [async-01.cs] fez);
  • linha 14: a propriedade [Status] retorna o estado da tarefa. Imediatamente após ser iniciada, a tarefa fica aqui esperando que uma thread do pool a assuma ([WaitingToRun]); dependendo da carga da máquina, também é possível ver [Running] (em execução);
  • linha 16: [await task1] espera que a tarefa termine sem bloquear a thread e retorna seu resultado, que neste caso é do tipo [long]. A expressão [await t] é do tipo [T] se [t] for do tipo [Task<T>], e não tem valor se [t] for do tipo [Task];
  • linha 20: [Task.Delay(300)] retorna uma tarefa que será concluída em 300 ms. Nenhuma thread é ocupada durante esse tempo. É o equivalente assíncrono de [Thread.Sleep(300)]. Seu estado, [WaitingForActivation], significa “esperando por um evento externo”;
  • linhas 26–27: [Task.FromResult(42)] retorna uma tarefa que já foi concluída com o resultado 42, enquanto [Task.CompletedTask] retorna uma tarefa que já foi concluída sem resultado. Elas são usadas quando um método precisa retornar uma tarefa, mas já dispõe do resultado (um valor em cache, por exemplo);
  • linhas 31–36: uma tarefa cuja função lança uma exceção termina com o estado [Faulted]. A exceção é mantida dentro da tarefa, e [await] a relança; ela é capturada com um [try / catch]comum;
  • linhas 42–48: [Wait()] espera que a tarefa termine bloqueando a thread atual, e a propriedade [Result] retorna o resultado de uma [Task<T>] bloqueando igualmente a thread se a tarefa não tiver terminado. São as formas de espera de thread do capítulo anterior ([Join]). Devem ser evitadas: elas têm todos os inconvenientes da E/S bloqueante, encapsulam as exceções em uma [AggregateException] (linha 56) e podem causar um deadlock em uma aplicação gráfica. Devem ser reservadas para os raros casos em que se sabe que a tarefa já terminou;
  • linha 51: [ContinueWith] anexa a uma tarefa uma continuação, isto é, uma função que será executada quando a tarefa terminar. A continuação recebe a tarefa concluída e aqui retorna um inteiro: o resultado é uma nova tarefa, [Task<int>]. Era assim que se escrevia código assíncrono com o .NET 4.0, antes de [await]; [await] baseia-se em um mecanismo semelhante (registrar uma sequência a ser executada ao final da tarefa), implementado pelo compilador de forma mais segura. [ContinueWith] praticamente não é mais usado diretamente;
  • linhas 54–56: as propriedades booleanas [IsCompleted] (terminada, independentemente do modo), [IsCompletedSuccessfully] (terminada com êxito), [IsFaulted] (terminada por uma exceção), [IsCanceled] (cancelada) e a propriedade [Exception], do tipo [AggregateException], que contém a(s) exceção(ões) da tarefa.

Os valores possíveis da propriedade [Status] (enumeração [TaskStatus]) são os seguintes:

Estado
Significado
[Created]
A tarefa foi criada por um construtor e ainda não foi iniciada (raramente se criam tarefas com [new Task(...)])
[WaitingForActivation]
A tarefa está esperando por um evento externo: o fim de um tempo limite, uma operação de E/S ou outra tarefa
[WaitingToRun]
A tarefa está esperando que uma thread do pool fique disponível
[Running]
A tarefa está sendo executada por uma thread
[WaitingForChildrenToComplete]
A tarefa terminou, mas está esperando as tarefas “filhas” anexadas (caso raro)
[RanToCompletion]
A tarefa terminou com êxito
[Faulted]
A tarefa terminou devido a uma exceção não tratada
[Canceled]
A tarefa foi cancelada (veja a seção sobre cancelamento)

Os três últimos estados são estados finais: uma tarefa concluída não muda mais de estado.

9.3. Métodos assíncronos: async e await

9.3.1. Escrevendo um método assíncrono

Um método que contém [await] deve ser declarado com o modificador [async]. Ele retorna:

  • [Task] se não retorna resultado (o equivalente de [void]);
  • [Task<T>] se retorna um resultado do tipo [T]: dentro do método, escreve-se [return value;] com um valor do tipo [T], e o compilador o encapsula na tarefa.

Por convenção, o nome de um método que retorna uma tarefa termina com [Async]: [ReadAllTextAsync], [ConnectAsync], [MakeCoffeeAsync].

O programa [async-04.cs] faz café e conta cubos de açúcar:

// métodos assíncronos: async Task, async Task<T> e ordem de execução
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();
Display("call of MakeCoffeeAsync");
Task making = MakeCoffeeAsync();
Display("MakeCoffeeAsync has returned control: the program goes on");
Display("call of CountSugarsAsync");
Task<int> counting = CountSugarsAsync(3);
Display("CountSugarsAsync has returned control");
// agora esperamos os dois resultados
await making;
int nbSugars = await counting;
Display($"coffee ready, with {nbSugars} sugar(s)");

// um método assíncrono que não retorna resultado: retorna uma Task
async Task MakeCoffeeAsync()
{
    Display("  coffee: the machine is heating");
    // na primeira espera (await) de uma tarefa não concluída, o método devolve o controle ao chamador
    await Task.Delay(1000);
    // o restante será executado quando o atraso tiver passado
    Display("  coffee: the machine is pouring the coffee");
    await Task.Delay(500);
    Display("  coffee: done");
}

// um método assíncrono que retorna um inteiro: retorna uma Task<int>
async Task<int> CountSugarsAsync(int count)
{
    for (int i = 1; i <= count; i++)
    {
        await Task.Delay(200);
        Display($"  sugar no. {i}");
    }
    // retornamos um int, o compilador o encapsula na Task<int>
    return count;
}

// exibição com o tempo decorrido desde o início
void Display(string message)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : {message}");
}

Resultados:

> dotnet run async-04.cs
    1 ms : call of MakeCoffeeAsync
   29 ms :   coffee: the machine is heating
   33 ms : MakeCoffeeAsync has returned control: the program goes on
   33 ms : call of CountSugarsAsync
   36 ms : CountSugarsAsync has returned control
  237 ms :   sugar no. 1
  436 ms :   sugar no. 2
  636 ms :   sugar no. 3
 1031 ms :   coffee: the machine is pouring the coffee
 1532 ms :   coffee: done
 1532 ms : coffee ready, with 3 sugar(s)

Comentários:

  • linhas 17–25: um método assíncrono sem valor de retorno. Ele é executado normalmente, de forma síncrona, até encontrar seu primeiro [await] sobre uma tarefa não concluída (linha 21). Nesse ponto, ele devolve o controle ao chamador, repassando uma tarefa não concluída que o representa; é por isso que a linha 4 dos resultados aparece imediatamente após a linha 3, e não um segundo depois;
  • linha 23: quando o tempo limite de um segundo se esgota, o método retoma a execução imediatamente após o [await], com suas variáveis locais intactas, até o próximo [await] ou até terminar. Quando termina, a tarefa retornada ao chamador passa ao estado [RanToCompletion];
  • linhas 29–37: um método assíncrono que retorna um inteiro: seu tipo de retorno é [Task<int>], mas a instrução [return] retorna um [int];
  • linhas 6–9: o programa principal chama os dois métodos sem esperar por eles. Ele obtém duas tarefas e continua a execução. Os dois métodos prosseguem então “simultaneamente”: o açúcar é contado (linhas 7–9) enquanto a máquina esquenta;
  • linhas 12–13: o programa principal espera pelas duas tarefas. O café fica pronto após 1,5 segundo (a duração da mais longa das duas operações) e não após 2,1 segundos (1,5 + 3 × 0,2).

É importante observar que [async] não torna um método assíncrono: ele apenas permite o uso de [await] dentro do método. Um método [async] que não espera por nenhuma tarefa não concluída é executado inteiramente de forma síncrona (o compilador, aliás, emite um aviso para um método [async] que não contém nenhum [await]). São as operações aguardadas ([Task.Delay], E/S assíncrona) que são realmente assíncronas.

9.3.2. O que o compilador faz

Como um método pode ser interrompido no meio de um laço, ceder o controle e depois retomar mais tarde no mesmo ponto, com os mesmos valores de variáveis locais? O compilador transforma o método [async] em uma máquina de estados: uma classe (uma estrutura na versão otimizada do programa, compilada no modo “Release”) cujos campos são as variáveis locais do método e um número de estado que indica onde retomar. Para o método [CountSugarsAsync], o código gerado se parece com isto:

// o que o compilador gera (muito simplificado)
Task<int> CountSugarsAsync(int count)
{
    var machine = new CountSugarsMachine { count = count, state = 0 };
    machine.Advance();         // executa o método até o primeiro await
    return machine.ResultTask; // a tarefa que a máquina completará mais tarde
}

class CountSugarsMachine
{
    public int count, i, state;               // as variáveis locais viram campos
    public TaskCompletionSource<int> Source = new();
    public Task<int> ResultTask => Source.Task;

    public void Advance()
    {
        if (state == 0) { i = 1; }             // primeira passagem: início do laço
        else { Console.WriteLine($"  sugar no. {i}"); i++; }   // retomada após o await
        if (i <= count)
        {
            state = 1;
            // pedimos para ser chamados de volta no fim do atraso e depois devolvemos o controle
            Task.Delay(200).GetAwaiter().OnCompleted(Advance);
            return;
        }
        Source.SetResult(count);               // fim do método: a tarefa é concluída
    }
}

Isso segue o mesmo princípio dos métodos de retorno de chamada do modelo APM ([OnCompleted(Advance)] solicita um retorno de chamada ao final da operação), mas é o compilador que divide o método, salva as variáveis e trata as exceções. O desenvolvedor, por sua vez, escreve um método que se lê de cima para baixo. É possível ver o código realmente gerado com um decompilador como o ILSpy ou no site SharpLab; ele é bem mais longo, principalmente porque trata o caso em que a tarefa esperada já foi concluída (situação em que a execução continua sem interrupção) e o caso das exceções.

9.3.3. Qual thread executa o restante do código?

O programa [async-05.cs] exibe o número da thread que executa cada trecho de código:

// qual thread executa o restante de um método após um await?
Display("start of the program");
Display($"synchronization context: {SynchronizationContext.Current?.GetType().Name ?? "none"}");

// 1 - await de uma tarefa já concluída: sem suspensão, permanecemos na mesma thread
await Task.CompletedTask;
Display("after await Task.CompletedTask");

// 2 - await de uma tarefa não concluída: o restante é executado por uma thread do pool
for (int i = 1; i <= 3; i++)
{
    await Task.Delay(100);
    Display($"after await Task.Delay(100) no. {i}");
}

// 3 - durante a espera, a thread está livre: ela pode executar outra coisa
Task t1 = WorkAsync("A");
Task t2 = WorkAsync("B");
await Task.WhenAll(t1, t2);
Display($"end of the program, threads created by the pool: {ThreadPool.ThreadCount}");

async Task WorkAsync(string name)
{
    for (int i = 1; i <= 3; i++)
    {
        Display($"  {name}{i} : before await");
        await Task.Delay(100);
    }
}

// exibição prefixada pelo número da thread que a executa
static void Display(string message)
{
    Console.WriteLine($"[thread {Environment.CurrentManagedThreadId,2}] {message}");
}

Resultados:

> dotnet run async-05.cs
[thread  1] start of the program
[thread  1] synchronization context: none
[thread  1] after await Task.CompletedTask
[thread  5] after await Task.Delay(100) no. 1
[thread  5] after await Task.Delay(100) no. 2
[thread  5] after await Task.Delay(100) no. 3
[thread  5]   A1 : before await
[thread  5]   B1 : before await
[thread  6]   A2 : before await
[thread  5]   B2 : before await
[thread  6]   B3 : before await
[thread  5]   A3 : before await
[thread  6] end of the program, threads created by the pool: 2

Comentários:

  • linha 3: [SynchronizationContext.Current] é o contexto de sincronização da thread atual. Em um programa de console, não há nenhum (valor [null]); veremos na seção sobre [ConfigureAwait] o papel que ele desempenha nas interfaces gráficas de usuário;
  • linha 6: esperar por uma tarefa que já foi concluída não suspende o método: a execução continua imediatamente na mesma thread (thread 1, linha 4);
  • linhas 10–13: depois de esperar por uma tarefa não concluída, e na ausência de um contexto de sincronização, o restante do método é executado por qualquer thread do pool. A thread 1, a thread do programa principal, não é mais usada: durante a espera, ela não tinha nada a fazer. Portanto, em um método assíncrono, nunca se deve supor que o código que segue um [await] seja executado pela mesma thread que o código que o precede;
  • linhas 17–19: duas chamadas ao método [WorkAsync] prosseguem simultaneamente. Os seis blocos de código são executados por uma ou duas threads do pool (isso varia de uma execução para outra), que se alternam entre A e B conforme as esperas ocorrem: enquanto uma espera, a outra trabalha. Nenhuma thread é atribuída a A ou B, e nenhuma fica bloqueada durante os períodos de espera;
  • linha 20: [ThreadPool.ThreadCount] retorna o número de threads atualmente criadas pelo pool: apenas algumas.

Essa maneira de realizar várias operações simultaneamente sem aumentar o número de threads chama-se concorrência. Ela difere do paralelismo, que consiste em executar vários cálculos ao mesmo tempo em vários processadores (como visto no capítulo anterior: [Parallel.For], [Task.Run]). A assincronia facilita a concorrência de E/S; ela não torna os cálculos mais rápidos.

9.3.4. O programa principal assíncrono

Os programas anteriores usam [await] diretamente em instruções de nível superior. Isso é possível desde o C# 9: quando as instruções de nível superior contêm um [await], o compilador gera um método [Main] assíncrono com a assinatura [static async Task Main(string[] args)] (ou [Task<int>] se o programa usa [return integer;]).

Também é possível escrever esse método de forma explícita, o que é permitido desde o C# 7.1. É o que faz o programa [async-06.cs]:

// a forma explícita de um método Main assíncrono
namespace Async06;

public static class Program
{
    // Main pode retornar Task ou Task<int> (o código de saída do programa)
    public static async Task<int> Main(string[] args)
    {
        // o número de segundos é passado como argumento
        if (args.Length != 1 || !int.TryParse(args[0], out int nbSeconds) || nbSeconds < 0)
        {
            Console.WriteLine("syntax: dotnet run async-06.cs -- nbSeconds");
            return 1;
        }
        for (int i = nbSeconds; i > 0; i--)
        {
            Console.WriteLine($"{i} s left");
            await Task.Delay(1000);
        }
        Console.WriteLine("finished");
        return 0;
    }
}

Resultados, primeiro com e depois sem argumento:

1
2
3
4
5
> dotnet run async-06.cs -- 3
3 s left
2 s left
1 s left
finished
> dotnet run async-06.cs
syntax: dotnet run async-06.cs -- nbSeconds

Comentários:

  • Linha 7: o método [Main] é assíncrono e retorna uma [Task<int>]. O inteiro é o código de saída do programa (0 para sucesso, qualquer outro valor para um erro), que pode ser verificado por um script ([echo $?] no Linux, [echo %ERRORLEVEL%] no Windows);
  • linha 10: o argumento é o número de segundos da contagem regressiva. Ele é passado depois de [--] no comando [dotnet run async-06.cs -- 3];
  • linha 18: uma espera de um segundo, sem bloquear nenhuma thread.

Quando [Main] é assíncrono, o runtime a chama, obtém a tarefa retornada e espera que ela termine antes de encerrar o programa. Este é o único lugar em que é feita uma espera bloqueante, pelo próprio .NET.

9.4. Execução sequencial e execução concorrente

9.4.1. Task.WhenAll

O exemplo do café demonstrou isto: o momento em que uma operação assíncrona é iniciada e o momento em que ela é aguardada podem ser diferentes. Escrever [await MethodAsync()] inicia a operação e a aguarda imediatamente; escrever [var t = MethodAsync();] e depois, mais adiante, [await t;] permite que outras operações sejam disparadas nesse intervalo. O programa [async-07.cs] compara as duas abordagens usando três operações de um segundo:

// execução sequencial e execução concorrente de três operações de um segundo
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();

// 1 - em sequência: cada operação espera o fim da anterior
int a = await ReadTemperatureAsync("Angers");
int b = await ReadTemperatureAsync("Brest");
int c = await ReadTemperatureAsync("Colmar");
Console.WriteLine($"in sequence: {a}, {b}, {c} in {stopwatch.ElapsedMilliseconds} ms");

// 2 - de forma concorrente: lançamos as três operações e depois esperamos por elas
stopwatch.Restart();
Task<int> ta = ReadTemperatureAsync("Angers");
Task<int> tb = ReadTemperatureAsync("Brest");
Task<int> tc = ReadTemperatureAsync("Colmar");
await Task.WhenAll(ta, tb, tc);
Console.WriteLine($"concurrently: {ta.Result}, {tb.Result}, {tc.Result} in {stopwatch.ElapsedMilliseconds} ms");

// 3 - Task.WhenAll sobre uma coleção de Task<T> retorna diretamente o array de resultados
stopwatch.Restart();
string[] cities = ["Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix"];
int[] temperatures = await Task.WhenAll(cities.Select(ReadTemperatureAsync));
Console.WriteLine($"{cities.Length} cities: [{string.Join(", ", temperatures)}] in {stopwatch.ElapsedMilliseconds} ms");

// simula a consulta a um serviço remoto que responde em um segundo
static async Task<int> ReadTemperatureAsync(string city)
{
    await Task.Delay(1000);
    // uma "temperatura" derivada do nome da cidade
    return 10 + city.Length;
}

Resultados:

1
2
3
4
> dotnet run async-07.cs
in sequence: 16, 15, 16 in 3007 ms
concurrently: 16, 15, 16 in 1001 ms
6 cities: [16, 15, 16, 15, 14, 14] in 1005 ms

Comentários:

  • linhas 7–9: cada operação é iniciada e aguardada antes de iniciar a seguinte. O código não bloqueia nenhuma thread, mas as três operações são executadas uma após a outra: 3 segundos (linha 2). Esta é a abordagem correta quando uma operação precisa do resultado da anterior;
  • linhas 14–16: as três operações são iniciadas sem esperar umas pelas outras. Elas são executadas simultaneamente;
  • linha 17: [Task.WhenAll] retorna uma tarefa que é concluída quando todas as tarefas passadas a ela terminam. Aguardamos essa tarefa com [await]: 1 segundo em vez de 3 (linha 3);
  • linha 18: as três tarefas estão concluídas, portanto a propriedade [Result] retorna o resultado delas sem bloquear. Também poderíamos ter escrito [await ta], que retorna imediatamente o resultado de uma tarefa concluída;
  • linha 23: quando recebe uma coleção de [Task<T>], [Task.WhenAll] retorna uma [Task<T[]>] cujo resultado é o array de resultados, na ordem das tarefas (não na ordem em que foram concluídas). A expressão [cities.Select(ReadTemperatureAsync)] do LINQ chama o método para cada cidade, produzindo assim seis tarefas disparadas simultaneamente. As seis operações juntas levam um segundo.

[Task.WhenAll] é o equivalente assíncrono de [Task.WaitAll] (usado em [async-01.cs]), que espera todas as tarefas bloqueando a thread atual.

9.4.2. Task.WhenAny

[Task.WhenAny] retorna uma tarefa que termina assim que qualquer uma das tarefas passadas a ela é concluída; seu resultado é essa primeira tarefa concluída. O programa [async-08.cs] a utiliza de duas maneiras:

// Task.WhenAny: reagir à primeira tarefa concluída
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();

// 1 - consultamos três servidores espelho e mantemos a primeira resposta
Task<string>[] requests =
[
    QueryAsync("mirror-paris", 800),
    QueryAsync("mirror-lyon", 300),
    QueryAsync("mirror-lille", 600),
];
// WhenAny retorna a primeira tarefa concluída (uma Task<string>)
Task<string> first = await Task.WhenAny(requests);
Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : first answer: {await first}");
// as outras requisições continuam: esperamos por elas aqui para ver suas respostas
await Task.WhenAll(requests);
Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : all the answers: {string.Join(", ", requests.Select(t => t.Result))}");

// 2 - uma operação com tempo limitado: a colocamos em "corrida" contra um atraso
stopwatch.Restart();
Task<string> slow = QueryAsync("slow-server", 2000);
Task winner = await Task.WhenAny(slow, Task.Delay(500));
if (winner == slow)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : answer obtained in time: {await slow}");
}
else
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : the slow server did not answer within the 500 ms delay");
}

// simula um servidor que responde após [duration] milissegundos
static async Task<string> QueryAsync(string server, int duration)
{
    await Task.Delay(duration);
    return $"{server} ({duration} ms)";
}

Resultados:

1
2
3
4
> dotnet run async-08.cs
  309 ms : first answer: mirror-lyon (300 ms)
  803 ms : all the answers: mirror-paris (800 ms), mirror-lyon (300 ms), mirror-lille (600 ms)
  500 ms : the slow server did not answer within the 500 ms delay

Comentários:

  • linhas 7–11: três servidores espelho são consultados; todos têm as mesmas informações, mas respondem com velocidades variadas. As três tarefas são armazenadas em um array, inicializado com uma expressão de coleção;
  • linha 14: [await Task.WhenAny(requests)] retorna a primeira tarefa concluída, do tipo [Task<string>]. Para obter seu resultado, aguardamos essa tarefa por sua vez (linha 15): como ela já está concluída, [await] retorna imediatamente a string. A primeira resposta chega após 300 ms (linha 2);
  • linha 17: as outras requisições não são interrompidas por [WhenAny]; elas continuam até terminar. Para interrompê-las, seria preciso cancelá-las, o que veremos na seção sobre cancelamento. Aqui, esperamos que todas exibam suas respostas;
  • linhas 22–24: um uso clássico de [WhenAny]: limitar a duração de uma espera criando uma “corrida” entre a operação e um timeout. Se o timeout vencer, a operação demorou demais. O .NET agora oferece uma forma mais direta de tratar esse caso: o método [WaitAsync], que será visto mais adiante.

9.4.3. Task.WhenEach

Muitas vezes queremos processar os resultados de várias operações à medida que terminam, sem esperar pela mais lenta. Antes do .NET 9, escrevíamos para isso um laço que chamava [Task.WhenAny], processava a tarefa obtida e a removia da lista. O .NET 9 introduziu o método [Task.WhenEach], que retorna as tarefas na ordem em que são concluídas, na forma de um fluxo assíncrono percorrido com [await foreach] (os fluxos assíncronos são tratados mais adiante neste capítulo).

O programa [async-09.cs] processa cinco “arquivos”, cada um levando entre 100 e 900 ms para ser processado:

// Task.WhenEach (.NET 9): processar os resultados na ordem em que as tarefas terminam
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();
int[] durations = [900, 300, 700, 100, 500];
// lançamos todas as tarefas
List<Task<string>> tasks = durations.Select((duration, i) => ProcessAsync($"file{i}.txt", duration)).ToList();

// await foreach: cada tarefa é entregue assim que termina
await foreach (Task<string> task in Task.WhenEach(tasks))
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : {await task}");
}
Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : all the files have been processed");

// simula o processamento de um arquivo que dura [duration] milissegundos
static async Task<string> ProcessAsync(string file, int duration)
{
    await Task.Delay(duration);
    return $"{file} processed in {duration} ms";
}

Resultados:

1
2
3
4
5
6
7
> dotnet run async-09.cs
  111 ms : file3.txt processed in 100 ms
  312 ms : file1.txt processed in 300 ms
  509 ms : file4.txt processed in 500 ms
  710 ms : file2.txt processed in 700 ms
  906 ms : file0.txt processed in 900 ms
  906 ms : all the files have been processed

Comentários:

  • linha 7: os cinco processamentos são disparados. O método [Select] do LINQ fornece à função o elemento e seu índice ([(duration, i)]);
  • Linhas 10–12: [Task.WhenEach(tasks)] entrega cada tarefa assim que ela é concluída: o arquivo 3 (100 ms) primeiro, o arquivo 0 (900 ms) por último. O laço [await foreach] espera a próxima tarefa sem bloquear nenhuma thread. Cada tarefa entregue já está concluída: [await task] retorna seu resultado imediatamente;
  • o processo inteiro leva 900 ms — a duração do processamento mais longo — e cada resultado é exibido o mais cedo possível.

9.5. Exceções em código assíncrono

9.5.1. Propagação via [await]

Uma exceção lançada em um método assíncrono não é propagada ao chamador no momento da chamada: ela é armazenada na tarefa, que passa ao estado [Faulted]. É a instrução [await] que a relança. O programa [async-10.cs] examina os vários casos:

// exceções em código assíncrono

// 1 - await relança a exceção da tarefa aguardada
try
{
    int value = await ReadValueAsync("twelve");
    Console.WriteLine($"value = {value}");
}
catch (FormatException e)
{
    Console.WriteLine($"1 - exception caught: {e.GetType().Name} : {e.Message}");
}

// 2 - chamar um método async não lança exceção: ela é armazenada na tarefa
// (aqui, a exceção ocorre antes mesmo do primeiro await do método)
Task<int> task = ReadValueAsync("");
Console.WriteLine($"2 - after the call: status={task.Status}");
try
{
    await task;
}
catch (ArgumentException e)
{
    Console.WriteLine($"2 - it is the await that throws the exception: {e.GetType().Name} : {e.Message}");
}

// 3 - Task.WhenAll com várias tarefas com falha
Task<int>[] tasks = [ReadValueAsync("1"), ReadValueAsync("two"), ReadValueAsync("3"), ReadValueAsync("four")];
Task<int[]> all = Task.WhenAll(tasks);
try
{
    int[] values = await all;
}
catch (Exception e)
{
    // await relança apenas a primeira exceção…
    Console.WriteLine($"3 - await rethrows: {e.GetType().Name} : {e.Message}");
    // … mas todas elas estão na propriedade Exception da tarefa, do tipo AggregateException
    AggregateException ae = all.Exception!;
    Console.WriteLine($"3 - {ae.GetType().Name} with {ae.InnerExceptions.Count} exceptions:");
    foreach (Exception inner in ae.InnerExceptions)
    {
        Console.WriteLine($"      {inner.GetType().Name} : {inner.Message}");
    }
    // as tarefas bem-sucedidas têm, sim, o seu resultado
    foreach (Task<int> t in tasks.Where(t => t.IsCompletedSuccessfully))
    {
        Console.WriteLine($"      successful task, result = {t.Result}");
    }
}

// 4 - as formas bloqueantes encapsulam a exceção em uma AggregateException
try
{
    int value = ReadValueAsync("five").Result;
}
catch (AggregateException e)
{
    Console.WriteLine($"4 - Result throws: {e.GetType().Name} containing {e.InnerException?.GetType().Name}");
}

// um método assíncrono que falha se a string não for um inteiro
static async Task<int> ReadValueAsync(string text)
{
    // verificação imediata do parâmetro, antes de qualquer await
    ArgumentException.ThrowIfNullOrWhiteSpace(text);
    // a leitura leva um pouco de tempo
    await Task.Delay(100);
    return int.Parse(text);
}

Resultados:

> dotnet run async-10.cs
1 - exception caught: FormatException : The input string 'twelve' was not in a correct format.
2 - after the call: status=Faulted
2 - it is the await that throws the exception: ArgumentException : The value cannot be an empty string or composed entirely of whitespace. (Parameter 'text')
3 - await rethrows: FormatException : The input string 'two' was not in a correct format.
3 - AggregateException with 2 exceptions:
      FormatException : The input string 'two' was not in a correct format.
      FormatException : The input string 'four' was not in a correct format.
      successful task, result = 1
      successful task, result = 3
4 - Result throws: AggregateException containing FormatException

Comentários:

  • Linhas 63–69: o método testado. Ele primeiro verifica seu parâmetro ([ArgumentException.ThrowIfNullOrWhiteSpace] lança uma [ArgumentException] se a string for [null], vazia ou em branco), espera 100 ms e depois converte a string inteira, o que lança uma [FormatException] se a string não for um número;
  • linhas 3–11: o caso padrão. A exceção lançada por [int.Parse] após o [await] do método é relançada pelo [await] do chamador: um [try / catch] que envolve o [await] a intercepta, exatamente como em uma chamada síncrona. Esta é a grande simplificação introduzida por [await]: com o modelo APM, a exceção era relançada por [EndXxx], dentro do método de callback, longe do código que havia iniciado a operação;
  • linhas 16–24: aqui, a exceção é lançada antes mesmo do primeiro [await] do método. No entanto, a chamada não dispara nada: o método [async] retorna uma tarefa que já falhou (estado [Faulted], linha 3), e é o [await] que lança a exceção. Um método [async] nunca lança uma exceção quando é chamado;
  • linhas 28–32: [Task.WhenAll] espera quatro tarefas, duas das quais falham. A tarefa [all] também falha então e contém ambas as exceções. Mas o [await] relança apenas uma delas, a primeira (linha 5): os projetistas da linguagem optaram por manter a forma usual do [catch] (interceptando uma [FormatException], e não um wrapper);
  • linhas 39–43: para ver todas as exceções, consulte a propriedade [Exception] da tarefa [all]. Ela é do tipo [AggregateException], uma exceção que contém outras exceções, acessíveis por meio de sua propriedade [InnerExceptions];
  • linhas 46–48: a falha de [WhenAll] não impede que as outras tarefas tenham sucesso; seus resultados estão disponíveis;
  • linhas 52–59: as formas bloqueantes ([Result], [Wait()]) não relançam a própria exceção, mas sim uma [AggregateException] que a contém. Este é mais um motivo para preferir [await] a elas.

9.5.2. async void: a ser evitado

Um método [async] também pode ser declarado como [void]. Nesse caso, ele não retorna nenhuma tarefa, o que tem duas consequências graves: o chamador não pode saber quando ele termina (não pode esperá-lo) e não pode capturar suas exceções. Uma exceção não tratada em um método [async void] é relançada em uma thread do pool, onde ninguém pode capturá-la: ela encerra o programa. O programa [async-11.cs] demonstra isso:

// por que não se deve escrever um método async void

// exibimos a mensagem de uma exceção não tratada e depois encerramos o programa
AppDomain.CurrentDomain.UnhandledException += (sender, e) =>
{
    var exception = (Exception)e.ExceptionObject;
    Console.WriteLine($"unhandled exception: {exception.GetType().Name} : {exception.Message}");
    Console.WriteLine("the process is going to be stopped");
    Environment.Exit(1);
};

// 1 - um método async Task: o chamador pode aguardá-lo com await e capturar sua exceção
try
{
    await SaveAsync("a");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"1 - async Task: exception caught: {e.Message}");
}

// 2 - um método async void: o chamador não pode nem aguardá-lo com await nem capturar sua exceção
try
{
    Save("b");
    Console.WriteLine("2 - async void: the method has returned control, the try saw nothing");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"2 - async void: exception caught: {e.Message}");
}
// o programa continua seu trabalho…
for (int i = 1; i <= 5; i++)
{
    await Task.Delay(100);
    Console.WriteLine($"the program is working ({i})");
}
Console.WriteLine("normal end of the program");

static async Task SaveAsync(string data)
{
    await Task.Delay(200);
    throw new InvalidOperationException($"failure saving [{data}]");
}

// NÃO FAÇA ISSO: async void é reservado para manipuladores de eventos
static async void Save(string data)
{
    await Task.Delay(200);
    throw new InvalidOperationException($"failure saving [{data}]");
}

Resultados:

1
2
3
4
5
6
7
> dotnet run async-11.cs
1 - async Task: exception caught: failure saving [a]
2 - async void: the method has returned control, the try saw nothing
the program is working (1)
the program is working (2)
unhandled exception: InvalidOperationException : failure saving [b]
the process is going to be stopped

Comentários:

  • Linhas 4–9: o evento [AppDomain.CurrentDomain.UnhandledException] é disparado quando uma exceção não é capturada em lugar nenhum, pouco antes de o sistema encerrar o processo. Seu manipulador não pode impedir esse encerramento; nós o usamos aqui para exibir uma mensagem personalizada (em vez do stack trace que o .NET exibiria) e depois encerrar nós mesmos o processo com [Environment.Exit(1)];
  • linhas 15–19: o método [SaveAsync] retorna uma [Task]: sua exceção é interceptada normalmente;
  • linhas 25–26: o método [Save], declarado como [async void], devolve o controle em seu primeiro [await]; o [try] termina sem ter encontrado nada. 200 ms depois, o método lança sua exceção em uma thread do pool: o programa é interrompido no meio da execução (linhas 4–7), e a linha [normal end of the program] nunca é exibida.

A regra é, portanto: um método assíncrono sempre retorna [Task] ou [Task<T>], nunca [void]. A única exceção é um manipulador de evento de GUI (como o clique de um botão): a assinatura dos manipuladores de evento exige [void], então escrevemos [private async void CalculateButton_Click(object sender, EventArgs e)]. Nesse caso, todas as exceções são capturadas dentro do manipulador com [try / catch].

Um erro relacionado consiste em chamar um método que retorna uma tarefa sem aguardá-la ([SaveAsync("c");] sem [await]): o compilador sinaliza isso com um aviso (CS4014), pois qualquer exceção lançada pela tarefa seria perdida. Se você realmente quiser disparar uma tarefa sem aguardá-la (“fire-and-forget”), deve indicar explicitamente o elemento ignorado [_]: [_ = SaveAsync("c");], e o método deverá então tratar suas próprias exceções.

9.6. Cancelamento e timeouts

9.6.1. CancellationTokenSource e CancellationToken

Uma operação assíncrona de longa duração deve ser cancelável: o usuário clicou em [Cancel], um cliente de servidor web se desconectou, o aplicativo foi encerrado ou um timeout foi excedido. O .NET usa para isso um mecanismo cooperativo que envolve dois objetos:

  • um [CancellationTokenSource] (origem de cancelamento), mantido pelo código que decide cancelar. Seu método [Cancel()] solicita o cancelamento; [CancelAfter(delay)] o solicita automaticamente após um timeout;
  • um [CancellationToken] (token de cancelamento), obtido por meio da propriedade [Token] da origem e passado como parâmetro às operações canceláveis. A operação verifica o token ([IsCancellationRequested]) ou pede que ele lance uma exceção se o cancelamento tiver sido solicitado ([ThrowIfCancellationRequested()]), e o repassa às operações que chama.

O mecanismo é cooperativo: ninguém interrompe à força uma operação (o método [Thread.Abort] do curso de 2008 está obsoleto no .NET atual: ele simplesmente lança uma [PlatformNotSupportedException]); a operação para por conta própria, em um ponto em que possa fazê-lo de forma limpa. Por convenção, uma operação cancelada termina lançando uma [OperationCanceledException], e sua tarefa passa ao estado [Canceled].

O programa [async-12.cs] cancela um download simulado de três maneiras:

// cancelar uma operação assíncrona: CancellationTokenSource e CancellationToken
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();

// 1 - uma fonte de cancelamento que se cancela sozinha após 1,2 segundo
using (var source = new CancellationTokenSource())
{
    source.CancelAfter(TimeSpan.FromSeconds(1.2));
    try
    {
        // o token da fonte é passado para a operação
        await DownloadAsync(10, source.Token);
    }
    catch (OperationCanceledException e)
    {
        Display($"1 - {e.GetType().Name} : {e.Message}");
    }
}

// 2 - um cálculo que verifica ele mesmo, regularmente, se deve parar
stopwatch.Restart();
using (var source = new CancellationTokenSource(TimeSpan.FromMilliseconds(300)))
{
    Task<long> computation = Task.Run(() => Compute(source.Token), source.Token);
    try
    {
        long result = await computation;
        Display($"2 - result: {result}");
    }
    catch (OperationCanceledException e)
    {
        Display($"2 - {e.GetType().Name}, status of the task: {computation.Status}");
    }
}

// 3 - o cancelamento é solicitado explicitamente pelo programa, com Cancel()
stopwatch.Restart();
using (var source = new CancellationTokenSource())
{
    Task download = DownloadAsync(10, source.Token);
    await Task.Delay(700);
    Display("3 - the program requests the cancellation");
    source.Cancel();
    try
    {
        await download;
    }
    catch (OperationCanceledException)
    {
        Display($"3 - download cancelled, IsCanceled={download.IsCanceled}");
    }
}

// simula o download de [nbBlocks] blocos de dados (um bloco a cada 300 ms)
async Task DownloadAsync(int nbBlocks, CancellationToken token)
{
    for (int i = 1; i <= nbBlocks; i++)
    {
        // Task.Delay aceita um token: a espera termina assim que o cancelamento é solicitado
        await Task.Delay(300, token);
        Display($"  block {i}/{nbBlocks} received");
    }
}

// um longo cálculo síncrono que verifica o token a cada 1.000.000 de iterações
static long Compute(CancellationToken token)
{
    long sum = 0;
    for (long i = 0; i < 100_000_000_000; i++)
    {
        if (i % 1_000_000 == 0)
        {
            // lança OperationCanceledException se o cancelamento tiver sido solicitado
            token.ThrowIfCancellationRequested();
        }
        sum += i % 7;
    }
    return sum;
}

void Display(string message)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : {message}");
}

Resultados:

> dotnet run async-12.cs
  307 ms :   block 1/10 received
  620 ms :   block 2/10 received
  921 ms :   block 3/10 received
 1211 ms : 1 - TaskCanceledException : A task was canceled.
  304 ms : 2 - OperationCanceledException, status of the task: Canceled
  300 ms :   block 1/10 received
  600 ms :   block 2/10 received
  700 ms : 3 - the program requests the cancellation
  701 ms : 3 - download cancelled, IsCanceled=True

Comentários:

  • Linhas 56–62: o download simulado recebe um bloco a cada 300 ms. Ele recebe um [CancellationToken] como último parâmetro (esta é a convenção) e o repassa a [Task.Delay] (linha 61): se o cancelamento for solicitado durante a espera, a espera é interrompida imediatamente e uma [TaskCanceledException] — classe derivada de [OperationCanceledException] — é lançada. Quase todos os métodos assíncronos do .NET aceitam um token: [ReadAllTextAsync], [ConnectAsync], [ToListAsync]…;
  • Linhas 6–17: a origem é criada em um [using] porque utiliza um timer que deve ser liberado. [CancelAfter] solicita o cancelamento após 1,2 segundo: o download recebe três blocos e depois para em 1.200 ms (linha 5). Interceptamos [OperationCanceledException], a classe base, que trata todos os cancelamentos;
  • linhas 21–33: um cálculo síncrono (não uma espera) que pode ser cancelado. O método [Compute] (linhas 67–79) verifica o token a cada um milhão de iterações com [ThrowIfCancellationRequested()], que lança uma [OperationCanceledException] se o cancelamento tiver sido solicitado. O cálculo é delegado ao pool por [Task.Run], ao qual o token também é passado: a tarefa termina então com o estado [Canceled] em vez de [Faulted] (linha 6). Aqui, a origem é criada com um atraso (construtor [CancellationTokenSource(TimeSpan)]), o que equivale a [CancelAfter];
  • linhas 37–51: a origem é cancelada explicitamente por [Cancel()] após 700 ms. O cancelamento é imediato: a espera pelo terceiro bloco é interrompida (linhas 9–10).

9.6.2. O exemplo do BackgroundWorker reescrito

O curso de 2008 apresentava a classe [BackgroundWorker] com um exemplo de cinco processamentos com duração de 1 a 5 segundos, dos quais o nº 3 lançava uma exceção e o nº 4 era cancelado. Era preciso assinar métodos nos eventos [DoWork] e [RunWorkerCompleted], habilitar o cancelamento ([WorkerSupportsCancellation]), testar [CancellationPending] no laço de trabalho e preencher as propriedades [Result] e [Cancel] do argumento do evento; e o curso observava que, em caso de exceção ou cancelamento, era impossível determinar qual processamento havia sido afetado. [BackgroundWorker] ainda existe no .NET, mas foi concebido para interfaces gráficas Windows Forms e não tem mais utilidade: as tarefas fazem o mesmo de forma mais simples. O programa [async-13.cs] reescreve esse exemplo:

// o exemplo do BackgroundWorker do curso de 2008 reescrito com tarefas:
// cinco processamentos de 1 a 5 segundos, o nº 3 lança uma exceção, o nº 4 é cancelado
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();
using var cancellation = new CancellationTokenSource();
var tasks = new Task<Result>[5];
for (int i = 0; i < tasks.Length; i++)
{
    // somente o processamento nº 4 recebe o token da fonte de cancelamento
    CancellationToken token = i == 4 ? cancellation.Token : CancellationToken.None;
    tasks[i] = SleepAsync(i, i + 1, token);
}
// cancelamos o processamento nº 4 após 2,5 segundos
cancellation.CancelAfter(2500);
Console.WriteLine($"{stopwatch.Elapsed.TotalSeconds,4:F1} s : the {tasks.Length} processings are launched");

// usamos cada processamento assim que ele termina, seja qual for a forma como termina
await foreach (Task<Result> task in Task.WhenEach(tasks))
{
    int number = Array.IndexOf(tasks, task);
    string outcome = task.Status switch
    {
        TaskStatus.RanToCompletion => $"finished: scheduled duration {task.Result.Duration} s, actual duration {task.Result.ActualDuration:F1} s",
        TaskStatus.Faulted => $"encountered the following error: {task.Exception!.InnerException!.Message}",
        TaskStatus.Canceled => "cancelled",
        _ => $"unexpected status {task.Status}",
    };
    Console.WriteLine($"{stopwatch.Elapsed.TotalSeconds,4:F1} s : processing {number} {outcome}");
}

// o processamento: dormir [duration] segundos, em fatias de um segundo
static async Task<Result> SleepAsync(int number, int duration, CancellationToken token)
{
    var start = Stopwatch.GetTimestamp();
    // exceção para o processamento nº 3
    if (number == 3)
    {
        throw new InvalidOperationException("test....");
    }
    for (int i = 1; i <= duration; i++)
    {
        await Task.Delay(1000, token);
    }
    // o resultado retornado ao chamador
    return new Result(duration, Stopwatch.GetElapsedTime(start).TotalSeconds);
}

// o resultado de um processamento
record Result(int Duration, double ActualDuration);

Resultados:

1
2
3
4
5
6
7
> dotnet run async-13.cs
 0.0 s : the 5 processings are launched
 0.0 s : processing 3 encountered the following error: test....
 1.0 s : processing 0 finished: scheduled duration 1 s, actual duration 1.0 s
 2.0 s : processing 1 finished: scheduled duration 2 s, actual duration 2.0 s
 2.5 s : processing 4 cancelled
 3.0 s : processing 2 finished: scheduled duration 3 s, actual duration 3.0 s

Comentários:

  • Linhas 33–46: o processamento. O nº 3 lança uma exceção; os demais “dormem” por [duration] segundos em incrementos de um segundo, com um [Task.Delay] cancelável, e retornam um resultado — um [record] — que contém a duração prevista e a duração real. [Stopwatch.GetTimestamp()] e [Stopwatch.GetElapsedTime(start)] medem uma duração sem criar um objeto [Stopwatch];
  • linhas 8–15: os cinco processamentos são disparados. Apenas o processamento nº 4 recebe o token da origem de cancelamento; os outros recebem [CancellationToken.None], um token que nunca será cancelado. O processamento nº 4 é cancelado após 2,5 segundos, embora ainda tivesse 2,5 segundos de sono pela frente;
  • linhas 19–29: com [Task.WhenEach], cada processamento é tratado assim que termina, independentemente de como terminou: não usamos [await task], que dispararia a exceção, mas verificamos o estado da tarefa com uma expressão [switch]. O número do trabalho é obtido a partir de sua posição no array de tarefas ([Array.IndexOf]): o problema relatado no curso de 2008 está resolvido;
  • os resultados mostram que o nº 3 falha imediatamente, que os nºs 0, 1 e 2 terminam após 1, 2 e 3 segundos, respectivamente, e que o nº 4 é cancelado aos 2,5 segundos.

9.6.3. Limitando a duração de uma espera

O programa [async-14.cs] oferece duas ferramentas complementares: o método [WaitAsync] e as origens de cancelamento associadas.

// limitar a duração de uma espera: WaitAsync e tokens vinculados
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();

// 1 - WaitAsync(TimeSpan): não esperamos mais que um segundo
Task<string> slow = QueryAsync("slow-server", 3000, CancellationToken.None);
try
{
    string answer = await slow.WaitAsync(TimeSpan.FromSeconds(1));
    Display($"1 - answer: {answer}");
}
catch (TimeoutException e)
{
    Display($"1 - {e.GetType().Name} : {e.Message}");
}
// atenção: WaitAsync desiste da espera, não da operação, que continua
Display($"1 - status of the operation: {slow.Status}");

// 2 - para realmente interromper a operação, é preciso passar a ela um token de cancelamento
stopwatch.Restart();
using (var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(1)))
{
    Task<string> slow2 = QueryAsync("slow-server", 3000, timeout.Token);
    try
    {
        Display($"2 - answer: {await slow2}");
    }
    catch (OperationCanceledException)
    {
        Display($"2 - operation cancelled after one second, status: {slow2.Status}");
    }
}

// 3 - combinar duas causas de cancelamento: um atraso e uma solicitação do chamador
stopwatch.Restart();
using var generalStop = new CancellationTokenSource();
await Task.WhenAll(ProcessWithTimeoutAsync("fast", 500, 1000, generalStop.Token),
                   ProcessWithTimeoutAsync("slow", 3000, 1000, generalStop.Token),
                   ProcessWithTimeoutAsync("medium", 1500, 2000, generalStop.Token),
                   StopAfterAsync(1200));

// um processamento limitado a [timeout] milissegundos, que também pode ser interrompido pelo chamador
async Task ProcessWithTimeoutAsync(string name, int duration, int timeout, CancellationToken stop)
{
    // a fonte vinculada é cancelada se qualquer uma das duas causas ocorrer
    using var linked = CancellationTokenSource.CreateLinkedTokenSource(stop);
    linked.CancelAfter(timeout);
    try
    {
        Display($"3 - {await QueryAsync(name, duration, linked.Token)}");
    }
    catch (OperationCanceledException) when (stop.IsCancellationRequested)
    {
        Display($"3 - {name} : stopped at the caller's request");
    }
    catch (OperationCanceledException)
    {
        Display($"3 - {name} : timeout of {timeout} ms exceeded");
    }
}

// o chamador solicita a parada geral após [duration] milissegundos
async Task StopAfterAsync(int duration)
{
    await Task.Delay(duration);
    Display("3 - general stop requested");
    generalStop.Cancel();
}

// simula um servidor que responde após [duration] milissegundos
static async Task<string> QueryAsync(string server, int duration, CancellationToken token)
{
    await Task.Delay(duration, token);
    return $"{server} answered in {duration} ms";
}

void Display(string message)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : {message}");
}

Resultados:

1
2
3
4
5
6
7
8
> dotnet run async-14.cs
 1024 ms : 1 - TimeoutException : The operation has timed out.
 1037 ms : 1 - status of the operation: WaitingForActivation
 1001 ms : 2 - operation cancelled after one second, status: Canceled
  502 ms : 3 - fast answered in 500 ms
 1003 ms : 3 - slow : timeout of 1000 ms exceeded
 1204 ms : 3 - general stop requested
 1204 ms : 3 - medium : stopped at the caller's request

Comentários:

  • Linha 10: [t.WaitAsync(TimeSpan)] (.NET 6) retorna uma tarefa que é concluída como [t] se [t] for concluída dentro do limite de tempo, e falha com uma [TimeoutException] caso contrário. Esta é a implementação direta da “corrida” com [Task.WhenAny] do programa [async-08.cs]. Outra sobrecarga, [WaitAsync(CancellationToken)], permite parar de esperar por uma tarefa que não aceita um token;
  • Linha 18: [WaitAsync] interrompe a espera, não a operação. A operação continua (estado [WaitingForActivation]); ela consome recursos, e seu resultado será perdido;
  • Linhas 20–31: para realmente interromper a operação, é preciso passar a ela um token cancelado ao fim do período de timeout. A operação termina após 1 segundo com o estado [Canceled]. Esta é a solução preferida sempre que a operação aceita um token;
  • linhas 44–59: um processamento pode ser cancelado por vários motivos; aqui, isso se deve ao seu próprio timeout e a uma solicitação geral de parada feita pelo chamador. [CancellationTokenSource.CreateLinkedTokenSource(stop)] cria uma origem vinculada: ela é cancelada se o token [stop] for cancelado, e também pode ser cancelada por conta própria, neste caso com [CancelAfter(timeout)]. Para determinar qual das duas causas ocorreu, usa-se um filtro de exceção [when] (linha 53): o primeiro [catch] só é aceito se o chamador tiver solicitado o encerramento;
  • Linhas 38–41: três processamentos e uma parada geral solicitada em 1.200 ms. O processamento [fast] termina normalmente; o processamento [slow] excede seu limite de um segundo; o processamento [medium], ao qual haviam sido concedidos dois segundos, é encerrado pela parada geral.

9.7. Relatando o progresso: IProgress<T>

Uma operação de longa duração costuma precisar relatar seu progresso (uma barra de progresso, uma porcentagem). Com [BackgroundWorker], o processamento chamava [ReportProgress], e a interface assinava o evento [ProgressChanged]. Com tarefas, usa-se a interface [IProgress<T>], que tem apenas um método:

1
2
3
4
public interface IProgress<in T>
{
    void Report(T value);
}

A operação recebe um objeto [IProgress<T>] como parâmetro e lhe passa seus relatórios por meio de [Report]; ela desconhece como eles serão exibidos. O .NET fornece a implementação [Progress<T>], destinada a interfaces gráficas: ela armazena o contexto de sincronização da thread que a cria (a thread de UI) e executa ali o tratamento dos relatórios, o que permite atualizar os componentes gráficos sem se preocupar com threads. O curso de 2008 precisava chamar [Invoke] nos componentes gráficos usando um delegate para obter o mesmo resultado. Em um programa de console, que não tem contexto de sincronização, [Progress<T>] faz com que os relatórios sejam tratados por threads do pool, sem garantir sua ordem: o programa [async-15.cs] usa, portanto, sua própria implementação de [IProgress<T>]. Ele simula uma cópia de arquivos que o usuário pode cancelar digitando [Enter]:

// informar o progresso de uma operação com IProgress<T>; o usuário pode cancelá-la
using var cancellation = new CancellationTokenSource();
// uma tarefa em segundo plano espera o usuário digitar [Enter] para solicitar o cancelamento
_ = Task.Run(() =>
{
    Console.ReadLine();
    cancellation.Cancel();
});
Console.WriteLine("Copy in progress, type [Enter] to cancel it");

// o objeto que recebe os relatórios de progresso
IProgress<Advancement> progress = new ConsoleProgress();
try
{
    int nbFiles = await CopyAsync(8, progress, cancellation.Token);
    Console.WriteLine($"Copy finished: {nbFiles} files copied");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Copy cancelled by the user");
}

// a operação não sabe como seu progresso é exibido: ela apenas o informa
static async Task<int> CopyAsync(int nbFiles, IProgress<Advancement>? progress, CancellationToken token)
{
    for (int i = 1; i <= nbFiles; i++)
    {
        // a cópia de um arquivo
        await Task.Delay(300, token);
        // o relatório de progresso (o chamador pode não querer nenhum: progress é então null)
        progress?.Report(new Advancement(100 * i / nbFiles, $"file{i}.dat"));
    }
    return nbFiles;
}

// um relatório de progresso
record Advancement(int Percentage, string File);

// a exibição dos relatórios de progresso no console
class ConsoleProgress : IProgress<Advancement>
{
    public void Report(Advancement advancement)
    {
        // uma barra de 20 caracteres
        string bar = new string('#', advancement.Percentage / 5).PadRight(20, '.');
        Console.WriteLine($"[{bar}] {advancement.Percentage,3} % {advancement.File}");
    }
}

Resultados sem cancelamento:

> dotnet run async-15.cs
Copy in progress, type [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
[############........]  62 % file5.dat
[###############.....]  75 % file6.dat
[#################...]  87 % file7.dat
[####################] 100 % file8.dat
Copy finished: 8 files copied

Resultados quando o usuário digita [Enter] durante a operação de cópia, após um segundo e meio:

1
2
3
4
5
6
7
> dotnet run async-15.cs
Copy in progress, type [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
Copy cancelled by the user

Comentários:

  • Linhas 24–33: a operação recebe um [IProgress<Advancement>] e um token de cancelamento. Após cada arquivo, ela relata seu progresso por meio de um objeto [Advancement] (um [record] contendo a porcentagem e o nome do arquivo). O parâmetro é declarado como anulável ([IProgress<Advancement>?]) e usado com o operador [?.]: um chamador que não quer relatórios passa [null];
  • linhas 40–46: a implementação de console de [IProgress<Advancement>] exibe uma barra de 20 caracteres;
  • linhas 4–7: uma tarefa do pool espera que o usuário digite [Enter] ([Console.ReadLine] é uma leitura bloqueante, daí o [Task.Run]: é uma thread do pool que fica bloqueada, não o programa) e depois solicita o cancelamento. O programa não a espera, daí o descarte [_]: ao final do programa, essa tarefa é abandonada;
  • linhas 15–20: o programa inicia a cópia e a aguarda. Um cancelamento resulta em uma [OperationCanceledException].

9.8. Entrada/saída assíncrona

A E/S é a própria essência da assincronia. As classes do .NET oferecem uma versão assíncrona de todos os seus métodos de E/S: arquivos ([File], [FileStream], [StreamReader], [StreamWriter]), rede ([Socket], [TcpClient], [NetworkStream], [HttpClient], conforme visto no Capítulo 12), bancos de dados (ADO.NET e Entity Framework Core, Capítulos 10 e 11). O programa [async-16.cs] demonstra a E/S assíncrona de arquivos lendo o arquivo das faixas do imposto do diretório de exemplos, [TaxData.txt], localizado na pasta do programa:

1
2
3
4
5
6
7
4962:0:0
8382:0.068:291.09
14753:0.191:1322.92
23888:0.283:2668.39
38868:0.374:4846.98
47932:0.426:6883.66
0:0.481:9505.54

Cada linha contém o limite da faixa, o coeficiente [coeffR] e o coeficiente [coeffN], separados pelo caractere [:] e escritos com ponto decimal (a tabela do imposto é a de 2004 para a renda de 2003, mantida como está neste exercício). O programa é executado na pasta [09-async] e procura seus arquivos na pasta atual.

// entrada / saída assíncrona em arquivos
using System.Globalization;

const string data = "TaxData.txt";
const string report = "report-16.txt";

// 1 - leitura do arquivo inteiro em uma única operação
string[] lines = await File.ReadAllLinesAsync(data);
Console.WriteLine($"1 - File.ReadAllLinesAsync: {lines.Length} lines");

// 2 - leitura linha a linha com um StreamReader
var brackets = new List<TaxBracket>();
using (var reader = new StreamReader(data))
{
    string? line;
    // ReadLineAsync retorna null no fim do arquivo
    while ((line = await reader.ReadLineAsync()) is not null)
    {
        brackets.Add(TaxBracket.Parse(line));
    }
}
Console.WriteLine($"2 - StreamReader.ReadLineAsync: {brackets.Count} brackets, the 2nd is {brackets[1]}");

// 3 - File.ReadLinesAsync retorna um fluxo assíncrono de linhas, iterado com await foreach
int nbBrackets = 0;
await foreach (string line in File.ReadLinesAsync(data))
{
    nbBrackets++;
}
Console.WriteLine($"3 - File.ReadLinesAsync: {nbBrackets} lines");

// 4 - escrita com um StreamWriter: await using libera o fluxo de forma assíncrona
await using (var writer = new StreamWriter(report))
{
    await writer.WriteLineAsync("Brackets of the tax scale (exercise: 2004 scale on 2003 income)");
    foreach (var (bracket, i) in brackets.Select((t, i) => (t, i + 1)))
    {
        string limit = bracket.Limit == 0 ? "beyond" : $"up to {bracket.Limit:N0} €";
        await writer.WriteLineAsync($"bracket {i} : {limit,-18} rate {bracket.CoeffR:P1}");
    }
}

// 5 - leitura do arquivo inteiro como uma string
string text = await File.ReadAllTextAsync(report);
Console.Write($"4 and 5 - content of [{report}]:\n{text}");

// 6 - acréscimo no fim do arquivo e depois exclusão
await File.AppendAllTextAsync(report, "end of the report\n");
Console.WriteLine($"6 - last line: {(await File.ReadAllLinesAsync(report))[^1]}");
File.Delete(report);

// uma faixa de imposto; o arquivo usa o ponto decimal: lemos com a cultura invariante
readonly record struct TaxBracket(decimal Limit, decimal CoeffR, decimal CoeffN)
{
    public static TaxBracket Parse(string line)
    {
        string[] fields = line.Split(':');
        return new TaxBracket(decimal.Parse(fields[0], CultureInfo.InvariantCulture),
                                decimal.Parse(fields[1], CultureInfo.InvariantCulture),
                                decimal.Parse(fields[2], CultureInfo.InvariantCulture));
    }
}

Resultados:

> dotnet run async-16.cs
1 - File.ReadAllLinesAsync: 7 lines
2 - StreamReader.ReadLineAsync: 7 brackets, the 2nd is TaxBracket { Limit = 8382, CoeffR = 0.068, CoeffN = 291.09 }
3 - File.ReadLinesAsync: 7 lines
4 and 5 - content of [report-16.txt]:
Brackets of the tax scale (exercise: 2004 scale on 2003 income)
bracket 1 : up to 4,962 €      rate 0.0 %
bracket 2 : up to 8,382 €      rate 6.8 %
bracket 3 : up to 14,753 €     rate 19.1 %
bracket 4 : up to 23,888 €     rate 28.3 %
bracket 5 : up to 38,868 €     rate 37.4 %
bracket 6 : up to 47,932 €     rate 42.6 %
bracket 7 : beyond             rate 48.1 %
6 - last line: end of the report

Comentários:

  • Linha 8: [File.ReadAllLinesAsync] lê o arquivo inteiro e retorna uma [Task<string[]>]. Os métodos de leitura e escrita da classe [File] têm versões assíncronas: [ReadAllTextAsync], [ReadAllBytesAsync], [WriteAllTextAsync], [WriteAllLinesAsync], [AppendAllTextAsync]… Todos aceitam um token de cancelamento como último parâmetro;
  • linhas 13–19: leitura linha a linha com um [StreamReader]. [ReadLineAsync] retorna uma [Task<string?>], cujo resultado é [null] no fim do arquivo. Cada linha é convertida em [TaxBracket] pelo método [Parse] (linhas 55–60), que lê os números em formato de cultura invariável para que o ponto decimal seja reconhecido em uma máquina francesa;
  • linhas 26–28: [File.ReadLinesAsync] (.NET 7) retorna um fluxo assíncrono de linhas ([IAsyncEnumerable<string>]), percorrido com [await foreach]. Ao contrário de [ReadAllLinesAsync], ele não carrega o arquivo inteiro na memória: lê as linhas sob demanda. Este é o método preferido para arquivos grandes;
  • linhas 33–39: escrita com um [StreamWriter] e seu método [WriteLineAsync]. [StreamWriter] é declarado com [await using] (C# 8): ao sair do bloco, ele é liberado por seu método [DisposeAsync], que descarrega seu buffer de forma assíncrona. [await using] é usado com objetos que implementam a interface [IAsyncDisposable] ([StreamWriter], [FileStream], conexões com bancos de dados etc.); [StreamReader], que faz apenas uma leitura, implementa somente [IDisposable] e usa um [using] comum;
  • linha 36: o laço percorre as tuplas (faixa, número) produzidas por [Select] e as desconstrói;
  • Linhas 44–50: [ReadAllTextAsync] relê o arquivo escrito, [AppendAllTextAsync] acrescenta uma linha a ele e, em seguida, o arquivo é excluído. [File.Delete] não tem versão assíncrona: excluir um arquivo é uma operação muito curta.

Nota: no Windows, um [FileStream] aberto sem opções específicas executa suas operações assíncronas delegando leituras síncronas ao pool de threads; para uma E/S assíncrona real do sistema, abra-o com a opção [FileOptions.Asynchronous] (ou [useAsync: true]). Os métodos da classe [File] cuidam disso automaticamente. Para arquivos locais, a diferença raramente é perceptível; ela é perceptível nas operações de rede, em que a E/S assíncrona é sempre uma E/S assíncrona real.

9.9. Fluxos assíncronos: IAsyncEnumerable<T>

Um método assíncrono retorna um resultado depois de certo tempo. Um iterador (um método que retorna um [IEnumerable<T>] com [yield return]) retorna uma sequência de resultados, produzidos sob demanda. Os fluxos assíncronos (C# 8) combinam ambos: uma sequência de valores, cada um dos quais pode exigir uma espera assíncrona antes de ser produzido. Eles servem para ler as linhas de um arquivo grande, as linhas do resultado de uma consulta SQL, mensagens que chegam por uma conexão de rede, medições de sensores e assim por diante…

  • o tipo é [IAsyncEnumerable<T>];
  • ele é produzido por um método [async], que retorna [IAsyncEnumerable<T>] e contém tanto [await] quanto [yield return];
  • ele é consumido por [await foreach].

Já encontramos dois deles: [Task.WhenEach] e [File.ReadLinesAsync]. O programa [async-17.cs] escreve um:

// fluxos assíncronos: IAsyncEnumerable<T>, yield return, await foreach
using System.Diagnostics;
using System.Runtime.CompilerServices;

var stopwatch = Stopwatch.StartNew();

// 1 - cada valor é processado assim que é produzido
await foreach (Measure measure in ReadMeasuresAsync("sensor-1", 4))
{
    Display($"1 - received {measure}");
}

// 2 - podemos sair do laço antes do fim: o produtor também para
stopwatch.Restart();
await foreach (Measure measure in ReadMeasuresAsync("sensor-2", 100))
{
    Display($"2 - received {measure}");
    if (measure.Value >= 22)
    {
        break;
    }
}

// 3 - cancelamento: WithCancellation passa o token ao parâmetro marcado com [EnumeratorCancellation]
stopwatch.Restart();
using var source = new CancellationTokenSource(TimeSpan.FromMilliseconds(700));
try
{
    await foreach (Measure measure in ReadMeasuresAsync("sensor-3", 100).WithCancellation(source.Token))
    {
        Display($"3 - received {measure}");
    }
}
catch (OperationCanceledException)
{
    Display("3 - reading cancelled");
}

// 4 - LINQ sobre fluxos assíncronos (System.Linq.AsyncEnumerable, .NET 10)
stopwatch.Restart();
List<double> high = await ReadMeasuresAsync("sensor-4", 6)
    .Where(m => m.Value > 21)
    .Select(m => m.Value)
    .ToListAsync();
Display($"4 - measures above 21: [{string.Join(" ; ", high)}]");

// um produtor assíncrono: uma medição a cada 200 ms
static async IAsyncEnumerable<Measure> ReadMeasuresAsync(string sensor, int count,
    [EnumeratorCancellation] CancellationToken token = default)
{
    try
    {
        for (int i = 1; i <= count; i++)
        {
            // esperando a próxima medição
            await Task.Delay(200, token);
            // a medição é entregue ao consumidor; o produtor retomará aqui na próxima requisição
            yield return new Measure(sensor, i, 19.5 + i * 0.75);
        }
    }
    finally
    {
        // executado no fim normal, em um break do consumidor ou no cancelamento
        Console.WriteLine($"          {sensor} : end of the production");
    }
}

void Display(string message)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : {message}");
}

// uma medição
record Measure(string Sensor, int Number, double Value)
{
    public override string ToString() => $"{Sensor} no. {Number} : {Value} °C";
}

Resultados:

> dotnet run async-17.cs
  214 ms : 1 - received sensor-1 no. 1 : 20.25 °C
  426 ms : 1 - received sensor-1 no. 2 : 21 °C
  626 ms : 1 - received sensor-1 no. 3 : 21.75 °C
  827 ms : 1 - received sensor-1 no. 4 : 22.5 °C
          sensor-1 : end of the production
  204 ms : 2 - received sensor-2 no. 1 : 20.25 °C
  404 ms : 2 - received sensor-2 no. 2 : 21 °C
  605 ms : 2 - received sensor-2 no. 3 : 21.75 °C
  809 ms : 2 - received sensor-2 no. 4 : 22.5 °C
          sensor-2 : end of the production
  201 ms : 3 - received sensor-3 no. 1 : 20.25 °C
  404 ms : 3 - received sensor-3 no. 2 : 21 °C
  604 ms : 3 - received sensor-3 no. 3 : 21.75 °C
          sensor-3 : end of the production
  703 ms : 3 - reading cancelled
          sensor-4 : end of the production
 1213 ms : 4 - measures above 21: [21.75 ; 22.5 ; 23.25 ; 24]

Comentários:

  • Linhas 48–64: o produtor. Ele espera 200 ms ([await]) e depois entrega uma medição ([yield return]), e assim por diante. A cada [yield return], ele faz uma pausa até que o consumidor solicite o próximo valor. O bloco [finally] é executado quando o produtor para, qualquer que seja o motivo;
  • linha 49: o token de cancelamento de um fluxo assíncrono é um parâmetro marcado com o atributo [[EnumeratorCancellation]] (namespace [System.Runtime.CompilerServices]). Ele recebe [default] (um token que nunca é cancelado) se o chamador não fornecer um;
  • linhas 7–10: o laço [await foreach] espera cada medição sem bloquear uma thread e a processa assim que é produzida: uma a cada 200 ms (linhas 2–6);
  • linhas 13–20: quando o consumidor sai do laço por meio de [break], o fluxo é liberado (método [DisposeAsync], chamado por [await foreach]): o produtor não produz as 96 medições restantes e executa seu bloco [finally] (linha 11);
  • linhas 24–36: o método de extensão [WithCancellation] passa um token ao parâmetro marcado com [[EnumeratorCancellation]]. O token é cancelado após 700 ms: a espera pela 4ª medição é interrompida; uma [OperationCanceledException] atravessa o produtor (que executa seu [finally]) e depois o laço [await foreach] do consumidor;
  • Linhas 41–44: o .NET 10 incorpora o LINQ para fluxos assíncronos (classe [System.Linq.AsyncEnumerable], antes disponível no pacote NuGet [System.Linq.Async]): [Where], [Select], [Take], [FirstAsync], [ToListAsync]… aplicam-se a um [IAsyncEnumerable<T>]. Os métodos que produzem um fluxo ([Where], [Select]) retornam outro fluxo; os que produzem um valor ([ToListAsync], [CountAsync], [FirstAsync]) retornam uma tarefa que fica pendente;
  • Linha 76: o método [ToString] do [record] [Measure] é redefinido para uma exibição mais compacta.

9.10. ValueTask, ConfigureAwait e TaskCompletionSource

9.10.1. ValueTask<T>

Uma tarefa é um objeto: cada chamada a um método que retorna uma [Task<T>] (em geral) aloca um objeto no heap, que o coletor de lixo terá de recuperar. Isso é desprezível para uma E/S que dura milissegundos, mas não para um método chamado milhões de vezes por segundo que, na maioria das vezes, já tem o resultado (um cache, um buffer pré-preenchido). Para esse caso, o .NET oferece a [ValueTask<T>] struct (C# 7, 2017): ela contém diretamente o resultado (sem alocação) ou uma tarefa verdadeira quando a operação é de fato assíncrona. O programa [async-18.cs] a utiliza em um serviço de taxas de câmbio com cache:

// ValueTask<T>: um método assíncrono que, na maioria das vezes, já tem o resultado
using System.Diagnostics;

var service = new RateService();
var stopwatch = Stopwatch.StartNew();
foreach (string code in new[] { "EUR", "USD", "EUR", "EUR", "USD", "GBP", "EUR" })
{
    long start = stopwatch.ElapsedMilliseconds;
    decimal rate = await service.ReadRateAsync(code);
    Console.WriteLine($"{code} : {rate,6} read in {stopwatch.ElapsedMilliseconds - start,3} ms");
}
Console.WriteLine($"server accesses: {service.NbServerAccesses}, cache answers: {service.NbCacheAccesses}");

class RateService
{
    private readonly Dictionary<string, decimal> cache = [];
    public int NbServerAccesses { get; private set; }
    public int NbCacheAccesses { get; private set; }

    // ValueTask<decimal>: nenhuma alocação de Task quando o resultado está no cache
    public ValueTask<decimal> ReadRateAsync(string code)
    {
        if (cache.TryGetValue(code, out decimal rate))
        {
            // caminho rápido e síncrono: o resultado já é conhecido
            NbCacheAccesses++;
            return ValueTask.FromResult(rate);
        }
        // caminho lento e assíncrono: é preciso consultar o servidor
        return new ValueTask<decimal>(ReadServerRateAsync(code));
    }

    private async Task<decimal> ReadServerRateAsync(string code)
    {
        NbServerAccesses++;
        // simula a consulta a um servidor remoto
        await Task.Delay(300);
        decimal rate = code switch
        {
            "EUR" => 1m,
            "USD" => 1.17m,
            "GBP" => 0.87m,
            _ => throw new ArgumentException($"unknown currency: {code}"),
        };
        cache[code] = rate;
        return rate;
    }
}

Resultados:

1
2
3
4
5
6
7
8
9
> dotnet run async-18.cs
EUR :      1 read in 323 ms
USD :   1.17 read in 301 ms
EUR :      1 read in   0 ms
EUR :      1 read in   0 ms
USD :   1.17 read in   0 ms
GBP :   0.87 read in 301 ms
EUR :      1 read in   0 ms
server accesses: 3, cache answers: 4

Comentários:

  • Linhas 21–30: o método não é [async]. Se a taxa estiver no cache, ele retorna um [ValueTask<decimal>] que contém diretamente o resultado ([ValueTask.FromResult]): nenhum objeto é criado. Caso contrário, ele encapsula em um [async] a tarefa do método — que consulta o servidor — em um [ValueTask<decimal>];
  • linhas 33–45: a consulta simulada ao servidor (300 ms), que armazena o resultado no cache. Um método [async] também pode retornar diretamente um [ValueTask<T>];
  • linha 9: para o chamador, nada muda: ele aguarda o [ValueTask] com [await]. Os resultados mostram os 3 acessos ao servidor (300 ms cada) e as 4 respostas imediatas do cache.

[ValueTask<T>] tem restrições: ele deve ser aguardado uma única vez (nenhum par de [await] sobre o mesmo [ValueTask], nenhuma espera simultânea a partir de vários locais), e não pode ser passado diretamente a [Task.WhenAll]: é preciso antes convertê-lo em uma tarefa com [AsTask()]. A regra prática é simples: use [Task] e [Task<T>] por padrão, e [ValueTask] somente em código que, após medição, se mostrou muito solicitado e frequentemente síncrono. Você encontrará [ValueTask] principalmente como tipo de retorno de métodos do .NET: [Stream.ReadAsync(Memory<byte>)], [DisposeAsync], [ChannelWriter.WriteAsync]…

9.10.2. ConfigureAwait e o contexto de sincronização

O programa [async-05.cs] demonstrou que, no console, o restante de um método após um [await] é executado por qualquer thread do pool. Isso não ocorre em uma aplicação gráfica (Windows Forms, WPF, MAUI). Um componente gráfico só pode ser manipulado pela thread de UI: o curso de 2008 precisava usar [listBoxEvts.Invoke(...)] em seus métodos de callback para que a atualização fosse executada por essa thread. Com [await], isso não é mais necessário: a thread da interface tem um contexto de sincronização ([SynchronizationContext.Current] não é [null]), que o [await] armazena; ao fim da espera, o restante do método é devolvido a esse contexto e, assim, executado pela thread da interface. Podemos escrever:

1
2
3
4
5
6
private async void DownloadButton_Click(object sender, EventArgs e)
{
    statusLabel.Text = "downloading…";                     // thread da interface
    string page = await client.GetStringAsync(address);     // a interface continua responsiva durante a espera
    pageTextBox.Text = page;                                 // de volta à thread da interface
}

Esse retorno ao contexto original tem um custo e um risco: se um código bloqueia a thread da interface enquanto espera por uma tarefa ([task.Result]), e essa tarefa precisa dessa mesma thread para executar o restante de seu código, as duas esperarão uma pela outra indefinidamente (“deadlock”). Este é o principal motivo da regra “nada de [.Result]”.

O método [ConfigureAwait(false)] instrui o [await] a não voltar ao contexto original: [await stream.ReadAsync(buffer).ConfigureAwait(false);]. O restante do código é então executado por uma thread do pool. As recomendações são as seguintes:

  • no código de uma biblioteca de uso geral (que não trata uma interface gráfica e não sabe quem a chamará), use [ConfigureAwait(false)] em cada [await]: isso é um pouco mais eficiente e evita deadlocks se um chamador descuidado usar [.Result];
  • no código de aplicação (interface gráfica, programa de console, aplicação ASP.NET Core), ele não é escrito. De todo modo, programas de console e aplicações ASP.NET Core não têm contexto de sincronização: [ConfigureAwait(false)] não faz diferença neles.

Os exemplos deste curso, que são aplicações, não usam [ConfigureAwait].

9.10.3. TaskCompletionSource<T>: convertendo um evento em uma tarefa

Às vezes é preciso usar uma API que sinaliza o fim de suas operações por meio de um evento (o modelo EAP, ou qualquer classe que publique eventos), enquanto o restante do código é escrito com [await]. A classe [TaskCompletionSource<T>] permite criar uma tarefa que você mesmo conclui no momento desejado:

  • sua propriedade [Task] é uma [Task<T>] não concluída, que é retornada ao chamador;
  • [SetResult(value)] / [TrySetResult(value)] conclui a tarefa com sucesso;
  • [SetException(exception)] / [TrySetException(exception)] a encerra com uma falha;
  • [SetCanceled()] / [TrySetCanceled()] a cancela.

Os métodos [TryXxx] retornam [false] em vez de lançar uma exceção se a tarefa já tiver sido concluída. De fato, foi uma [TaskCompletionSource<int>] que a máquina de estados simplificada do método [CountSugarsAsync] apresentado acima utilizou. O programa [async-19.cs] espera que um termômetro, que publica suas medições por meio de um evento, atinja uma certa temperatura:

// TaskCompletionSource<T>: transformar uma API baseada em eventos em uma tarefa
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();
var thermometer = new Thermometer();
thermometer.Start();

// 1 - esperamos, sem bloquear uma thread, a primeira medição maior ou igual a 21 °C
double measure = await WaitForTemperatureAsync(thermometer, 21, CancellationToken.None);
Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : 1 - temperature reached: {measure} °C");

// 2 - a mesma espera, limitada a um segundo: a tarefa é cancelada
using (var timeout = new CancellationTokenSource(1000))
{
    try
    {
        measure = await WaitForTemperatureAsync(thermometer, 30, timeout.Token);
        Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : 2 - temperature reached: {measure} °C");
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : 2 - 30 °C not reached within one second");
    }
}
thermometer.Stop();

// transforma os eventos MeasureTaken do termômetro em uma tarefa
static Task<double> WaitForTemperatureAsync(Thermometer thermometer, double threshold, CancellationToken token)
{
    // a fonte de uma tarefa que nós mesmos completamos
    var source = new TaskCompletionSource<double>(TaskCreationOptions.RunContinuationsAsynchronously);
    // o registro no token de cancelamento, a liberar quando a tarefa terminar
    CancellationTokenRegistration registration = default;
    // o manipulador de evento completa a tarefa quando o limite é atingido
    void OnMeasure(object? sender, double temperature)
    {
        if (temperature >= threshold && source.TrySetResult(temperature))
        {
            thermometer.MeasureTaken -= OnMeasure;
            registration.Dispose();
        }
    }
    thermometer.MeasureTaken += OnMeasure;
    // uma solicitação de cancelamento completa a tarefa com o status Canceled
    registration = token.Register(() =>
    {
        if (source.TrySetCanceled(token))
        {
            thermometer.MeasureTaken -= OnMeasure;
        }
    });
    // a tarefa é retornada imediatamente; ela será concluída mais tarde
    return source.Task;
}

// um termômetro que publica uma medição a cada 200 ms por meio de um evento (API "à moda antiga")
class Thermometer
{
    public event EventHandler<double>? MeasureTaken;
    private Timer? timer;
    private double temperature = 19;

    public void Start()
    {
        timer = new Timer(_ =>
        {
            temperature += 0.5;
            Console.WriteLine($"          measure: {temperature} °C");
            MeasureTaken?.Invoke(this, temperature);
        }, null, 200, 200);
    }

    public void Stop()
    {
        timer?.Dispose();
    }
}

Resultados:

> dotnet run async-19.cs
          measure: 19.5 °C
          measure: 20 °C
          measure: 20.5 °C
          measure: 21 °C
  805 ms : 1 - temperature reached: 21 °C
          measure: 21.5 °C
          measure: 22 °C
          measure: 22.5 °C
          measure: 23 °C
          measure: 23.5 °C
 1812 ms : 2 - 30 °C not reached within one second

Comentários:

  • Linhas 57–75: o termômetro, uma classe “à moda antiga”: um timer ([System.Threading.Timer], que executa um método em intervalos regulares em uma thread do pool) aumenta a temperatura em 0,5 °C a cada 200 ms e a publica por meio do evento [MeasureTaken], do tipo [EventHandler<double>] (os eventos foram tratados no Capítulo 7);
  • linhas 28–53: o método que converte eventos em uma tarefa. Ele não é [async]: cria um [TaskCompletionSource<double>], assina um manipulador no evento e retorna imediatamente a tarefa da origem, que ainda não está concluída;
  • Linha 31: esta opção especifica que o código restante que aguarda a tarefa não deve ser executado pela thread que chama [TrySetResult] (neste caso, a thread do timer, no meio da emissão do evento), mas por uma thread do pool. Esta é a opção recomendada em quase todos os casos;
  • linhas 35–40: a cada medição, o manipulador verifica o limite. Quando ele é atingido, o manipulador encerra a tarefa com a temperatura como resultado, depois cancela a assinatura do evento e libera o registro junto ao token de cancelamento;
  • linhas 45–47: [token.Register(action)] registra uma ação a ser executada se o cancelamento for solicitado. Aqui, ela cancela a tarefa (estado [Canceled]) e cancela a assinatura do manipulador. Sem isso, uma tarefa que espera um limite nunca atingido jamais terminaria;
  • linhas 9–22: para o chamador, esperar por uma temperatura é um método assíncrono como qualquer outro: ele é aguardado com [await] e limitado no tempo por um token de cancelamento.

[Task.Factory.FromAsync], mencionado acima, desempenha o mesmo papel para as APIs do modelo APM ([BeginXxx] / [EndXxx]).

9.11. Paralelismo assíncrono

9.11.1. Parallel.ForEachAsync

[Task.WhenAll] dispara todas as operações ao mesmo tempo. Isso nem sempre é desejável: para baixar 10.000 páginas web, você não quer abrir 10.000 conexões simultâneas com o mesmo servidor. O capítulo anterior apresentou [Parallel.ForEach], que distribui o processamento de uma coleção entre várias threads; sua versão assíncrona, [Parallel.ForEachAsync] (.NET 6), processa os elementos de uma coleção usando uma função assíncrona, limitando o número de operações concorrentes. O programa [async-20.cs] baixa nove páginas, no máximo três por vez:

// Parallel.ForEachAsync: processar uma coleção com um número limitado de operações simultâneas
using System.Diagnostics;

var stopwatch = Stopwatch.StartNew();
string[] pages = [.. Enumerable.Range(1, 9).Select(i => $"page{i}.html")];
int inProgress = 0;

// no máximo 3 downloads ao mesmo tempo
var options = new ParallelOptions { MaxDegreeOfParallelism = 3 };
await Parallel.ForEachAsync(pages, options, async (page, token) =>
{
    // contador compartilhado pelas operações simultâneas: nós o modificamos de forma atômica
    int n = Interlocked.Increment(ref inProgress);
    Display($"start of {page} ({n} in progress)");
    // o download simulado de uma página
    await Task.Delay(1000, token);
    Interlocked.Decrement(ref inProgress);
    Display($"end of {page}");
});
Display($"the {pages.Length} pages are downloaded");

void Display(string message)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms [thread {Environment.CurrentManagedThreadId,2}] : {message}");
}

Resultados:

> dotnet run async-20.cs
   12 ms [thread  4] : start of page1.html (1 in progress)
   12 ms [thread  6] : start of page2.html (2 in progress)
   29 ms [thread  6] : start of page3.html (3 in progress)
 1024 ms [thread  6] : end of page1.html
 1025 ms [thread  6] : start of page4.html (3 in progress)
 1028 ms [thread  4] : end of page3.html
 1028 ms [thread  6] : end of page2.html
 1029 ms [thread  4] : start of page5.html (2 in progress)
 1029 ms [thread  6] : start of page6.html (3 in progress)
 2023 ms [thread  6] : end of page4.html
 2023 ms [thread  6] : start of page7.html (3 in progress)
 2028 ms [thread  6] : end of page6.html
 2028 ms [thread  6] : start of page8.html (3 in progress)
 2030 ms [thread  4] : end of page5.html
 2030 ms [thread  4] : start of page9.html (3 in progress)
 3025 ms [thread  8] : end of page9.html
 3026 ms [thread  8] : end of page7.html
 3025 ms [thread  4] : end of page8.html
 3026 ms [thread  4] : the 9 pages are downloaded

Comentários:

  • linha 5: os nomes das nove páginas, construídos com uma expressão de coleção com o operador de espalhamento [..];
  • linha 9: a propriedade [MaxDegreeOfParallelism] de [ParallelOptions] define o número máximo de operações concorrentes (por padrão, o número de processadores). Um token de cancelamento ([CancellationToken]) também pode ser definido aqui;
  • Linhas 10–18: [Parallel.ForEachAsync] recebe a coleção, as opções e uma função assíncrona (uma lambda [async]) que é chamada para cada elemento com o elemento e um token de cancelamento, a ser repassado às operações assíncronas da função. [Parallel.ForEachAsync] retorna uma tarefa que é concluída quando todos os elementos foram processados;
  • linhas 13–17: as funções são executadas simultaneamente em várias threads: o contador [inProgress] que elas compartilham é modificado atomicamente por meio da classe [Interlocked] do capítulo anterior;
  • Os resultados mostram três ondas de três páginas: assim que uma página termina, outra começa, e o número de downloads em andamento nunca excede 3. O processo inteiro leva 3 segundos em vez de 9. Quando duas threads escrevem quase ao mesmo tempo, a ordem das linhas pode variar de uma execução para outra, e um horário exibido pode até ser ligeiramente anterior ao da linha precedente;
  • apenas duas ou três threads executaram todas as funções: durante os períodos de espera, nenhuma thread fica ocupada.

9.11.2. Produtor/consumidor: System.Threading.Channels

O capítulo anterior apresentou o padrão produtor/consumidor com a coleção [BlockingCollection<T>]: threads produtoras enfileiram elementos em uma fila, e threads consumidoras os desenfileiram; [Take] (ou a enumeração [GetConsumingEnumerable]) bloqueia um consumidor enquanto a fila estiver vazia, e [Add] bloqueia um produtor enquanto uma fila limitada estiver cheia. Essas esperas bloqueiam threads. Os canais do namespace [System.Threading.Channels] (.NET Core 3.0) prestam o mesmo serviço com esperas assíncronas:

  • [Channel.CreateBounded<T>(capacity)] cria um canal limitado, [Channel.CreateUnbounded<T>()] cria um canal ilimitado;
  • a propriedade [Writer] ([ChannelWriter<T>]) é usada pelos produtores: [WriteAsync] publica um item (esperando de forma assíncrona que haja espaço disponível), [TryWrite] tenta adicioná-lo imediatamente, [Complete] indica que não haverá mais elementos;
  • A propriedade [Reader] ([ChannelReader<T>]) é usada pelos consumidores: [ReadAsync] recupera um elemento, enquanto [ReadAllAsync] retorna um fluxo assíncrono de todos os elementos, que termina quando o canal é fechado por [Complete] e está vazio.

O programa [async-21.cs] processa pedidos, gerados a cada 50 ms, usando dois consumidores que levam 400 ms cada um para processar um pedido:

// produtor / consumidores com um canal (System.Threading.Channels)
using System.Diagnostics;
using System.Threading.Channels;

var stopwatch = Stopwatch.StartNew();
// um canal limitado: contém no máximo 2 pedidos aguardando processamento
Channel<int> channel = Channel.CreateBounded<int>(2);

// o produtor e dois consumidores trabalham ao mesmo tempo
Task producer = ProduceAsync(channel.Writer, 8);
Task consumer1 = ConsumeAsync("C1", channel.Reader);
Task consumer2 = ConsumeAsync("C2", channel.Reader);
await Task.WhenAll(producer, consumer1, consumer2);
Display("all the orders have been processed");

// o produtor: um pedido a cada 50 ms
async Task ProduceAsync(ChannelWriter<int> writer, int nbOrders)
{
    for (int i = 1; i <= nbOrders; i++)
    {
        await Task.Delay(50);
        // TryWrite descarta o pedido imediatamente se não houver espaço no canal
        if (writer.TryWrite(i))
        {
            Display($"P  : order {i} dropped");
        }
        else
        {
            // canal cheio: WriteAsync espera (sem bloquear uma thread) que uma vaga seja liberada
            Display($"P  : channel full, order {i} waits");
            await writer.WriteAsync(i);
            Display($"P  : order {i} dropped");
        }
    }
    // nada mais será escrito: os consumidores sairão de seu laço
    writer.Complete();
    Display("P  : end of the production");
}

// um consumidor: processar um pedido leva 400 ms
async Task ConsumeAsync(string name, ChannelReader<int> reader)
{
    // ReadAllAsync retorna um fluxo assíncrono que termina quando o canal é fechado e está vazio
    await foreach (int order in reader.ReadAllAsync())
    {
        Display($"{name} : processing of order {order}");
        await Task.Delay(400);
    }
    Display($"{name} : no more orders");
}

void Display(string message)
{
    Console.WriteLine($"{stopwatch.ElapsedMilliseconds,5} ms : {message}");
}

Resultados:

> dotnet run async-21.cs
   63 ms : C1 : processing of order 1
   63 ms : P  : order 1 dropped
  130 ms : P  : order 2 dropped
  130 ms : C2 : processing of order 2
  181 ms : P  : order 3 dropped
  233 ms : P  : order 4 dropped
  284 ms : P  : channel full, order 5 waits
  479 ms : P  : order 5 dropped
  479 ms : C1 : processing of order 3
  530 ms : P  : channel full, order 6 waits
  530 ms : C2 : processing of order 4
  530 ms : P  : order 6 dropped
  583 ms : P  : channel full, order 7 waits
  879 ms : C1 : processing of order 5
  879 ms : P  : order 7 dropped
  930 ms : P  : channel full, order 8 waits
  930 ms : C2 : processing of order 6
  930 ms : P  : order 8 dropped
  935 ms : P  : end of the production
 1277 ms : C1 : processing of order 7
 1330 ms : C2 : processing of order 8
 1679 ms : C1 : no more orders
 1731 ms : C2 : no more orders
 1731 ms : all the orders have been processed

Comentários:

  • linha 7: uma fila de inteiros (contendo os números dos pedidos) que comporta no máximo 2 pedidos pendentes;
  • Linhas 10–13: o produtor e os dois consumidores são três métodos assíncronos disparados simultaneamente; o programa espera que os três terminem;
  • linhas 23–31: o produtor tenta enviar cada pedido com [TryWrite]. Se o canal estiver cheio, ele sinaliza isso e espera que haja espaço disponível com [WriteAsync]: o produtor é freado ao ritmo dos consumidores (linhas 8–9), sem que nenhuma thread seja bloqueada. Este é o benefício de um canal limitado: um produtor rápido demais não consegue encher a memória;
  • linha 36: a produção terminou. Os consumidores esvaziarão o canal e depois sairão de seu laço;
  • linhas 44–49: cada consumidor processa o fluxo assíncrono [ReadAllAsync]. Um pedido é entregue a apenas um consumidor: os pedidos são distribuídos entre C1 e C2 conforme a disponibilidade deles;
  • Como no exemplo anterior, duas linhas exibidas quase ao mesmo tempo podem aparecer fora de ordem (os horários exibidos, portanto, nem sempre estão em ordem crescente).

Os canais são a ferramenta moderna para o padrão produtor/consumidor, tanto entre métodos assíncronos quanto entre threads.

9.12. Tempo: PeriodicTimer e TimeProvider

Duas classes recentes completam as ferramentas relacionadas ao tempo:

  • [PeriodicTimer] (.NET 6) é um timer usado com [await]: seu método [WaitForNextTickAsync] retorna uma tarefa que é concluída no próximo “tique”. Ao contrário de [System.Threading.Timer] (usado em [async-19.cs]), que chama um método de callback em uma thread do pool — possivelmente enquanto a chamada anterior ainda está em andamento —, [PeriodicTimer] é escrito como um simples laço e nunca sobrepõe duas execuções;
  • [TimeProvider] (.NET 8) é uma classe abstrata que representa o relógio: a hora atual ([GetUtcNow], [GetLocalNow]), a medição de tempo ([GetTimestamp], [GetElapsedTime]) e a criação de timers. [TimeProvider.System] é o relógio do sistema. Uma classe que depende da hora recebe um [TimeProvider] em vez de usar [DateTime.Now] diretamente: ela pode então ser testada com um relógio controlado.

O programa [async-22.cs] usa ambos:

// tempo: PeriodicTimer e TimeProvider
// 1 - PeriodicTimer: uma ação a cada 500 ms, interrompida após 2,2 segundos
TimeProvider clock = TimeProvider.System;
long start = clock.GetTimestamp();
using (var timer = new PeriodicTimer(TimeSpan.FromMilliseconds(500)))
using (var stop = new CancellationTokenSource(TimeSpan.FromSeconds(2.2)))
{
    int nbTicks = 0;
    try
    {
        // WaitForNextTickAsync retorna true a cada tique, false se o timer for interrompido por Dispose
        while (await timer.WaitForNextTickAsync(stop.Token))
        {
            nbTicks++;
            Console.WriteLine($"{clock.GetElapsedTime(start).TotalMilliseconds,6:F0} ms : tick no. {nbTicks}");
        }
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine($"{clock.GetElapsedTime(start).TotalMilliseconds,6:F0} ms : timer stopped after {nbTicks} ticks");
    }
}

// 2 - TimeProvider: uma classe que depende do tempo recebe seu relógio em vez de ler DateTime.Now
var morning = new FixedClock(new DateTimeOffset(2026, 10, 3, 9, 30, 0, TimeSpan.Zero));
var evening = new FixedClock(new DateTimeOffset(2026, 10, 3, 19, 45, 0, TimeSpan.Zero));
Console.WriteLine(new Welcome(morning).Greet("Pierre"));
Console.WriteLine(new Welcome(evening).Greet("Pierre"));

// uma classe que depende da hora atual
class Welcome(TimeProvider clock)
{
    public string Greet(string name)
    {
        DateTimeOffset now = clock.GetLocalNow();
        string greeting = now.Hour < 18 ? "Hello" : "Good evening";
        return $"[{now:dd/MM/yyyy HH:mm}] {greeting} {name}";
    }
}

// um relógio parado, para os testes: ele sempre informa a mesma hora (em tempo universal)
class FixedClock(DateTimeOffset instant) : TimeProvider
{
    public override DateTimeOffset GetUtcNow() => instant;
    public override TimeZoneInfo LocalTimeZone => TimeZoneInfo.Utc;
}

Resultados:

1
2
3
4
5
6
7
8
> dotnet run async-22.cs
   507 ms : tick no. 1
  1003 ms : tick no. 2
  1505 ms : tick no. 3
  2001 ms : tick no. 4
  2227 ms : timer stopped after 4 ticks
[03/10/2026 09:30] Hello Pierre
[03/10/2026 19:45] Good evening Pierre

Comentários:

  • Linhas 5–20: um timer de 500 ms e uma origem de cancelamento de 2,2 segundos. [WaitForNextTickAsync(token)] retorna [true] a cada pulso do relógio e [false] se o timer tiver sido liberado ([Dispose]); aqui, o cancelamento interrompe o laço após 4 tiques;
  • linha 4: [GetTimestamp] e [GetElapsedTime] de [TimeProvider] medem uma duração, assim como os métodos de mesmo nome de [Stopwatch];
  • Linhas 31–37: a classe [Welcome] diz “Hello” ou “Good evening” conforme a hora. Ela recebe seu relógio em seu construtor primário, em vez de ler [DateTime.Now]: trata-se de uma dependência injetada, assim como a camada [dao] é injetada na camada [business] no Capítulo 6;
  • Linhas 42–45: um relógio parado, derivado de [TimeProvider], que redefine a hora universal e o fuso horário. Ele permite verificar o comportamento de [Welcome] pela manhã e à noite sem precisar esperar o anoitecer. O pacote NuGet [Microsoft.Extensions.TimeProvider.Testing] fornece um relógio de teste mais completo, [FakeTimeProvider], que pode ser avançado à vontade, inclusive para atrasos e timers ([Task.Delay(TimeSpan, TimeProvider)], [new PeriodicTimer(TimeSpan, TimeProvider)]).

9.13. Aplicação: cálculo do imposto com E/S assíncrona

O programa [async-23.cs] reúne várias ferramentas deste capítulo em torno do cálculo do imposto que percorre todo o curso. Ele lê as faixas do imposto do arquivo [TaxData.txt] (já utilizado) e lê uma lista de contribuintes do arquivo [taxpayers.txt]:

1
2
3
4
5
6
7
y 2 60000
y 3 60000
n 0 60000
n 2 25000
y 5 120000
x 1 20000
y 1 -5

(cada linha contém: casado [y/n], número de filhos, salário anual), calcula o imposto de cada contribuinte e grava os resultados no arquivo [results.txt]. Todas as operações de E/S são assíncronas, e o processo inteiro é limitado a 10 segundos.

// aplicação: o cálculo do imposto com entrada / saída assíncrona
// - as faixas são lidas de [TaxData.txt], os contribuintes de [taxpayers.txt]
// - os resultados são gravados em [results.txt]
using System.Globalization;

using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(10));
try
{
    TaxBracket[] brackets = await LoadBracketsAsync("TaxData.txt", cancellation.Token);
    int nbResults = await CalculateTaxesAsync(brackets, "taxpayers.txt", "results.txt", cancellation.Token);
    Console.WriteLine($"{nbResults} lines written to [results.txt]:");
    Console.Write(await File.ReadAllTextAsync("results.txt", cancellation.Token));
}
catch (OperationCanceledException)
{
    Console.WriteLine("processing abandoned: timeout exceeded");
}
catch (Exception e) when (e is IOException or FormatException)
{
    Console.WriteLine($"error: {e.GetType().Name} : {e.Message}");
}

// lê as faixas de imposto (limite:coeffR:coeffN, ponto decimal)
static async Task<TaxBracket[]> LoadBracketsAsync(string file, CancellationToken token)
{
    string[] lines = await File.ReadAllLinesAsync(file, token);
    return [.. lines.Where(l => l.Trim() != "").Select(TaxBracket.Parse)];
}

// lê os contribuintes (casado filhos salário), calcula seu imposto e grava os resultados
static async Task<int> CalculateTaxesAsync(TaxBracket[] brackets, string input, string output, CancellationToken token)
{
    int nbLines = 0;
    await using var writer = new StreamWriter(output);
    await foreach (string line in File.ReadLinesAsync(input, token))
    {
        string[] fields = line.Split(' ', StringSplitOptions.RemoveEmptyEntries);
        string result = fields switch
        {
            [var m, var c, var s] when m is "y" or "n" && int.TryParse(c, out int children) && children >= 0
                                       && int.TryParse(s, out int salary) && salary >= 0
                => $"tax = {CalculateTax(brackets, m == "y", children, salary)} €",
            _ => "incorrect line",
        };
        await writer.WriteLineAsync($"{line,-12} : {result}");
        nbLines++;
    }
    return nbLines;
}

// o cálculo do imposto (tabela de 2004 sobre a renda de 2003, mantida para o exercício)
static int CalculateTax(TaxBracket[] brackets, bool married, int nbChildren, int salary)
{
    decimal shares = married ? nbChildren / 2m + 2 : nbChildren / 2m + 1;
    if (nbChildren >= 3)
    {
        shares += 0.5m;
    }
    decimal income = 0.72m * salary;
    decimal quotient = income / shares;
    // a primeira faixa cujo limite excede o quociente familiar, senão a última
    TaxBracket bracket = brackets.FirstOrDefault(t => quotient <= t.Limit, brackets[^1]);
    return (int)(bracket.CoeffR * income - bracket.CoeffN * shares);
}

// uma faixa de imposto
readonly record struct TaxBracket(decimal Limit, decimal CoeffR, decimal CoeffN)
{
    public static TaxBracket Parse(string line)
    {
        string[] fields = line.Split(':');
        return new TaxBracket(decimal.Parse(fields[0], CultureInfo.InvariantCulture),
                                decimal.Parse(fields[1], CultureInfo.InvariantCulture),
                                decimal.Parse(fields[2], CultureInfo.InvariantCulture));
    }
}

Resultados:

1
2
3
4
5
6
7
8
9
> dotnet run async-23.cs
7 lines written to [results.txt]:
y 2 60000    : tax = 4282 €
y 3 60000    : tax = 2959 €
n 0 60000    : tax = 11519 €
n 2 25000    : tax = 792 €
y 5 120000   : tax = 11109 €
x 1 20000    : incorrect line
y 1 -5       : incorrect line

Comentários:

  • linha 6: uma origem de cancelamento que limita o processo inteiro a 10 segundos. Seu token é passado a todos os métodos assíncronos;
  • Linhas 24–27: leitura das faixas. A expressão de coleção com espalhamento [[.. sequence]] converte a sequência LINQ em um array;
  • Linhas 31–48: processamento dos contribuintes. As linhas são lidas uma a uma por meio do fluxo assíncrono [File.ReadLinesAsync], e os resultados são gravados com [WriteLineAsync] em um [StreamWriter] liberado por [await using];
  • Linhas 38–43: validação de uma linha com uma expressão [switch] com um padrão de lista de três elementos ([[var m, var c, var s]]) e uma cláusula [when] que verifica os três campos;
  • linhas 52–63: o cálculo do imposto. O método [FirstOrDefault] do LINQ, com um valor padrão, retorna a primeira faixa cujo limite é maior ou igual ao quociente familiar, ou a última faixa se nenhuma se aplicar (sem modificar os dados, ao contrário do código de 2008);
  • linhas 14–20: os erros possíveis são tratados em um único local do programa principal: violações do limite de tempo e erros de E/S ou de formato (arquivo ausente, número digitado incorretamente), filtrados por [when] com um padrão [or];
  • Os resultados fornecem os valores de referência: € 4.282 para um casal com 2 filhos e renda conjunta de € 60.000; € 2.959 com 3 filhos; e € 11.519 para uma pessoa solteira sem filhos.

O cálculo em si é síncrono: ele não realiza E/S e leva alguns microssegundos. Seria inútil — e até prejudicial — torná-lo assíncrono. Somente as operações que envolvem espera são tornadas assíncronas.

9.14. As regras de ouro

Resumamos as regras da programação assíncrona com .NET:

  • async até o fim: um método que espera uma operação assíncrona torna-se ele próprio assíncrono ([async Task]), e o mesmo vale para seus chamadores, até o ponto de entrada ([Main] assíncrono, manipulador de evento, action de controller do ASP.NET Core). Misturar código assíncrono com esperas bloqueantes anula os benefícios da assincronia;
  • não use [.Result], [.Wait()] nem [Task.WaitAll] em uma tarefa não concluída: use [await], [Task.WhenAll], [Task.WhenAny] ou [Task.WhenEach] no lugar. Essas formas bloqueantes congelam uma thread e podem causar deadlocks permanentes em aplicações gráficas;
  • não use [Thread.Sleep] em código assíncrono: use [await Task.Delay(...)] no lugar;
  • não escreva métodos [async void], exceto em manipuladores de eventos de GUI; um método assíncrono deve usar [Task] ou [Task<T>] (em casos excepcionais, [ValueTask<T>]);
  • o nome de um método assíncrono termina com [Async]: [CalculateTaxesAsync], [ReadRateAsync];
  • um método assíncrono cancelável recebe um [CancellationToken] como último parâmetro e o repassa a todas as operações assíncronas que chama; uma operação cancelada termina com uma [OperationCanceledException];
  • [Task.Run] é reservado para cálculos que você quer executar em segundo plano (para evitar bloquear uma thread de GUI, por exemplo). Não encapsule uma operação de E/S síncrona em [Task.Run] para “torná-la assíncrona”: use a versão [XxxAsync] da operação;
  • inicie primeiro, espere depois: para executar várias operações independentes simultaneamente, inicie todas e depois espere por elas com [Task.WhenAll]; para limitar o número de operações, use [Parallel.ForEachAsync] ou um canal;
  • [ConfigureAwait(false)] é usado em bibliotecas, não em aplicações;
  • uma tarefa iniciada deve ser aguardada (ou explicitamente ignorada com [_ =], tratando suas exceções): uma tarefa esquecida esconde suas exceções e pode ser interrompida pelo fim do programa.

A tabela a seguir resume as equivalências entre o mundo das threads (capítulo anterior, curso de 2008) e o das tarefas:

Threads, esperas bloqueantes
Tarefas, esperas assíncronas
[Thread.Sleep(1000)]
[await Task.Delay(1000)]
[thread.Start()] seguido de [thread.Join()]
[var t = MethodAsync();] depois [await t]
Esperar várias threads ([Join] em um laço, [Task.WaitAll])
[await Task.WhenAll(...)]
[Thread.Abort()] (obsoleto), [BackgroundWorker.CancelAsync]
[CancellationTokenSource.Cancel()] e [CancellationToken]
[BackgroundWorker.ReportProgress] / [ProgressChanged]
[IProgress<T>.Report]
[BackgroundWorker.RunWorkerCompleted]
O código que segue o [await]
[BeginXxx] / [EndXxx] e métodos de callback (APM)
[await XxxAsync(...)]
[Control.Invoke] para voltar à thread da interface
[await], que volta automaticamente ao contexto de sincronização
[BlockingCollection<T>] ([Add] / [GetConsumingEnumerable])
[Channel<T>] ([WriteAsync] / [ReadAllAsync])
[System.Threading.Timer]
[PeriodicTimer]

Os próximos capítulos aplicarão essas regras: acesso assíncrono a bancos de dados com ADO.NET (Capítulo 10) e Entity Framework Core (Capítulo 11), servidor TCP assíncrono multicliente e cliente [HttpClient] (Capítulo 12), serviços web ASP.NET Core e seus clientes [HttpClient] (Capítulo 13).