# バッチ設計書 19-ベンチマークスイート実行（uv_run_benchmarks_a）

## 概要

本ドキュメントは、libuvプロジェクトのベンチマークスイート実行バッチ「uv_run_benchmarks_a」のバッチ設計書である。55個のベンチマーク宣言を含むパフォーマンス測定スイートであり、ループバック・TCP・UDP・spawn等の性能計測を行う。

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

uv_run_benchmarks_aは、libuvの主要APIのパフォーマンスを定量的に計測するベンチマークバイナリである。ベンチマークは `test/benchmark-list.h` で宣言・登録され、各ベンチマークは個別のCソースファイルとして実装されている。

**業務上の目的・背景**：libuvは高性能な非同期I/Oライブラリであり、パフォーマンスがコアバリューの一つである。コード変更がパフォーマンスに与える影響を定量的に評価するため、主要なI/O操作（TCP通信、UDP通信、パイプ通信、プロセス生成、非同期処理等）に対するベンチマークスイートを提供する。これにより、パフォーマンスリグレッションの早期検出と、最適化の効果測定が可能になる。

**バッチの実行タイミング**：開発者によるローカルでの手動実行（パフォーマンスチューニング時）。CMakeのLIBUV_BUILD_BENCHMARKSオプションがONの場合にビルドされる。

**主要な処理内容**：
1. CMakeによるベンチマークバイナリのビルド
2. ヘルパーサーバープロセス（tcp4_blackhole_server、tcp_pump_server、pipe_pump_server、tcp4_echo_server、pipe_echo_server）の起動
3. 各ベンチマークの実行と性能測定
4. 測定結果の出力

**前後の処理との関連**：CMakeLists.txt（No.4）でビルドターゲットが定義される。LIBUV_BUILD_BENCHMARKSはLIBUV_BUILD_TESTSに依存しており、テストビルドが有効な場合にのみベンチマークがビルドされる。テストスイート（No.18）とソースファイル（runner.c、echo-server.c等）を共有する。

**影響範囲**：ベンチマーク結果はパフォーマンスの判断基準として使用される。CI/CDでの自動実行は標準では行われないが、手動で実行しパフォーマンスリグレッションの検出に使用される。

## バッチ種別

テスト実行（パフォーマンスベンチマーク）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（./uv_run_benchmarks_a） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| CMakeビルド完了 | LIBUV_BUILD_BENCHMARKS=ONでCMakeビルドが成功していること |
| LIBUV_BUILD_TESTS有効 | ベンチマークビルドはテストビルドに依存する |
| 静的ライブラリ | uv_a（libuv静的ライブラリ）がビルド済みであること |
| ネットワーク環境 | ループバックネットワーク（127.0.0.1）が使用可能であること |

### 実行可否判定

CMakeLists.txtの `cmake_dependent_option` により、`LIBUV_BUILD_TESTS` がONの場合にのみ `LIBUV_BUILD_BENCHMARKS` が有効になる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| ベンチマーク名 | string | No | 全ベンチマーク | 特定ベンチマークのみ実行する場合に指定 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| test/benchmark-list.h | C言語ヘッダ | BENCHMARK_DECLARE/BENCHMARK_ENTRY/BENCHMARK_HELPER/HELPER_DECLAREマクロによるベンチマーク一覧定義 |
| test/benchmark-*.c | C言語ソース | 各ベンチマークの実装ファイル（18ファイル） |
| test/run-benchmarks.c | C言語ソース | ベンチマーク実行エントリポイント |
| test/runner.c | C言語ソース | テスト/ベンチマーク共通ランナーロジック |
| test/echo-server.c | C言語ソース | TCP/パイプエコーサーバーヘルパー |
| test/blackhole-server.c | C言語ソース | TCPブラックホールサーバーヘルパー |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 各ベンチマークの実行結果（スループット、レイテンシ等） |
| 終了コード | 整数 | 0: 全ベンチマーク完了、非0: エラー |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 直接のファイル出力なし（標準出力） |
| 出力先 | stdout / stderr |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. ベンチマークランナー初期化
   └─ プラットフォーム固有の初期化処理
2. ヘルパープロセス起動
   └─ tcp4_blackhole_server: TCP接続を受け入れてデータを破棄するサーバー
   └─ tcp_pump_server: TCP接続でデータをポンプするサーバー
   └─ pipe_pump_server: パイプでデータをポンプするサーバー
   └─ tcp4_echo_server: TCP接続でデータをエコーするサーバー
   └─ pipe_echo_server: パイプでデータをエコーするサーバー
