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 版本中發生 API 變更，因此除非專案已經啟用，否則不要建議使用它們。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)) 會恐慌：未來是在執行緒外部建立的。需要包裝它：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()，並將長生命週期的未來固定在循環外部，然後在 &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 首次立即觸發，並且預設會追上遺漏的 ticks。當追趕爆發不符合需求時，應設定 MissedTickBehavior::Delay 或 Skip。https://docs.rs/tokio/latest/tokio/time/enum.MissedTickBehavior.html
• timeout 在檢查截止時間之前會輪詢未來，因此一個永不讓出 CPU 的未來可能會在截止時間後以 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) 表示連接已關閉。忽略此情況的循環會導致 CPU 使用率 100%。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、coop 預算、LocalSet、spawn_local、task_local
references/sync-locks.md	std 與 tokio 的 Mutex、跨 .await 的守護物件、RwLock、Semaphore、Notify、OnceCell、SetOnce、Barrier
references/channels.md	mpsc 背壓、許可與關閉、oneshot、廣播延遲、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 擴充特徵、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 中。