rust-concurrency-primitives

Rust の並行処理プリミティブ

スレッドベースの Rust の並行処理を、所有権、共有、同期を明示して設計する際に、このスキルを使用してください。共有可変状態を追加する前に、連携要件に合った最も単純なプリミティブを優先してください。

基本的なワークフロー

1. 作業を分類します。独立したフォーク・ジョイン、プロデューサー／コンシューマーパイプライン、共有状態、1 回限りの初期化、低レベルのアトミックな連携のいずれかです。
2. スレッドごとに所有データを使用することを優先します。複数のスレッドでデータを参照または変更する必要がある場合にのみ、共有所有権を追加してください。
3. 子スレッドがスタックデータを借用でき、関数の戻り前に終了する必要がある場合は、std::thread::scope を使用してください。
4. 所有権の移動やパイプラインにはチャネルを使用してください。共有状態の方が明確なモデルである場合にのみ、Arc<Mutex<T>> または Arc<RwLock<T>> を使用してください。
5. ロックの保持範囲を短くし、保護対象の不変条件そのものである場合を除き、ロックを保持したままユーザー制御下のコードやブロッキングコードを呼び出さないでください。
6. その場しのぎのグローバル可変状態の代わりに、スレッドセーフな 1 回限りの初期化には OnceLock または LazyLock を使用してください。
7. アトミックは特殊な用途のツールとして扱ってください。より弱い順序付けが妥当で、その理由が文書化されるまでは、デフォルトで SeqCst を使用してください。

プリミティブの選択

新しい共有状態プリミティブを導入する場合や、デッドロックを起こしやすいコードをレビューする場合は、事前に references/threading-shared-state.md を読んでください。

必要な用途	プリミティブ
短命なスレッドにローカルデータを借用させる	std::thread::scope
作業や結果を移動する	std::sync::mpsc またはプロジェクトのチャネルクレート
共有読み書き状態	Arc<Mutex<T>>
読み取りが多く、書き込みがまれ	Arc<RwLock<T>>
条件の変化を待つ	Mutex と組み合わせた Condvar
グローバルな 1 回限りの初期化	LazyLock または OnceLock
カウンター、フラグ、ロックフリーな連携	std::sync::atomic

安全性とレビューのルール

• スレッド境界を越える値には Send を、複数のスレッドから使用する共有参照には Sync を要求してください。
• パニック時にポイズニングを伝播させるか、PoisonError::into_inner で回復するかを決めてください。
• 複数のロックを取得できる場合は、ロックの取得順序を定めてください。
• クローンした値が所有権ハンドルであり、可読性が重要な場合は、value.clone() よりも Arc::clone(&value) を優先してください。
• 問題が純粋な CPU データ並列処理であり、プロジェクトがすでにその依存関係を受け入れている場合は、データの並列イテレーションに Rayon を使用してください。

テスト

• 最終状態、メッセージ数、シャットダウンを対象とした決定的なテストを追加してください。
• テストの連携にはバリア、チャネル、またはスコープ付きスレッドを使用し、スリープは避けてください。
• コードが依存する場合は、パニック、送信側／受信側のドロップ、またはキャンセル動作を対象としたテストを少なくとも 1 つ追加してください。