3. TASK_LISTに登録されたベンチマーク実行
   └─ sizes: データ構造サイズ計測
   └─ loop_count/loop_count_timed/loop_alive: ループ性能
   └─ ping_pongs: TCPピンポン性能
   └─ ping_udp1/10/100: UDPピンポン性能
   └─ tcp_write_batch: TCPバッチ書き込み
   └─ tcp_pump/pipe_pump: TCP/パイプポンプ性能
   └─ tcp4_pound/pipe_pound: 接続負荷テスト
   └─ tcp_multi_accept: マルチアクセプト性能
   └─ udp_pummel: UDP負荷テスト（パケット数/時間ベース）
   └─ getaddrinfo: DNS解決性能
   └─ fs_stat: ファイルシステムstat性能
   └─ async: 非同期通知性能
   └─ queue_work: スレッドプールキュー性能
   └─ spawn: プロセス生成性能
   └─ thread_create: スレッド生成性能
   └─ million_async/million_timers: 大量ハンドル性能
4. 結果出力
   └─ 各ベンチマークのスループット/レイテンシを表示
```

### フローチャート

```mermaid
flowchart TD
    A[uv_run_benchmarks_a実行] --> B[ランナー初期化]
    B --> C[ヘルパーサーバー起動]
    C --> D[TASK_LISTからベンチマーク取得]
    D --> E{ヘルパー必要?}
    E -->|Yes| F[BENCHMARK_HELPERで関連付け]
    E -->|No| G[ベンチマーク直接実行]
    F --> G
    G --> H[性能測定実行]
    H --> I[結果出力]
    I --> J{全ベンチマーク完了?}
    J -->|No| D
    J -->|Yes| K[ヘルパーサーバー停止]
    K --> L[最終結果出力]
```

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

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

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

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0終了コード | ベンチマーク失敗 | ベンチマーク実行中のエラー | エラーログを確認し原因を特定 |
| EADDRINUSE | ポート競合 | ヘルパーサーバーのバインドポートが使用中 | 他のプロセスがポートを使用していないか確認 |
| SIGTERM | タイムアウト | ベンチマークが制限時間内に完了しない | 処理のデッドロックを調査 |

### リトライ仕様

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

### 障害時対応

1. ヘルパーサーバー起動失敗：ポートの競合を確認し、使用中のプロセスを終了する
2. ベンチマーク異常値：システム負荷が高い状態でないか確認し、静穏な環境で再実行する
3. セグメンテーション違反：デバッグビルドで再実行し、原因を特定する

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 55個のベンチマーク宣言（TASK_LISTには34エントリ + ヘルパー） |
| 目標処理時間 | ベンチマーク内容により変動（数分〜数十分） |
| メモリ使用量上限 | million_async/million_timersで数百MB以上使用の可能性 |

## 排他制御

ベンチマーク実行中は他のベンチマークやテストの同時実行を避ける必要がある。ネットワークベンチマークはループバックポートを使用するため、同じポートを使用する他のプロセスとの競合に注意が必要。ベンチマーク結果の安定性のため、システム負荷が低い状態での実行が推奨される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ベンチマーク開始時 | ベンチマークスイート開始メッセージ |
| 進捗ログ | 各ベンチマーク実行時 | ベンチマーク名、測定値 |
| 終了ログ | ベンチマーク完了時 | 全ベンチマーク完了メッセージ |
| エラーログ | エラー発生時 | エラー詳細情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- ベンチマークは以下のカテゴリに分類される：
  - **サイズ計測**: sizes（データ構造のメモリサイズ）
  - **ループ性能**: loop_count, loop_count_timed, loop_alive
  - **TCP性能**: ping_pongs, tcp_write_batch, tcp_pump, tcp4_pound, tcp_multi_accept
  - **UDP性能**: ping_udp, udp_pummel（パケット数ベース）, udp_timed_pummel（時間ベース）
  - **パイプ性能**: pipe_pump, pipe_pound
  - **DNS**: getaddrinfo
  - **ファイルシステム**: fs_stat
  - **非同期**: async1/2/4/8, async_pummel_1/2/4/8
  - **スレッドプール**: queue_work
  - **プロセス**: spawn, thread_create
  - **大量ハンドル**: million_async, million_timers
- UDPパメルテストは送受信パターンが `1v1`, `1v10`, ..., `1000v1000` と段階的にスケールする
- ヘルパープロセスは `BENCHMARK_HELPER` マクロで関連付けられ、対応するベンチマーク実行前に起動される
- LIBUV_BUILD_BENCHMARKSがOFFの場合（テストビルドが無効の場合）、ベンチマークバイナリはビルドされない
- ベンチマーク結果の比較は手動で行う必要がある（自動リグレッション検出機能は組み込まれていない）
