# 機能設計書 6-イベントループ設定

## 概要

本ドキュメントは、libuvライブラリにおけるイベントループ設定機能（`uv_loop_configure()`）の設計仕様を記述する。

### 本機能の処理概要

`uv_loop_configure()`は、イベントループのオプションを設定する関数である。可変長引数を使用し、指定されたオプションに応じた設定を行う。現在サポートされているオプションは、シグナルブロック（`UV_LOOP_BLOCK_SIGNAL`）、メトリクスアイドル時間計測（`UV_METRICS_IDLE_TIME`）、Linux固有のio_uring SQPOLL（`UV_LOOP_USE_IO_URING_SQPOLL`）の3種類である。

**業務上の目的・背景**：イベントループの動作をアプリケーションの要件に合わせてカスタマイズするために必要な機能である。プロファイリング時のSIGPROFブロック、パフォーマンス計測のためのメトリクス有効化、Linuxでの高性能I/Oのためのio_uring設定などを行う。

**機能の利用シーン**：
- プロファイリングツール使用時にSIGPROFシグナルをブロックする場合
- イベントループのパフォーマンス計測（アイドル時間等）を有効にする場合
- Linuxでio_uringのSQPOLLモードを使用する場合

**主要な処理内容**：
1. 可変長引数リストの解析
2. プラットフォーム非依存オプションの処理（現在は`uv__loop_configure()`に委譲）
3. `UV_METRICS_IDLE_TIME`: 内部フラグにメトリクスフラグを設定
4. `UV_LOOP_BLOCK_SIGNAL`: SIGPROFの場合のみ`UV_LOOP_BLOCK_SIGPROF`フラグを設定
5. `UV_LOOP_USE_IO_URING_SQPOLL`: Linux限定で`UV_LOOP_ENABLE_IO_URING_SQPOLL`フラグを設定

**関連システム・外部連携**：Linux環境でのio_uring連携。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_loop_configure()によるループオプション設定のAPI定義 |

## 機能種別

設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | 設定対象のイベントループ | NULLチェックなし |
| option | uv_loop_option | Yes | 設定するオプション種別 | UV_LOOP_BLOCK_SIGNAL, UV_METRICS_IDLE_TIME, UV_LOOP_USE_IO_URING_SQPOLL |
| ... | 可変長 | オプション依存 | オプション固有の追加パラメータ | UV_LOOP_BLOCK_SIGNALの場合はint（SIGPROF指定） |

### 入力データソース

呼び出し元から直接提供されるパラメータ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時は0、サポートされていないオプションの場合UV_ENOSYS、不正な引数の場合UV_EINVAL |

### 出力先

イベントループ構造体のフラグフィールド（`loop->flags`、`lfields->flags`）への更新。

## 処理フロー

### 処理シーケンス

