Introdução

System.Threading.Channels é a biblioteca do .NET que oferece canais para transportar dados entre produtores e consumidores de forma concorrente, com APIs de leitura e escrita compatíveis com async e await. Eu a usaria quando uma etapa gera trabalho e outra precisa consumi-lo em um ritmo diferente, sem obrigar o produtor a executar toda a etapa seguinte nem criar uma tarefa independente para cada item.

O canal é uma fila em memória dentro do processo, não um broker de mensagens. Um canal limitado pode conter o crescimento do buffer e aplicar backpressure: quando a fila fica cheia, o produtor espera por espaço ou a política escolhida descarta itens. Isso organiza a pressão entre etapas, mas não fornece persistência, confirmação de processamento nem recuperação após queda da aplicação. Se um pedido precisa sobreviver a um reinício, Channels sozinho não resolve o problema.

Imagine uma importação que lê registros mais rápido do que consegue validá-los. Acumular tudo em uma lista aumenta o uso de memória; criar milhares de tasks transfere a fila para o agendador e dificulta controlar a concorrência. Um canal coloca uma fronteira explícita entre leitura e processamento. A partir dela, eu consigo discutir capacidade, quantidade de consumidores, comportamento de saturação e encerramento com decisões verificáveis.

Neste artigo, vou explicar Channel<T>, ChannelWriter<T> e ChannelReader<T>, comparar canais limitados e ilimitados e mostrar por que aceitar uma escrita não é o mesmo que concluir o trabalho. Também vou tratar cancelamento, conclusão e falhas que podem deixar um produtor bloqueado. O exemplo será pequeno, com .NET 10 e testes determinísticos, sem banco ou mensageria externa.

O analisador de histórico Git já aplica Channels em um problema específico. Aqui, o objetivo é entender a biblioteca e seu ciclo de vida sem repetir aquele analisador. Depois, o mesmo raciocínio pode ajudar na implementação de Workers, importações e pipelines de processamento locais.

Pré-requisitos

  • .NET SDK 10.0.400 ou patch compatível, conforme o global.json do repositório de exemplos.
  • Conhecimento de Task, CancellationToken e async/await. Não é necessário conhecer um broker de mensagens.
  • Entendimento básico de injeção de dependência se o exemplo for adaptado a um Worker ou API.
  • O clone de blog-zocateli-sample, para executar o demo e consultar os testes completos.

Em um projeto que usa o framework .NET 10, os tipos de System.Threading.Channels já estão disponíveis pelas referências do framework. O demo deste artigo não precisa adicionar um pacote NuGet de Channels. Se você estiver mantendo uma biblioteca para outros frameworks, confira os frameworks de destino e a necessidade de referenciar o pacote correspondente.

Os dados do exemplo são inteiros gerados em memória. Isso evita confundir o comportamento do canal com latência de banco, indisponibilidade de rede ou garantias de entrega de um sistema externo.

Channel, Writer e Reader separam as responsabilidades

Um Channel<T> representa a estrutura que conecta escrita e leitura. Sua propriedade Writer fornece um ChannelWriter<T>, usado pelo produtor para adicionar itens e sinalizar que não haverá novas escritas. A propriedade Reader fornece um ChannelReader<T>, usado pelo consumidor para retirar itens ou aguardar sua chegada. Essa separação permite entregar apenas a capacidade necessária a cada componente.

O produtor não precisa saber qual consumidor receberá o item. O consumidor não precisa acessar a fonte original dos dados. Isso é útil quando a etapa de leitura tem uma natureza diferente da etapa de processamento: um parser pode produzir registros incrementalmente, enquanto um grupo pequeno de consumidores aplica validações. O contrato comum é o tipo transportado pelo canal.

Essa estrutura já oferece sincronização para suas operações. Eu não colocaria um lock externo ao redor de cada escrita e leitura por reflexo. Entretanto, essa proteção não se estende ao conteúdo do item: se o produtor e o consumidor continuam alterando o mesmo objeto mutável depois da escrita, ainda existe compartilhamento de estado. Prefira dados imutáveis ou uma transferência de responsabilidade bem definida.

