rust-unsafe-boundaries

Rust の unsafe 境界

このスキルは、unsafe な Rust コードを小さく、ドキュメント化され、テスト可能な境界の内側に隔離するために使用します。必要な操作を、許容できる正確性とパフォーマンスで安全な API では表現できない場合に限り、unsafe コードを使用できます。

基本的なワークフロー

1. まず安全な設計を試します。標準 API、所有権の再構成、イテレーター、同期プリミティブ、既存のクレートを確認します。
2. 安全な Rust では証明できない不変条件を明示します。不変条件を書き出せない場合は、まだ unsafe コードを書かないでください。
3. unsafe ブロックは極小に保ちます。ブロックに入る前に、安全なコードでランタイムチェックとセットアップを行います。
4. 各 unsafe ブロックの直前に // SAFETY: コメントを記述し、その中の各 unsafe 操作が有効である理由を説明します。
5. 呼び出し元に追加の条件を満たす責任がある場合に限り、関数を unsafe fn としてマークします。その条件は # Safety セクションに記載します。
6. unsafe_op_in_unsafe_fn を有効にするか、その設定に従います。unsafe 関数内の unsafe 操作も、明示的な unsafe ブロックで囲みます。
7. 通常の動作、境界ケース、パニック経路、ドロップ時の動作をテストします。プロジェクトが対応している場合は Miri を実行します。

境界ルール

unsafe コードを追加または承認する前に、references/safety-invariants.md を読んでください。

• private な unsafe 内部実装と、安全な公開ラッパーを優先します。
• 非推奨または場当たり的な未初期化メモリのパターンより、MaybeUninit<T> を優先します。
• 妥当性、アラインメント、初期化、エイリアシング、ライフタイムのすべてを証明できない限り、raw ポインターから参照を作成しないでください。
• 容量、初期化、所有権を証明せずに、set_len、ポインター演算、from_raw_parts を使用しないでください。
• 部分的に初期化された値、手動でのドロップ、または長さの変更が関わる場合は、パニック安全性を明確にします。
• static mut は避け、OnceLock、LazyLock、アトミック、またはロックされた状態を優先します。

ドキュメントのパターン

/// # Safety
///
/// `ptr` must be non-null, aligned for `T`, initialized, and valid for reads
/// for the returned lifetime. No mutable reference may alias the same value.
pub unsafe fn read_ref<'a, T>(ptr: *const T) -> &'a T {
    // SAFETY: The caller guarantees `ptr` satisfies the documented contract.
    unsafe { &*ptr }
}

レビューチェックリスト

• すべての unsafe ブロックに、その箇所の SAFETY の説明があります。
• すべての unsafe fn または unsafe トレイトに、# Safety 契約があります。
• 公開されている安全な API から内部不変条件に違反できません。
• ドロップ、パニック、早期リターンの各経路で、初期化と所有権が保たれます。
• テストまたは Miri で、正常なケースだけでなく危険な境界も確認しています。