```
1. 可変長引数の開始
   └─ va_start(ap, option)
2. プラットフォーム固有の処理委譲
   └─ uv__loop_configure(loop, option, ap)呼び出し
3. 可変長引数の終了
   └─ va_end(ap)
4. 結果の返却

[uv__loop_configure内部]
a. UV_METRICS_IDLE_TIME の場合
   └─ lfields->flags |= UV_METRICS_IDLE_TIME → 0返却
b. UV_LOOP_USE_IO_URING_SQPOLL の場合（Linux限定）
   └─ loop->flags |= UV_LOOP_ENABLE_IO_URING_SQPOLL → 0返却
c. UV_LOOP_BLOCK_SIGNAL の場合
   └─ 引数がSIGPROFかチェック
      └─ SIGPROF: loop->flags |= UV_LOOP_BLOCK_SIGPROF → 0返却
      └─ 他: UV_EINVAL返却
d. その他のオプション
   └─ UV_ENOSYS返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[va_start]
    B --> C{option == UV_METRICS_IDLE_TIME?}
    C -->|Yes| D[lfields->flags設定 → 0返却]
    C -->|No| E{option == UV_LOOP_USE_IO_URING_SQPOLL?}
    E -->|Yes & Linux| F[loop->flags設定 → 0返却]
    E -->|No| G{option == UV_LOOP_BLOCK_SIGNAL?}
    G -->|Yes| H{arg == SIGPROF?}
    H -->|Yes| I[loop->flags設定 → 0返却]
    H -->|No| J[UV_EINVAL返却]
    G -->|No| K[UV_ENOSYS返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | SIGPROFのみブロック可能 | UV_LOOP_BLOCK_SIGNALオプションではSIGPROFのみサポート | UV_LOOP_BLOCK_SIGNAL使用時 |
| BR-02 | Linux限定io_uring | UV_LOOP_USE_IO_URING_SQPOLLはLinux環境のみ有効 | Linux以外ではコンパイル時に除外 |
| BR-03 | 初期化後に設定 | uv_loop_init()後、uv_run()前に呼び出すことが推奨される | 常時 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_ENOSYS | 未サポート | 認識されないオプションが指定された場合 | サポート対象のオプションを使用 |
| UV_EINVAL | 不正引数 | UV_LOOP_BLOCK_SIGNALでSIGPROF以外が指定された場合 | SIGPROFを指定 |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

設定処理はフラグのビット操作のみであり、実質的にゼロコスト。

## セキュリティ考慮事項

特になし。

## 備考

- `UV_METRICS_IDLE_TIME`を設定すると、`uv_metrics_idle_time()`でアイドル時間を取得できるようになる
- `UV_LOOP_BLOCK_SIGPROF`フラグはI/Oポーリング中のSIGPROFシグナルをブロックし、プロファイラの干渉を防ぐ

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **261-266行目**: `uv_loop_option`列挙型。UV_LOOP_BLOCK_SIGNAL=0, UV_METRICS_IDLE_TIME, UV_LOOP_USE_IO_URING_SQPOLL |

**読解のコツ**: `uv_loop_option`の各値と、それに対応するフラグ（`loop->flags`と`lfields->flags`）の違いに注意する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **307行目**: `uv_loop_configure()`のAPI宣言 |
| 2-2 | uv-common.c | `src/uv-common.c` | **833-843行目**: `uv_loop_configure()`の実装。va_start/va_endで可変長引数を処理 |

**主要処理フロー**:
1. **837行目**: `va_start(ap, option)`
2. **839行目**: `uv__loop_configure(loop, option, ap)`に処理委譲
3. **840行目**: `va_end(ap)`

#### Step 3: プラットフォーム固有実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | loop.c | `src/unix/loop.c` | **214-239行目**: `uv__loop_configure()`のUnix実装 |

**主要処理フロー**:
- **218-221行目**: `UV_METRICS_IDLE_TIME`の場合、`lfields->flags |= UV_METRICS_IDLE_TIME`
- **224-228行目**: `UV_LOOP_USE_IO_URING_SQPOLL`の場合（Linux限定）、`loop->flags |= UV_LOOP_ENABLE_IO_URING_SQPOLL`
- **231-232行目**: `UV_LOOP_BLOCK_SIGNAL`以外は`UV_ENOSYS`
- **234-235行目**: 引数が`SIGPROF`以外は`UV_EINVAL`
- **237行目**: `loop->flags |= UV_LOOP_BLOCK_SIGPROF`

### プログラム呼び出し階層図

```
uv_loop_configure(loop, option, ...)      [src/uv-common.c:833]
    |
    +-- va_start(ap, option)
    |
    +-- uv__loop_configure(loop, option, ap)  [src/unix/loop.c:214]
    |       |
    |       +-- [UV_METRICS_IDLE_TIME] lfields->flags設定
    |       +-- [UV_LOOP_USE_IO_URING_SQPOLL] loop->flags設定 (Linux)
    |       +-- [UV_LOOP_BLOCK_SIGNAL] va_arg + SIGPROF判定 + loop->flags設定
    |
    └-- va_end(ap) + return err
```

### データフロー図

```
[入力]                    [処理]                              [出力]

uv_loop_t* loop     -->  オプション判定                  -->  int (0/UV_ENOSYS/UV_EINVAL)
uv_loop_option           |                                    |
可変長引数               +-- フラグ設定                       +-- loop->flags更新
                                                              +-- lfields->flags更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_loop_configure()のAPI宣言、uv_loop_option定義 |
| uv-common.c | `src/uv-common.c` | ソース | uv_loop_configure()の共通実装（va_list処理） |
| loop.c | `src/unix/loop.c` | ソース | uv__loop_configure()のUnix固有実装 |