Também não surge uma thread dedicada apenas porque um canal foi criado. As operações assíncronas aguardam disponibilidade; o trabalho real continua sendo executado pelas tarefas que você inicia. Channels coordena a passagem de dados, não decide sozinho quantos consumidores existirão nem qual será o paralelismo adequado.

No código, essa divisão aparece diretamente: Writer.WriteAsync admite trabalho; Reader.ReadAllAsync fornece itens para processamento. O serviço que consome continua responsável por validar o dado, executar a operação e tratar seus efeitos. Uma leitura bem-sucedida não é uma confirmação de conclusão do negócio.

Canal limitado aplica backpressure; ilimitado não limita memória

Um canal ilimitado não possui uma capacidade máxima configurada para o buffer. Se o produtor avança continuamente e os consumidores não acompanham, os itens pendentes podem se acumular. “Ilimitado” descreve a política da estrutura, não a quantidade de memória disponível no processo. O limite real continuará sendo imposto pelos recursos do ambiente.

Um canal limitado torna explícita a quantidade de itens que pode permanecer no buffer. No modo Wait, uma escrita assíncrona aguarda espaço quando essa capacidade é atingida. Em vez de continuar lendo uma fonte e empilhando objetos, o produtor recebe pressão da etapa mais lenta. Isso é backpressure: a velocidade de uma parte do pipeline influencia a etapa que a alimenta.

1
2
3
4
5
6
7
8
// Quatro itens podem permanecer no buffer; itens em processamento são adicionais.
var canal = Channel.CreateBounded<int>(new BoundedChannelOptions(4)
{
    FullMode = BoundedChannelFullMode.Wait,
    SingleWriter = true,
    SingleReader = false,
    AllowSynchronousContinuations = false
});

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog: BlogSamples/AsyncParallel/Channels/

A capacidade limita itens aguardando dentro do canal, não todo o trabalho em trânsito. Com quatro posições e dois consumidores, ainda posso ter quatro itens no buffer e dois sendo processados. Objetos já criados pela fonte, buffers de rede e tasks iniciadas fora dessa fronteira também ocupam memória. O canal não impõe um teto global ao processo.

Por isso, eu dimensionaria capacidade e concorrência juntas. Uma fila muito grande pode aumentar espera e memória sem melhorar throughput; uma fila pequena pode ser suficiente para suavizar pequenas diferenças de ritmo. Antes de escolher centenas de posições, meça o tamanho dos itens, a latência do consumidor e os limites do recurso acessado. O maior número nem sempre produz o melhor fluxo.

Canal limitado conecta produtor e consumidores; saturação aplica espera e conclusão permite drenar o buffer

Os modos de descarte mudam o significado da escrita

BoundedChannelFullMode define o que acontece quando uma escrita encontra o buffer cheio. O padrão Wait preserva a intenção de admitir todos os itens, esperando por espaço nas escritas assíncronas. Os outros modos aceitam perder dados em pontos específicos. Escolher um deles é uma decisão funcional: qual informação o sistema está autorizado a abandonar?

Considere um canal com capacidade dois, contendo [10, 20], e uma tentativa de escrever 30, sem leituras concorrentes:

ModoResultado no bufferItem descartado
Wait[10, 20] até existir espaçoNenhum pela política; TryWrite(30) retorna false
DropWrite[10, 20]O novo item 30
DropNewest[10, 30]O mais novo que já estava no buffer: 20
DropOldest[20, 30]O mais antigo que estava no buffer: 10

O nome DropNewest merece atenção: ele não significa descartar automaticamente a nova escrita. O canal remove o item mais recente já armazenado, abrindo espaço para o que chega. Confundir isso com DropWrite pode inverter a política pretendida.

Nos modos de descarte, TryWrite pode retornar true mesmo quando um item foi descartado pela política. Esse retorno não comprova que todos os dados permaneceram na fila, muito menos que foram processados. O teste do exemplo verifica explicitamente esse comportamento. Para observar os descartes, a criação do canal pode receber um callback itemDropped; mantenha essa função pequena, segura e adequada à concorrência dos escritores.

Eu consideraria DropOldest para estados substituíveis de uma visualização, se preservar todos os estados intermediários não for requisito. Não usaria essa política para pedidos ou auditoria que exigem registro completo. Também não presumiria que descartar o mais antigo cria uma regra de “último valor por entidade”: a política atua na fila, não entende chaves de negócio.

