C# Cancelamento

Um download está demorando e a Ana clica em Cancelar. Uma busca passou de 5 segundos e o programa deve desistir. A Ana aperta Ctrl+C e quer que o programa salve o arquivo antes de fechar. Em todos esses casos, alguém precisa pedir para uma tarefa parar, e a tarefa precisa ouvir o pedido. No .NET, isso é feito com uma dupla: o CancellationTokenSource ("fonte do sinal de cancelamento") e o CancellationToken ("sinal de cancelamento").

Todas as saídas desta aula são reais: foram feitas com o .NET 10 (10.0.112) na máquina fictícia da Ana, na pasta ~/cs/cancelar, com dotnet run arquivo.cs. Os programas usam async, await e Task (veja async e await e Task).

A ideia: o juiz e o apito

Num jogo de futebol, o juiz não entra em campo e arranca a bola do pé de ninguém. Ele apita, e os jogadores, que estão sempre de ouvido atento, param a jogada. Se um jogador estiver no meio de um chute, ele termina o chute e então para. Ninguém é derrubado à força.

O cancelamento no .NET funciona igual: é um pedido, não uma ordem à força. O .NET nunca "mata" uma tarefa no meio de uma linha (isso poderia deixar um arquivo pela metade). A própria tarefa confere o sinal de tempos em tempos e para num ponto seguro.

A separação é de propósito: o método que baixa o arquivo recebe só o CancellationToken. Ele pode saber que pediram para parar, mas não pode cancelar o trabalho dos outros.

1. O primeiro cancelamento

A Ana baixa um arquivo em 10 partes, de 100 milissegundos cada. Depois de 350 milissegundos, ela clica em Cancelar:

using var cts = new CancellationTokenSource();

Task baixar = Baixar(cts.Token);

await Task.Delay(350);
Console.WriteLine("Ana clicou em Cancelar");
cts.Cancel();

try
{
    await baixar;
}
catch (OperationCanceledException)
{
    Console.WriteLine("Download cancelado.");
}

static async Task Baixar(CancellationToken token)
{
    for (int parte = 1; parte <= 10; parte++)
    {
        token.ThrowIfCancellationRequested();
        Console.WriteLine($"Baixando parte {parte} de 10...");
        await Task.Delay(100);
    }
    Console.WriteLine("Download completo!");
}

$ dotnet run download.cs
Baixando parte 1 de 10...
Baixando parte 2 de 10...
Baixando parte 3 de 10...
Baixando parte 4 de 10...
Ana clicou em Cancelar
Download cancelado.

Linha por linha:

using var cts = new CancellationTokenSource();

Cria o "juiz" (o nome cts é a sigla do tipo, e é o nome que quase todo mundo usa). O using libera os recursos dele no fim do programa (veja using e IDisposable).

Task baixar = Baixar(cts.Token);

Começa o download e entrega a ele o sinal, cts.Token. Repare que não há await aqui: o download segue sozinho enquanto o programa principal continua (veja Task).

await Task.Delay(350);

Espera 350 milissegundos: é a Ana olhando a barra de progresso.

cts.Cancel();

"Cancele": o apito. A partir daqui, cts.Token passa a dizer que o cancelamento foi pedido. Só isso: o Cancel() não para nada sozinho.

await baixar;

Espera o download terminar (de um jeito ou de outro).

catch (OperationCanceledException)

Quando uma tarefa para por cancelamento, ela termina com essa exceção ("exceção de operação cancelada"). Aqui, ela é o jeito normal de dizer "parei porque pediram", e o programa a trata com uma mensagem amigável.

CancellationToken token

O método que faz o trabalho recebe o sinal como parâmetro. Por costume, ele é o último parâmetro e se chama token ou cancellationToken.

token.ThrowIfCancellationRequested();

"Lance uma exceção se o cancelamento foi pedido". Se ninguém apitou, não faz nada e o laço segue. Se apitaram, lança a OperationCanceledException e o método para ali. É o jogador olhando para o juiz antes de cada jogada.

O momento exato em que o cancelamento chega depende do relógio (a Ana viu 4 partes; noutra execução poderiam ser 3). O que não muda é a ordem: a tarefa só para quando chega ao próximo ThrowIfCancellationRequested().

using var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
int parte = 0;

try
{
    for (parte = 1; parte <= 10; parte++)
    {
        Console.WriteLine($"Parte {parte}");

        if (parte == 3)
        {
            cts.Cancel(); // a Ana clicou em Cancelar
        }
    }
    Console.WriteLine("Download completo!");
}
catch (OperationCanceledException)
{
    Console.WriteLine($"Download cancelado na parte {parte}.");
}

