tokio-docs

tokio (1.54.1)

Visão Geral

Este skill contém o que a documentação oficial do Tokio diz que é fácil de errar: segurança de cancelamento, bloqueio do runtime, padrões surpreendentes, panics e as APIs que substituem as antigas. Os fundamentos que todo desenvolvedor Rust assíncrono conhece foram omitidos. Cada afirmação em references/ termina com a URL da documentação de onde veio, para que você possa reabrir a página. https://docs.rs/tokio/latest/tokio/index.html

Versão Coberta

tokio 1.54.1, conforme servido por docs.rs/tokio/latest, além do tutorial e páginas de tópicos do tokio.rs. APIs instáveis precisam de --cfg tokio_unstable e podem quebrar na versão 1.x, portanto, não as sugira a menos que o projeto já as habilite. https://docs.rs/tokio/latest/tokio/index.html#unstable-features

Como Navegar

1. Encontre o domínio do código que você está escrevendo ou revisando na tabela abaixo.
2. Abra apenas o arquivo de referência correspondente. Cada um é independente, com uma tabela de conteúdos no topo.
3. Aplique suas regras padrão. Use a saída de escape somente quando a condição declarada for verdadeira.
4. Em uma revisão, verifique também a tabela "Padrões antigos" no final do arquivo, quando houver, e sugira a substituição.
5. Na sua resposta, forneça a URL da documentação que segue cada regra que você aplicar, para que o leitor possa verificá-la.

Regras de Maior Valor

• Um runtime construído com Builder não possui drivers de E/S ou temporizador. Chame enable_all(), ou os tipos de rede e tempo falharão. https://docs.rs/tokio/latest/tokio/runtime/index.html#resource-drivers
• #[tokio::test] executa em um runtime de thread única, #[tokio::main] em um multi-thread. #[tokio::main] em uma função chamada com frequência constrói um novo runtime por chamada. https://docs.rs/tokio/latest/tokio/attr.test.html e https://docs.rs/tokio/latest/tokio/attr.main.html
• rt.block_on(sleep(d)) causa pânico: o future é criado fora do runtime. Encapsule-o: rt.block_on(async { sleep(d).await }). https://docs.rs/tokio/latest/tokio/time/fn.sleep.html
• Em um runtime de thread única, as tarefas spawnadas são executadas apenas enquanto Runtime::block_on estiver em execução. Handle::block_on não as impulsiona. https://docs.rs/tokio/latest/tokio/runtime/index.html#driving-the-runtime
• Por padrão, use std::sync::Mutex em código assíncrono, nunca mantido através de um .await. Encerre o guard em um escopo de bloco, já que drop(guard) não satisfaz a verificação de Send. Use tokio::sync::Mutex apenas quando o guard precisar cruzar um .await. https://tokio.rs/tokio/tutorial/shared-state
• Execute código bloqueante ou pesado em CPU com spawn_blocking, e loops infinitos em uma std::thread. abort não para uma tarefa bloqueante em execução. https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
• Em select!, as branches perdedoras são descartadas. read_exact, read_to_end, write_all e mpsc::Sender::send perdem dados ali. Use reserve() para envios, e fixe futures de longa duração fora do loop e selecione em &mut fut. https://docs.rs/tokio/latest/tokio/macro.select.html e https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Sender.html#method.send
• select! causa pânico quando todas as branches estão desabilitadas e não há else. https://docs.rs/tokio/latest/tokio/macro.select.html
• Prefira um mpsc::channel(n) limitado para contrapressão. recv retorna None apenas quando todos os Sender forem descartados. https://tokio.rs/tokio/tutorial/channels e https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html
• Um receptor broadcast lento obtém RecvError::Lagged(n) e permanece aberto. Trate isso em vez de tratar todo erro como fechamento. https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.recv
• Em um loop changed() de watch, use borrow_and_update(), e nunca mantenha um borrow() através de .await. https://docs.rs/tokio/latest/tokio/sync/watch/index.html
• Descartar um JoinHandle desanexa a tarefa. Descartar um JoinSet aborta todas as suas tarefas. https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html
• interval dispara imediatamente na primeira vez e, por padrão, acumula ticks perdidos. Defina MissedTickBehavior::Delay ou Skip quando rajadas de recuperação forem inadequadas. https://docs.rs/tokio/latest/tokio/time/enum.MissedTickBehavior.html
• timeout avalia o future antes de verificar o prazo, portanto, um future que nunca cede pode terminar após o prazo com Ok. https://docs.rs/tokio/latest/tokio/time/fn.timeout.html
• Teste temporizadores com #[tokio::test(start_paused = true)] (feature test-util) e sleep com avanço automático em vez de advance. https://docs.rs/tokio/latest/tokio/time/fn.advance.html
• Descarregue um BufWriter e um tokio::fs::File antes do drop, ou os dados serão perdidos ou escritos tardiamente. https://docs.rs/tokio/latest/tokio/io/index.html e https://docs.rs/tokio/latest/tokio/fs/struct.File.html
• Um read() retornando Ok(0) significa fechado. Um loop que o ignora gira a 100% de CPU. https://tokio.rs/tokio/tutorial/io
• Cada chamada tokio::fs é um spawn_blocking. Agrupe com fs::read / fs::write ou BufWriter. https://docs.rs/tokio/latest/tokio/fs/index.html
• Um Child descartado continua em execução a menos que kill_on_drop(true). output() força stdout e stderr canalizados. https://docs.rs/tokio/latest/tokio/process/index.html e https://docs.rs/tokio/latest/tokio/process/struct.Command.html#method.output
• No Unix, o primeiro listener ctrl_c() substitui o manipulador padrão de SIGINT permanentemente. https://docs.rs/tokio/latest/tokio/signal/fn.ctrl_c.html
• Um servidor de pipe nomeado deve criar a próxima instância antes de entregar a instância conectada, ou os clientes recebem NotFound. Um cliente tenta novamente apenas em ERROR_PIPE_BUSY. NotFound significa que não há servidor, portanto, retorne o erro em vez de tentar novamente. https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeServer.html e https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeClient.html

Referências

Arquivo	Cobre
references/runtime.md	Feature flags, Builder e drivers, LocalRuntime, shutdown, #[tokio::main] e #[tokio::test]
references/block-on-bridging.md	Impulsionando um runtime, block_on e Handle::block_on, EnterGuard e Handle::current, chamando código assíncrono de código síncrono, fork Unix
references/tasks.md	spawn e seus limites, JoinHandle, abort, JoinSet, spawn_blocking, block_in_place, orçamento cooperativo, LocalSet, spawn_local, task_local
references/sync-locks.md	Mutex std vs tokio, guards através de .await, RwLock, Semaphore, Notify, OnceCell, SetOnce, Barrier
references/channels.md	Contrapressão mpsc, permits e fechamento, oneshot, lag broadcast, regras de borrow em watch
references/select-cancellation.md	Regras de select!, listas de segurança de cancelamento, fixação através de loops, biased, join!, try_join!, encerramento gracioso
references/time-testing.md	sleep, interval e MissedTickBehavior, timeout, Instant, tempo pausado, simulação de E/S em testes
references/io-net.md	Traits ext AsyncRead/AsyncWrite, BufWriter, split, io::copy, framing, TcpListener, TcpStream, TcpSocket, UdpSocket
references/fs-process.md	tokio::fs e seu pool bloqueante, File flush e drop, Command, Child, kill_on_drop, pipes stdio
references/signals-named-pipes.md	ctrl_c, sinais Unix, eventos de console Windows, servidor e cliente de pipe nomeado Windows

Todas as páginas lidas estão listadas em SOURCES.md.