⚠️ Atenção: Descarte é perda deliberada de informação. Documente a política, conte os itens descartados e verifique se o domínio admite essa perda antes de usar DropWrite, DropNewest ou DropOldest.

Escrita e leitura assíncronas exigem um ciclo de vida explícito

WriteAsync é uma boa escolha quando o produtor deve aguardar espaço em um canal limitado. TryWrite permite uma tentativa imediata; no modo Wait, uma fila cheia faz essa tentativa retornar false. Nenhuma dessas APIs deve ser interpretada como confirmação de que o consumidor terminou sua operação.

Existem APIs de espera separadas, como WaitToWriteAsync e WaitToReadAsync, mas uma indicação de disponibilidade não reserva permanentemente uma posição ou um item. Com concorrência, outra tarefa pode ocupar o espaço ou retirar o dado antes da operação seguinte. Use os padrões documentados e evite construir um protocolo próprio de reserva em cima de uma checagem isolada.

Para uma fonte finita, o produtor deve sinalizar conclusão depois da última escrita. TryComplete tenta encerrar o writer sem lançar a exceção que uma segunda chamada a Complete poderia provocar. Nenhuma nova escrita será aceita após o encerramento, mas os itens que já estão no buffer podem continuar sendo lidos.

No caminho normal, ReadAllAsync torna esse consumo direto:

1
2
3
4
5
6
// O fim da enumeracao ocorre depois que o writer conclui e o buffer esvazia.
await foreach (var item in canal.Reader.ReadAllAsync(cancellationToken))
{
    cancellationToken.ThrowIfCancellationRequested();
    await processar(item, cancellationToken);
}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog: BlogSamples/AsyncParallel/Channels/

Eu aguardaria também as tarefas consumidoras. Reader.Completion representa o estado de conclusão da leitura do canal; não garante que uma operação de negócio já iniciada com o último item terminou. Quando o consumidor retira o item, ele passa a estar fora do buffer. Só aguardar os consumidores fornece a confirmação de que seus delegates concluíram, e isso ainda depende da semântica desses delegates.

Vários consumidores distribuem trabalho, mas não fazem broadcast

Um canal pode aceitar vários produtores e vários consumidores. Cada leitura bem-sucedida remove um item da fila para aquele leitor; não entrega uma cópia a todos os consumidores. Se três consumidores leem o mesmo canal, eles compartilham o trabalho. Se todos precisam receber cada evento, você precisa de uma estratégia de distribuição diferente ou de canais próprios para as assinaturas.

Também existe uma diferença entre ordem de retirada e ordem de conclusão. Itens disponibilizados na fila são retirados conforme a estrutura de leitura, mas consumidores paralelos podem levar tempos diferentes para processá-los. Um item posterior pode terminar antes do anterior. Isso apareceu no demo: todos os inteiros foram processados, mas algumas linhas do console saíram fora da sequência numérica.

Se a ordem final importa, não prometa preservá-la apenas porque os dados entraram em uma fila. Você pode optar por um consumidor, ordenar resultados por uma sequência explícita ou particionar por uma chave que defina a unidade de ordenação. Cada alternativa possui custos e limites; Channels não escolhe essa política por você.

SingleWriter e SingleReader são declarações sobre o uso real do canal, permitindo otimizações. Eles não são um mecanismo de autorização nem uma forma de obrigar o resto do programa a usar somente uma tarefa. Configure SingleReader = true apenas se não houver leituras concorrentes. No exemplo, esse valor depende da quantidade de consumidores configurada.

Por fim, limite o paralelismo antes de iniciar operações caras. Ler da fila e criar uma task desacoplada para cada item pode esvaziar o buffer rapidamente, mas colocar milhares de operações em andamento. Nesse desenho, o backpressure fica enfraquecido: o gargalo foi transferido para uma lista de tarefas que o canal não controla.

Conclusão, cancelamento e falha não são o mesmo encerramento

Na conclusão normal, o produtor termina suas escritas, encerra o writer e os consumidores drenam os itens restantes. Se a intenção é processar tudo o que foi admitido, esse é um caminho distinto de cancelar imediatamente cada leitura e operação. Em um Worker, o tempo disponível para esse escoamento também depende do limite de encerramento configurado pelo host.