using var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
int parte = 0;

try
{
    for (parte = 1; parte <= 10; parte++)
    {
        token.ThrowIfCancellationRequested();
        Console.WriteLine($"Parte {parte}");

        if (parte == 3)
        {
            cts.Cancel(); // a Ana clicou em Cancelar
        }
    }
    Console.WriteLine("Download completo!");
}
catch (OperationCanceledException)
{
    Console.WriteLine($"Download cancelado na parte {parte}.");
}

2. Passar o token para o .NET

Quase todo método do .NET que pode demorar aceita um CancellationToken no fim: Task.Delay(100, token), File.ReadAllTextAsync(caminho, token), HttpClient.GetStringAsync(endereço, token). Passando o token adiante, a espera é interrompida na hora, sem precisar chegar ao próximo ThrowIfCancellationRequested():

«… o começo, igual ao download.cs …»
catch (OperationCanceledException e)
{
    Console.WriteLine($"Download cancelado ({e.GetType().Name}).");
}

static async Task Baixar(CancellationToken token)
{
    for (int parte = 1; parte <= 10; parte++)
    {
        Console.WriteLine($"Baixando parte {parte} de 10...");
        await Task.Delay(100, token);
    }
    Console.WriteLine("Download completo!");
}

$ dotnet run download2.cs
Baixando parte 1 de 10...
Baixando parte 2 de 10...
Baixando parte 3 de 10...
Baixando parte 4 de 10...
Ana clicou em Cancelar
Download cancelado (TaskCanceledException).

await Task.Delay(100, token);

"Espere 100 milissegundos, mas pare se o token apitar." A espera da parte 4 foi interrompida no meio.

TaskCanceledException

O Task.Delay avisa com a TaskCanceledException ("exceção de tarefa cancelada"), que é uma filha da OperationCanceledException (veja Herança). Por isso o mesmo catch (OperationCanceledException) pega as duas. Prefira sempre pegar a mãe.

A mensagem e o token da exceção

using var cts = new CancellationTokenSource();
cts.Cancel();
try
{
    cts.Token.ThrowIfCancellationRequested();
}
catch (OperationCanceledException e)
{
    Console.WriteLine(e.GetType().FullName);
    Console.WriteLine(e.Message);
    Console.WriteLine(e.CancellationToken == cts.Token);
}

$ dotnet run excecao.cs
System.OperationCanceledException
The operation was canceled.
True

A mensagem vem em inglês ("a operação foi cancelada"), como todas as exceções do .NET no Linux. A propriedade e.CancellationToken diz qual token causou o cancelamento: útil quando há mais de um (seção 5).

3. Parar com calma: IsCancellationRequested

Nem sempre você quer uma exceção. Às vezes o certo é parar o laço e devolver o que já foi feito. Para isso, em vez de ThrowIfCancellationRequested(), confira a propriedade IsCancellationRequested ("o cancelamento foi pedido?"), que é um bool:

using var cts = new CancellationTokenSource(TimeSpan.FromMilliseconds(250));
int somadas = await Somar(cts.Token);
Console.WriteLine($"Parei. Somei {somadas} notas antes do tempo acabar.");

static async Task<int> Somar(CancellationToken token)
{
    int quantas = 0;
    while (!token.IsCancellationRequested)
    {
        quantas++;
        await Task.Delay(100);
    }
    return quantas;
}

$ dotnet run educado.cs
Parei. Somei 3 notas antes do tempo acabar.

new CancellationTokenSource(TimeSpan.FromMilliseconds(250))

Um juiz com cronômetro: ele mesmo apita depois de 250 milissegundos, sem ninguém chamar Cancel(). É o jeito de dar um tempo limite (em inglês, timeout) a um trabalho.

while (!token.IsCancellationRequested)

"Enquanto não pediram para parar." O ! é o "não" (veja Operadores Lógicos).

return quantas;

Sem exceção: o método termina normalmente e devolve o resultado parcial.

4. Tempo limite e Ctrl+C

Tempo limite: CancelAfter

Além do cronômetro no construtor, existe cts.CancelAfter(250) ("cancele depois de 250 milissegundos"), que você pode chamar a qualquer momento. Se ninguém tratar a exceção, o programa termina com erro:

using var cts = new CancellationTokenSource();
cts.CancelAfter(250);
await Task.Delay(1000, cts.Token);
Console.WriteLine("Fim");

$ dotnet run semtratar.cs; echo "código de saída: $?"
Unhandled exception. System.Threading.Tasks.TaskCanceledException: A task was canceled.
   at Program.<Main>$(String[] args) in /home/ana/cs/cancelar/semtratar.cs:line 3
   at Program.<Main>(String[] args)
