tokio-docs

tokio（1.54.1）

概要

このスキルは、公式tokioドキュメントの中で間違えやすいポイントをまとめたものです。キャンセル安全性、ランタイムのブロッキング、予期しないデフォルト動作、パニック、そして古いAPIの代替について扱っています。すべてのasync 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
• シングルスレッドランタイムでは、spawnされたタスクは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
• ブロッキング処理やCPU負荷の高いコードはspawn_blockingで実行し、無限ループは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
• select!は、すべてのブランチが無効でelseがない場合にパニックを起こします。https://docs.rs/tokio/latest/tokio/macro.select.html
• バックプレッシャーには、制限付きのmpsc::channel(n)を推奨します。recvは、すべてのSenderがドロップされた場合にのみNoneを返します。https://tokio.rs/tokio/tutorial/channels および https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html
• 低速なbroadcastレシーバーは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をポーリングするため、決してyieldしない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)を返した場合はクローズを意味します。これを無視するループはCPUを100%消費してスピンし続けます。https://tokio.rs/tokio/tutorial/io
• すべてのtokio::fs呼び出しは1回の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、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拡張トレイト、BufWriter、split、io::copy、フレーミング、TcpListener、TcpStream、TcpSocket、UdpSocket
references/fs-process.md	tokio::fsとそのブロッキングプール、Fileのflushとdrop、Command、Child、kill_on_drop、stdioパイプ
references/signals-named-pipes.md	ctrl_c、Unixシグナル、Windowsコンソールイベント、Windows名前付きパイプサーバーとクライアント

読み取ったすべてのページはSOURCES.mdにリストされています。