No cancelamento, a intenção é interromper o trabalho cooperativamente. Propague o token à escrita, à leitura, à fonte e à operação consumidora. ReadAllAsync pode ainda disponibilizar dados prontos mesmo quando o cancelamento é solicitado; o exemplo faz uma checagem explícita antes de iniciar o processamento do item. Isso não recupera automaticamente um item já retirado da fila.

Na falha, é necessário impedir que as tarefas sobreviventes fiquem aguardando indefinidamente. Imagine que o único consumidor lança uma exceção enquanto o produtor está bloqueado em WriteAsync por falta de espaço. Apenas aguardar Task.WhenAll não cancela esse produtor. Se ninguém mais retira itens, ele pode permanecer esperando e impedir que o conjunto termine.

O exemplo usa uma fonte de cancelamento vinculada. A primeira falha registrada é preservada; o writer é concluído com erro, o token compartilhado é cancelado e o código aguarda todas as tarefas antes de propagar a falha. A política é fail-fast: não promete drenar o buffer depois do erro. Na conclusão normal, entretanto, o buffer é drenado.

Não existe interrupção forçada segura de um delegate arbitrário que ignora cancelamento. Se a fonte ou o processamento fica preso em uma operação que não respeita o token, o encerramento pode continuar demorando. Defina timeouts nas dependências e verifique cooperação. O canal administra sua fila; não controla o comportamento de todo código externo chamado pelo pipeline.

Quando escolher Channels, Parallel.ForEachAsync ou mensageria

Eu escolheria Channels quando preciso separar etapas, controlar um buffer e explicitar a pressão entre produção e consumo no mesmo processo. Se o problema é apenas percorrer uma coleção com um grau de paralelismo limitado, Parallel.ForEachAsync pode resultar em menos código de coordenação. Não adicionaria um canal somente para tornar um loop aparentemente mais sofisticado.

O artigo de paralelismo em C# discute ferramentas para distribuir trabalho. Já Worker e Background Service aborda execução fora do ciclo HTTP. Channels pode ser usado dentro desses cenários, mas não substitui o host do Worker nem determina a política de concorrência das dependências.

Uma operação admitida em um canal local pode ser perdida se o processo cair antes de consumi-la. O canal não mantém um log persistente, não oferece acknowledgement de negócio e não reenvia automaticamente trabalho cujo consumidor falhou. Portanto, responder a uma requisição dizendo “aceito” depois de enfileirar em memória não equivale a garantir que o trabalho sobreviverá a um reinício.

Para entrega entre processos, retomada e persistência, avalie um broker ou outra estrutura durável, com garantias adequadas ao domínio. Mesmo nesses casos, duplicidade e consistência continuam exigindo idempotência e desenho de armazenamento. O Transactional Outbox Pattern trata uma dessas fronteiras.

Channels pode servir como estágio interno de um consumidor de mensageria, mas a confirmação externa deve acompanhar a política correta de processamento. Retirar uma mensagem do canal não é motivo suficiente para confirmar sua entrega no broker. O ponto de confirmação precisa refletir os efeitos duráveis que a aplicação realmente concluiu.

Exemplo Prático

O exemplo completo possui um pipeline reutilizável e um console independente em AsyncParallel/Channels/Demo. A API agregadora não precisa ser iniciada. O produtor gera vinte inteiros, dois consumidores executam uma operação assíncrona curta e a fila admite quatro itens no buffer. No encerramento normal, o total deve ser vinte.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// O demo gera 20 itens; a operacao simulada respeita cancelamento.
var processados = 0;
await PipelineChannels.ExecutarAsync(
    ProduzirAsync(),
    async (item, cancellationToken) =>
    {
        await Task.Delay(5, cancellationToken);
        Interlocked.Increment(ref processados);
        Console.WriteLine($"Processado: {item}");
    },
    capacidade: 4,
    consumidores: 2);

Console.WriteLine($"Total processado: {processados}");

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog: BlogSamples/AsyncParallel/Channels/

Execute a partir da raiz do repositório de exemplos:

1
2
3
4
5
# O console usa somente o framework .NET 10 e o fonte do pipeline.
dotnet run --project src/BlogSamples/AsyncParallel/Channels/Demo/ChannelsDemo.csproj