código de saída: 134

O Fim nunca apareceu: a espera de 1 segundo foi cortada aos 250 milissegundos, e a TaskCanceledException ("uma tarefa foi cancelada") subiu até o topo sem catch. O código de saída 134 é o de toda exceção não tratada no Linux (veja Exceções).

O Ctrl+C: Console.CancelKeyPress

Quando a Ana aperta Ctrl+C, o programa normalmente morre na hora. Com o evento Console.CancelKeyPress ("tecla de cancelar apertada"), ele pode transformar esse aperto num cancelamento educado (veja Eventos):

using var cts = new CancellationTokenSource();

Console.CancelKeyPress += (sender, e) =>
{
    e.Cancel = true; // não feche o programa na hora
    Console.WriteLine();
    Console.WriteLine("Ctrl+C recebido, terminando com calma...");
    cts.Cancel();
};

Console.WriteLine("Contando. Aperte Ctrl+C para parar.");
int segundos = 0;
try
{
    while (true)
    {
        await Task.Delay(1000, cts.Token);
        segundos++;
        Console.WriteLine($"{segundos} s");
    }
}
catch (OperationCanceledException)
{
    Console.WriteLine($"Parei depois de {segundos} s. Arquivo salvo.");
}

Para a saída ser reprodutível, em vez de apertar as teclas a Ana usou o timeout -s INT 3.5, que manda ao programa, depois de 3,5 segundos, o mesmo sinal (SIGINT) que o Ctrl+C manda:

$ timeout -s INT 3.5 dotnet run ctrlc.cs
Contando. Aperte Ctrl+C para parar.
1 s
2 s
3 s

Ctrl+C recebido, terminando com calma...
Parei depois de 3 s. Arquivo salvo.

Console.CancelKeyPress += (sender, e) => { … };

Registra uma lambda que roda quando o Ctrl+C chega.

e.Cancel = true;

"Cancele o fechamento": sem esta linha, o programa fecharia logo depois da lambda, sem passar pelo catch. Cuidado com a confusão de nomes: aqui, Cancel = true quer dizer "não feche".

cts.Cancel();

Transforma o aperto da tecla num pedido de cancelamento, que chega ao Task.Delay.

5. Register, CancellationToken.None e tokens ligados

Ser avisado: Register

using var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;

token.Register(() => Console.WriteLine("Aviso: alguém cancelou!"));

Console.WriteLine($"Pode cancelar? {token.CanBeCanceled}");
Console.WriteLine($"Cancelado? {token.IsCancellationRequested}");
cts.Cancel();
Console.WriteLine($"Cancelado? {token.IsCancellationRequested}");

CancellationToken nenhum = CancellationToken.None;
Console.WriteLine($"None pode cancelar? {nenhum.CanBeCanceled}");

$ dotnet run registrar.cs
Pode cancelar? True
Cancelado? False
Aviso: alguém cancelou!
Cancelado? True
None pode cancelar? False

token.Register(() => …)

"Registre": guarda uma lambda que roda no momento do Cancel(). Repare que o aviso saiu antes do segundo Cancelado?.

token.CanBeCanceled

"Pode ser cancelado?": true quando o token veio de um CancellationTokenSource.

CancellationToken.None

Um token que nunca apita. Serve para chamar um método que exige um token quando você não quer cancelar nada.

O token opcional: = default

Nos seus métodos, deixe o token opcional, como o .NET faz. Quem não se importa com cancelamento chama sem ele:

await Baixar();
Console.WriteLine("Baixou sem token");

using var cts = new CancellationTokenSource();
await Baixar(cts.Token);
Console.WriteLine("Baixou com token");

static async Task Baixar(CancellationToken token = default)
{
    await Task.Delay(100, token);
}

$ dotnet run padrao.cs
Baixou sem token
Baixou com token

O default de um CancellationToken é o mesmo que CancellationToken.None (veja Parâmetros Opcionais e Nomeados).

Dois motivos para parar: CreateLinkedTokenSource

Um download deve parar se a Ana clicar em Cancelar ou se passar do tempo limite. Um token "ligado" apita quando qualquer um dos outros apitar:

using var usuario = new CancellationTokenSource();
using var tempo = new CancellationTokenSource();
using var qualquerUm = CancellationTokenSource.CreateLinkedTokenSource(usuario.Token, tempo.Token);

tempo.Cancel(); // o tempo acabou

