# バッチ設計書 20-tsansupp.txt

## 概要

本ドキュメントは、libuvプロジェクトのThreadSanitizer（TSAN）抑制設定ファイル（`tsansupp.txt`）のバッチ設計書である。既知の無害な競合条件をフィルタリングし、TSAN実行時の偽陽性レポートを抑制する。

### 本バッチの処理概要

tsansupp.txtは、ThreadSanitizer（TSAN）によるデータ競合検出時に適用される抑制（suppression）ルールを定義するテキストファイルである。環境変数 `TSAN_OPTIONS` に `suppressions=tsansupp.txt` を設定することで、指定されたパターンに一致する競合レポートが抑制される。

**業務上の目的・背景**：libuvのテストスイート（No.18）やベンチマーク（No.19）をThreadSanitizerつきでビルド・実行すると、glibcの `pthread_barrier_destroy` 内部で既知の無害なデータ競合が検出される。これはglibcの実装上の問題であり、libuvのバグではない。この偽陽性がテスト結果に影響することを防ぐため、抑制ルールを定義している。CI/CDワークフロー（sanitizer.yml: No.9）でTSANビルドを実行する際に使用される。

**バッチの実行タイミング**：TSAN有効でビルドされたテスト/ベンチマークバイナリの実行時に、TSAN_OPTIONS環境変数を通じて参照される。

**主要な処理内容**：
1. TSANランタイムが `tsansupp.txt` を読み込む
2. `race:pthread_barrier_destroy` ルールを適用
3. `pthread_barrier_destroy` に関連するデータ競合レポートを抑制
4. その他の真のデータ競合は通常通りレポートされる

**前後の処理との関連**：sanitizer.yml（No.9）でTSANビルド・テスト実行時に使用される。テストスイート（No.18）およびベンチマーク（No.19）のTSANビルド実行が前提となる。

**影響範囲**：TSAN実行時のレポート出力に影響する。抑制されたデータ競合は報告されなくなるため、抑制ルールが過度に広範でないことの確認が重要である。

## バッチ種別

テスト補助（サニタイザー抑制設定）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | TSANテスト実行時 |
| 実行時刻 | TSAN有効バイナリの実行時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | TSAN_OPTIONS環境変数による指定 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| TSANビルド | テスト/ベンチマークバイナリがThreadSanitizer有効でビルドされていること |
| TSAN_OPTIONS | 環境変数 `TSAN_OPTIONS` に `suppressions=tsansupp.txt` が設定されていること |
| ファイルパス | tsansupp.txtがTSAN実行時のカレントディレクトリからアクセス可能であること |

### 実行可否判定

TSAN_OPTIONS環境変数に `suppressions` パスが設定されている場合にのみ、TSANランタイムが本ファイルを読み込む。設定されていない場合は抑制ルールなしで全てのデータ競合が報告される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| 該当なし | - | - | - | 静的設定ファイルのためパラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| tsansupp.txt | テキスト（TSAN suppression形式） | 抑制ルール定義ファイル |

## 出力仕様

### 出力データ

本ファイルは直接的な出力を行わない。TSANランタイムの動作を制御し、指定パターンに一致するデータ競合レポートを抑制する。

| 出力先 | 形式 | 説明 |
|-------|------|------|
| TSANランタイム | フィルタ設定 | データ競合レポートの抑制 |

### 出力ファイル仕様

該当なし（TSANのレポート出力に間接的に影響する）。

## 処理フロー

### 処理シーケンス

```
1. TSAN有効バイナリの実行開始
   └─ TSAN_OPTIONS="suppressions=tsansupp.txt" ./uv_run_tests_a
2. TSANランタイムがtsansupp.txtを読み込み
   └─ 抑制ルールをパース
3. テスト/ベンチマーク実行中のデータ競合検出
   └─ TSANがメモリアクセスを監視
4. 抑制ルール適用
   └─ race:pthread_barrier_destroy に一致する競合を抑制
5. レポート出力
   └─ 抑制されなかった競合のみレポート
```

### フローチャート

```mermaid
flowchart TD
    A[TSAN有効バイナリ実行] --> B{suppressions指定あり?}
    B -->|Yes| C[tsansupp.txt読み込み]
    B -->|No| D[全競合レポート]
    C --> E[抑制ルールパース]
    E --> F[テスト/ベンチマーク実行]
    F --> G{データ競合検出?}
    G -->|No| H[正常終了]
    G -->|Yes| I{抑制ルールに一致?}
    I -->|Yes| J[レポート抑制]
    I -->|No| K[データ競合レポート出力]
    J --> F
    K --> F
    D --> F
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベースを使用しない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | - |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TSANエラー | ファイル読み込みエラー | tsansupp.txtが指定パスに存在しない | ファイルパスを確認し、tsansupp.txtをコピーまたはパスを修正 |
| TSANエラー | 構文エラー | 抑制ルールの形式が不正 | TSAN suppression形式に準拠するよう修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回 |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. 抑制ファイル未検出：`TSAN_OPTIONS` の `suppressions` パスを確認する
2. 抑制が効かない場合：ルール記法がTSANの書式に準拠しているか確認する
3. 過剰抑制の懸念：抑制ルールの範囲が最小限であることを確認する

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ルール（現在） |
| 目標処理時間 | 即時（ルール読み込みはマイクロ秒単位） |
| メモリ使用量上限 | 無視できる程度 |

## 排他制御

tsansupp.txtは読み取り専用の静的ファイルであるため、排他制御は不要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 該当なし | tsansupp.txt自体はログを出力しない |
| 進捗ログ | 該当なし | tsansupp.txt自体はログを出力しない |
| 終了ログ | 該当なし | tsansupp.txt自体はログを出力しない |
| エラーログ | ファイル読み込み失敗時 | TSANランタイムがエラーメッセージを出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 抑制ルールの妥当性 | 新しい既知の競合条件発生時 | 開発者による手動確認 |

## 備考

- 現在のルールは1件のみ：`race:pthread_barrier_destroy`
  - コメント：「glibc reads `count` field unsynchronized, not a libuv bug」
  - glibcが `pthread_barrier_destroy` 内で `count` フィールドを同期なしに読み取ることに起因する既知の問題
- TSAN suppressionファイルの構文：
  - `#` で始まる行はコメント
  - `race:関数名またはシンボル` でデータ競合を抑制
  - その他の抑制タイプ：`deadlock:`, `mutex:`, `signal:` 等
- 抑制ルールの追加は慎重に行う必要がある。真のバグを隠蔽しないよう、ルールは最小限に限定すべきである
- sanitizer.yml（No.9）でのTSANテスト実行時に `TSAN_OPTIONS` 環境変数を通じて参照される