# Execute a classe de testes quando as dependencias do projeto agregador estiverem validas.
dotnet test tests/BlogSamples.Tests/BlogSamples.Tests.csproj --filter FullyQualifiedName~ChannelPipelineTests

A ordem das linhas individuais pode mudar entre execuções. O resultado relevante do caminho normal é a linha final:

1
Total processado: 20

Os testes verificam conclusão normal com um e quatro consumidores, falha do produtor, falha do consumidor, cancelamento e os quatro modos de buffer cheio. O caso de DropNewest confirma que o item removido é o mais recente já armazenado. Outro caso verifica que um item que estava no buffer pode ser lido mesmo depois de TryComplete receber uma exceção, antes de observar a conclusão com erro.

Na preparação deste artigo, os dez casos passaram executando os mesmos arquivos de fonte e teste em um projeto xUnit temporário isolado. A suíte agregadora estava bloqueada na restauração por alertas de segurança de dependências criptográficas preexistentes; não desabilitei a auditoria nem tratei essa suíte como aprovada. O console independente compilou e executou o total esperado.

Não apresento esse demo como benchmark. A espera de cinco milissegundos representa uma operação assíncrona simulada e ajuda a visualizar concorrência; não demonstra vantagem de performance de Channels. Para medir um produto, use sua carga, seu tamanho de item e suas dependências reais, comparando throughput, latência, memória e perdas.

Dicas e Boas Práticas

  • Comece com capacidade e concorrência pequenas. Meça a espera na escrita e o tempo de processamento antes de aumentar o buffer. Mais posições podem aumentar a latência do trabalho pendente sem acelerar o consumidor.
  • Registre a política de saturação como regra funcional. Explique se o sistema espera, rejeita ou descarta, e qual item pode ser perdido. Nos modos de descarte, acompanhe o callback e não use somente o retorno de escrita como contador de processamento.
  • Espere as tarefas, não apenas o canal. Encerrar o writer impede novas escritas e permite drenar o buffer. A conclusão das operações já iniciadas pertence aos consumidores e precisa ser aguardada explicitamente.
  • Propague cancelamento e preserve a falha original. Um consumidor que falha deve liberar o produtor que aguarda espaço. Mantenha a coordenação centralizada e verifique que fonte e operações externas respeitam os tokens recebidos.
  • Não desacople uma task por item sem limite. A retirada rápida da fila pode esconder o acúmulo de operações em andamento. O limite precisa alcançar o recurso que realmente processa o trabalho.
  • Não confunda concorrência com broadcast ou ordenação final. Vários leitores repartem itens e podem terminar fora de ordem. Se o domínio precisa de cópias para todos ou sequência por entidade, desenhe isso separadamente.
  • Use persistência quando o requisito exigir. Um canal em memória não sobrevive ao processo. Para comandos de negócio, defina entrega durável e idempotência em vez de prometer recuperação que a estrutura não fornece.

Resumo Objetivo

  • System.Threading.Channels transporta dados entre produtores e consumidores no mesmo processo, com APIs concorrentes de leitura e escrita compatíveis com operações assíncronas.
  • Canal limitado com Wait faz WriteAsync aguardar espaço quando o buffer enche; a capacidade não inclui itens já retirados e em processamento.
  • Modos de descarte têm políticas distintas: DropWrite perde a nova escrita, DropNewest remove o mais recente já armazenado e DropOldest remove o mais antigo do buffer.
  • Escrita aceita não confirma processamento. Nos modos de descarte, TryWrite pode retornar true apesar da perda de um item pela política.
  • Conclusão normal encerra as escritas e permite drenar o buffer; esperar as tarefas consumidoras continua necessário para acompanhar suas operações.
  • Falha e cancelamento precisam ser coordenados para não deixar produtor ou consumidores aguardando indefinidamente. O exemplo adota fail-fast nas falhas e cancelamento cooperativo.
  • Vários consumidores repartem o trabalho, não recebem cópias de todos os itens, e podem concluir operações fora da ordem de entrada.
  • Persistência e entrega entre processos não são garantias de Channels; comandos que precisam sobreviver a reinícios exigem uma estratégia durável.

Leia Também

Referências