Cancelamento e Timeouts

Em Rust async, o cancelamento é cooperativo: descartar um future ou chamar JoinHandle::abort para o trabalho no próximo ponto de await. Combine timeouts e sinais de desligamento para que os serviços falhem rapidamente e sejam desligados de forma limpa.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

use tokio::time::{timeout, Duration};
 
async fn work() -> &'static str {
    "done"
}
 
#[tokio::main]
async fn main() {
    match timeout(Duration::from_secs(1), work()).await {
        Ok(v) => println!("{v}"),
        Err(_) => println!("timed out"),
    }
}

Quando usar isso: Prazos de cliente HTTP, desligamento gracioso, limites de trabalho por escopo de solicitação e prevenção de tarefas travadas.

Exemplo de Trabalho

use tokio::sync::watch;
use tokio::time::{sleep, Duration};
 
async fn worker(mut shutdown: watch::Receiver<bool>) {
    loop {
        tokio::select! {
            _ = shutdown.changed() => {
                if *shutdown.borrow() {
                    println!("shutting down");
                    break;
                }
            }
            _ = sleep(Duration::from_millis(100)) => {
                println!("tick");
            }
        }
    }
}
 
#[tokio::main]
async fn main() {
    let (tx, rx) = watch::channel(false);
    let handle = tokio::spawn(worker(rx));
 
    sleep(Duration::from_millis(250)).await;
    tx.send(true).unwrap();
    handle.await.unwrap();
}

O que isso demonstra:

• Canal watch transmite o sinal de desligamento.
• select! compara ticks de trabalho com o desligamento.
• A tarefa sai do loop cooperativamente quando cancelada.

Mergulho Profundo

Como Funciona

• Drop = cancelamento: Descartar um future não aguardado cancela o trabalho em andamento nos limites de await.
• abort: JoinHandle::abort cancela tarefas geradas de forma semelhante.
• timeout: Envolve um future; ao expirar, o future interno é descartado.
• Tokens de desligamento: tokio_util::sync::CancellationToken propaga o cancelamento para tarefas filhas.

Ferramentas de Cancelamento

Notas de Rust

use tokio_util::sync::CancellationToken;
 
async fn scoped(token: CancellationToken) {
    let child = token.child_token();
    let _guard = token.drop_guard();
    tokio::select! {
        _ = token.cancelled() => {}
        _ = do_work(child) => {}
    }
}

• Execute a limpeza em implementações Drop ou padrões defer quando o cancelamento precisar liberar recursos.
• Documente quais operações são seguras para cancelamento em loops select!.
• Manipuladores de solicitação Axum cancelam quando os clientes se desconectam (future descartado).

Armadilhas

• Assumir parada imediata: Loop intensivo em CPU sem await ignora o cancelamento. Correção: Insira yield_now().await ou verifique o token de cancelamento em loops.
• Limpeza perdida no drop: Transações de banco de dados deixadas abertas. Correção: scopeguard, padrões async explícitos de finally, ou CancellationToken com branch de limpeza.
• Timeout muito agressivo: Interrompe consultas lentas, mas válidas. Correção: Divida os timeouts (conexão vs. leitura vs. total) e tente novamente operações idempotentes.
• select! recv não seguro para cancelamento: O descarte de um branch pode perder mensagens. Correção: Use biased e leia a documentação do Tokio; use buffer ou watch/broadcast apropriadamente.
• Ignorar JoinError após abort: Err esperado - não trate como falha. Correção: Use match com is_cancelled() no erro.

Alternativas

FAQs

Relacionados

• Combinando Futures - select e timeout
• Desligamento Gracioso - desligamento em produção
• Temporizadores e Intervalos - sleep e interval
• Tarefas e JoinHandles - abort
• Melhores Práticas Async - design seguro para cancelamento

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.