tokio-docs

tokio (1.54.1)

概述

此技能包含了官方 tokio 文档中容易被搞错的内容：取消安全性、阻塞运行时、令人惊讶的默认值、恐慌以及替代旧 API 的新 API。每个异步 Rust 开发者都知道的基础知识被省略了。references/ 中的每一个声明都以提供该声明的文档 URL 结尾，方便你重新打开该页面。 https://docs.rs/tokio/latest/tokio/index.html

覆盖版本

tokio 1.54.1，由 docs.rs/tokio/latest 提供，外加 tokio.rs 教程和主题页面。不稳定的 API 需要 --cfg tokio_unstable 并可能在 1.x 版本中破坏性变更，因此除非项目已启用，否则不要建议使用它们。 https://docs.rs/tokio/latest/tokio/index.html#unstable-features

导航方式

1. 在下表中找到你编写或审查代码所属的领域。
2. 只打开那个参考文件。每个文件都是独立的，顶部有目录。
3. 应用该文件的默认规则。只有在满足所述条件时才使用逃生舱。
4. 在审查时，也请检查文件末尾的“旧模式”表格（如果有的话），并建议替换方案。
5. 在你的回答中，给出你应用的每条规则所附带的文档 URL，以便读者可以核对。

最高价值规则

• 使用 Builder 构建的运行时没有 I/O 或计时器驱动。调用 enable_all()，否则网络和计时器类型会失败。 https://docs.rs/tokio/latest/tokio/runtime/index.html#resource-drivers
• #[tokio::test] 运行在单一线程运行时上，#[tokio::main] 运行在多线程运行时上。被频繁调用的函数上使用 #[tokio::main] 会导致每次调用都构建一个新的运行时。 https://docs.rs/tokio/latest/tokio/attr.test.html 和 https://docs.rs/tokio/latest/tokio/attr.main.html
• rt.block_on(sleep(d)) 会恐慌：future 是在运行时外部创建的。将其包装起来：rt.block_on(async { sleep(d).await })。 https://docs.rs/tokio/latest/tokio/time/fn.sleep.html
• 在单一线程运行时上，生成的任务仅在 Runtime::block_on 运行时才会被驱动。Handle::block_on 不会驱动它。 https://docs.rs/tokio/latest/tokio/runtime/index.html#driving-the-runtime
• 在异步代码中默认使用 std::sync::Mutex，并且在 .await 期间绝对不要持有锁。在块作用域中结束锁保护，因为 drop(guard) 不满足 Send 检查。仅当锁保护必须跨越 .await 时才使用 tokio::sync::Mutex。 https://tokio.rs/tokio/tutorial/shared-state
• 使用 spawn_blocking 运行阻塞或 CPU 密集型代码，对于无限循环则使用 std::thread。abort 无法停止正在运行的阻塞任务。 https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
• 在 select! 中，失败的分支会被丢弃。read_exact、read_to_end、write_all 和 mpsc::Sender::send 在其中会丢失数据。对于发送操作使用 reserve()，并将生命周期长的 future 钉在循环外部，然后对 &mut fut 进行 select!。 https://docs.rs/tokio/latest/tokio/macro.select.html 和 https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Sender.html#method.send
• 当每个分支都被禁用且没有 else 分支时，select! 会恐慌。 https://docs.rs/tokio/latest/tokio/macro.select.html
• 优先使用有界 mpsc::channel(n) 来实现背压。仅当所有 Sender 都被丢弃后，recv 才会返回 None。 https://tokio.rs/tokio/tutorial/channels 和 https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html
• 一个慢的广播接收器会得到 RecvError::Lagged(n) 并保持开启状态。要处理它，而不是将每个错误都视为关闭。 https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.recv
• 在 watch 的 changed() 循环中使用 borrow_and_update()，并且绝对不要在 .await 期间持有 borrow() 的结果。 https://docs.rs/tokio/latest/tokio/sync/watch/index.html
• 丢弃 JoinHandle 会分离任务。丢弃 JoinSet 会中止其所有任务。 https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html
• 默认情况下，interval 立即触发第一次，并且会爆发性地补足错过的滴答。当追赶性爆发不合适时，请设置 MissedTickBehavior::Delay 或 Skip。 https://docs.rs/tokio/latest/tokio/time/enum.MissedTickBehavior.html
• timeout 在检查截止时间之前会轮询 future，因此一个从不让步的 future 可能会在截止时间之后以 Ok 完成。 https://docs.rs/tokio/latest/tokio/time/fn.timeout.html
• 使用 #[tokio::test(start_paused = true)]（需要 test-util 特性）和带自动推进的 sleep（而非 advance）来测试计时器。 https://docs.rs/tokio/latest/tokio/time/fn.advance.html
• 在废弃之前，刷新 BufWriter 和 tokio::fs::File，否则数据会丢失或延迟写入。 https://docs.rs/tokio/latest/tokio/io/index.html 和 https://docs.rs/tokio/latest/tokio/fs/struct.File.html
• read() 返回 Ok(0) 表示已关闭。忽略此情况的循环会以 100% CPU 空转。 https://tokio.rs/tokio/tutorial/io
• 每次 tokio::fs 调用都是一次 spawn_blocking。使用 fs::read / fs::write 或 BufWriter 进行批处理。 https://docs.rs/tokio/latest/tokio/fs/index.html
• 被丢弃的 Child 会继续运行，除非设置了 kill_on_drop(true)。output() 会强制使用管道 stdout 和 stderr。 https://docs.rs/tokio/latest/tokio/process/index.html 和 https://docs.rs/tokio/latest/tokio/process/struct.Command.html#method.output
• 在 Unix 上，第一个 ctrl_c() 监听器会永久替换默认的 SIGINT 处理程序。 https://docs.rs/tokio/latest/tokio/signal/fn.ctrl_c.html
• 命名管道服务器必须在移交已连接的实例之前创建下一个实例，否则客户端会收到 NotFound。客户端仅在 ERROR_PIPE_BUSY 时重试。NotFound 意味着没有服务器，因此应返回错误而不是重试。 https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeServer.html 和 https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeClient.html

参考文件

文件	涵盖内容
references/runtime.md	特性标志、Builder 和驱动、LocalRuntime、关闭、#[tokio::main] 和 #[tokio::test]
references/block-on-bridging.md	驱动运行时、block_on 和 Handle::block_on、EnterGuard 和 Handle::current、从同步代码调用异步代码、Unix fork
references/tasks.md	spawn 及其约束、JoinHandle、abort、JoinSet、spawn_blocking、block_in_place、协作预算、LocalSet、spawn_local、task_local
references/sync-locks.md	std 与 tokio Mutex、跨越 .await 的锁保护、RwLock、Semaphore、Notify、OnceCell、SetOnce、Barrier
references/channels.md	mpsc 背压、许可和关闭、oneshot、broadcast 延迟、watch 借用规则
references/select-cancellation.md	select! 规则、取消安全列表、跨循环钉住、biased、join!、try_join!、优雅关闭
references/time-testing.md	sleep、interval 和 MissedTickBehavior、timeout、Instant、暂停时间、在测试中模拟 I/O
references/io-net.md	AsyncRead/AsyncWrite 扩展 trait、BufWriter、split、io::copy、framing、TcpListener、TcpStream、TcpSocket、UdpSocket
references/fs-process.md	tokio::fs 及其阻塞池、File 刷新和废弃、Command、Child、kill_on_drop、stdio 管道
references/signals-named-pipes.md	ctrl_c、Unix 信号、Windows 控制台事件、Windows 命名管道服务器和客户端

所有已读取的页面均列在 SOURCES.md 中。