Console.WriteLine($"Usuário cancelou? {usuario.IsCancellationRequested}");
Console.WriteLine($"Tempo acabou?     {tempo.IsCancellationRequested}");
Console.WriteLine($"Ligado cancelou?  {qualquerUm.IsCancellationRequested}");

$ dotnet run ligados.cs
Usuário cancelou? False
Tempo acabou?     True
Ligado cancelou?  True

O trabalho recebe qualquerUm.Token. No catch, a propriedade e.CancellationToken e o IsCancellationRequested de cada fonte dizem qual foi o motivo.

using var usuario = new CancellationTokenSource();
using var tempo = new CancellationTokenSource();
using var qualquerUm = CancellationTokenSource.CreateLinkedTokenSource(usuario.Token, tempo.Token);

qualquerUm.Token.Register(() => Console.WriteLine("O token ligado apitou!"));

tempo.Cancel(); // o tempo acabou

Console.WriteLine($"Usuário cancelou? {usuario.IsCancellationRequested}");
Console.WriteLine($"Tempo acabou?     {tempo.IsCancellationRequested}");
Console.WriteLine($"Ligado cancelou?  {qualquerUm.IsCancellationRequested}");

Quando dá errado

«… o começo, igual ao download.cs …»
static async Task Baixar(CancellationToken token)
{
    for (int parte = 1; parte <= 5; parte++)
    {
        Console.WriteLine($"Baixando parte {parte} de 5...");
        await Task.Delay(100);
    }
    Console.WriteLine("Download completo!");
}

$ dotnet run ignora.cs
Baixando parte 1 de 5...
Baixando parte 2 de 5...
Baixando parte 3 de 5...
Baixando parte 4 de 5...
Ana clicou em Cancelar
Baixando parte 5 de 5...
Download completo!

await Baixar();

static async Task Baixar(CancellationToken token)
{
    await Task.Delay(100, token);
}

$ dotnet run falta.cs
/home/ana/cs/cancelar/falta.cs(1,7): error CS7036: Não há nenhum argumento fornecido que corresponda ao parâmetro necessário 'token' de 'Baixar(CancellationToken)'

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

var cts = new CancellationTokenSource();
cts.Dispose();
cts.Cancel();

$ dotnet run descartado.cs; echo "código de saída: $?"
Unhandled exception. System.ObjectDisposedException: The CancellationTokenSource has been disposed.
   at System.Threading.CancellationTokenSource.Cancel()
   at Program.<Main>$(String[] args) in /home/ana/cs/cancelar/descartado.cs:line 3
código de saída: 134

Referência rápida

Exercícios

Missão final: processar os pedidos da lojinha

using var cts = new CancellationTokenSource();
string[] pedidos = ["Caderno", "Lápis", "Borracha", "Régua", "Estojo"];

int feitos = Processar(pedidos, cts, cts.Token);
Console.WriteLine($"Parei: processados {feitos} de {pedidos.Length}.");

static int Processar(string[] pedidos, CancellationTokenSource loja, CancellationToken token)
{
    int feitos = 0;
    foreach (string pedido in pedidos)
    {
        feitos++;
        Console.WriteLine($"Pedido {feitos} pronto");

        if (feitos == 2)
        {
            loja.Cancel(); // a loja fechou
        }
    }
    return feitos;
}

using var cts = new CancellationTokenSource();
string[] pedidos = ["Caderno", "Lápis", "Borracha", "Régua", "Estojo"];

int feitos = Processar(pedidos, cts, cts.Token);
Console.WriteLine($"Parei: processados {feitos} de {pedidos.Length}.");

static int Processar(string[] pedidos, CancellationTokenSource loja, CancellationToken token)
{
    int feitos = 0;
    foreach (string pedido in pedidos)
    {
        if (token.IsCancellationRequested) break;

        feitos++;
        Console.WriteLine($"Pedido {feitos} pronto");

        if (feitos == 2)
        {
            loja.Cancel(); // a loja fechou
        }
    }
    return feitos;
}

Resumo

• Cancelar é um pedido combinado: o CancellationTokenSource pede (Cancel()) e a tarefa, que recebeu o CancellationToken, obedece num ponto seguro.
• Obedeça com token.ThrowIfCancellationRequested() (exceção) ou token.IsCancellationRequested (um bool, para devolver o resultado parcial).
• Passe o token adiante: Task.Delay(ms, token) e os métodos …Async do .NET param na hora.
• Trate com catch (OperationCanceledException), que pega também a TaskCanceledException.
• Tempo limite: new CancellationTokenSource(TimeSpan…) ou CancelAfter. Ctrl+C: Console.CancelKeyPress com e.Cancel = true.
• Nos seus métodos, o token vem por último e é opcional: CancellationToken token = default.