# 機能設計書 2-デフォルトループ取得

## 概要

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

### 本機能の処理概要

`uv_default_loop()`は、プロセス全体で共有されるデフォルトのイベントループインスタンスを取得する関数である。初回呼び出し時にグローバルな`uv_loop_t`構造体を`uv_loop_init()`で初期化し、以降の呼び出しではキャッシュ済みのポインタを返す。

**業務上の目的・背景**：多くのアプリケーションでは単一のイベントループで十分であり、毎回ユーザーがメモリ確保と初期化を行う手間を省くために提供されている。簡易的なプログラムやプロトタイプ開発において、ボイラープレートコードを削減する役割を果たす。

**機能の利用シーン**：シングルスレッドのアプリケーションで単一のイベントループを使用する場合に利用される。マルチスレッド環境で複数のイベントループが必要な場合は、`uv_loop_init()`を直接使用することが推奨される。

**主要な処理内容**：
1. グローバルポインタ`default_loop_ptr`がNULLでない場合、既存のポインタを返却
2. NULLの場合、静的に確保された`default_loop_struct`を`uv_loop_init()`で初期化
3. 初期化成功時、`default_loop_ptr`にポインタを設定して返却
4. 初期化失敗時、NULLを返却

**関連システム・外部連携**：内部的に`uv_loop_init()`を呼び出すため、同機能と同等のプラットフォーム連携が発生する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_default_loop()によるデフォルトイベントループ取得のAPI定義 |
| 33 | 基本事項 | 主機能 | uv_default_loop()の使用方法の解説 |

## 機能種別

データ取得 / 初期化処理（遅延初期化パターン）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| （なし） | - | - | パラメータなし | - |

### 入力データソース

入力パラメータはない。内部のグローバル静的変数`default_loop_struct`および`default_loop_ptr`を使用する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uv_loop_t* | デフォルトイベントループへのポインタ。初期化失敗時はNULL |

### 出力先

関数の戻り値として返却される。

## 処理フロー

### 処理シーケンス

```
1. default_loop_ptrの確認
   └─ NULLでなければ既存ポインタを返却（高速パス）
2. default_loop_structの初期化
   └─ uv_loop_init(&default_loop_struct)を呼び出し
3. 初期化結果の判定
   └─ 失敗時はNULLを返却
4. default_loop_ptrの設定
   └─ &default_loop_structをdefault_loop_ptrに格納
5. ポインタの返却
   └─ default_loop_ptrを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{default_loop_ptr != NULL?}
    B -->|Yes| C[default_loop_ptrを返却]
    B -->|No| D[uv_loop_init実行]
    D --> E{初期化成功?}
    E -->|No| F[NULLを返却]
    E -->|Yes| G[default_loop_ptr = &default_loop_struct]
    G --> H[default_loop_ptrを返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | シングルトンパターン | プロセス内でデフォルトループは一つのみ存在する | 常時 |
| BR-02 | 遅延初期化 | 初回呼び出し時にのみ初期化が行われる | default_loop_ptrがNULLの場合 |
| BR-03 | uv_loop_closeとの連動 | uv_loop_close()でデフォルトループを閉じるとdefault_loop_ptrがNULLにリセットされる | uv_loop_close()呼び出し時 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NULL（戻り値） | 初期化失敗 | uv_loop_init()が失敗した場合 | プロセスを終了するか、リソースを解放して再試行 |

### リトライ仕様

リトライ機構は組み込まれていない。`uv_loop_init()`の失敗原因を解決してから再度呼び出す必要がある。

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

該当なし。

## パフォーマンス要件

初回呼び出し時は`uv_loop_init()`の実行コストが発生するが、2回目以降はポインタ比較のみで高速に返却される。

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

- グローバル変数への競合アクセスに対するスレッドセーフティは保証されていない。マルチスレッド環境で初回呼び出しが競合する場合、呼び出し元で同期を取る必要がある。

## 備考

- `uv_loop_close()`でデフォルトループを閉じた後、再度`uv_default_loop()`を呼び出すと新たに初期化される
- `uv_loop_new()`は非推奨であり、`uv_default_loop()`または`uv_loop_init()`の使用が推奨される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv-common.c | `src/uv-common.c` | **846-847行目**: グローバル静的変数`default_loop_struct`と`default_loop_ptr`の定義 |
| 1-2 | uv.h | `include/uv.h` | **1941-1956行目**: `uv_loop_s`構造体の定義 |

**読解のコツ**: `default_loop_struct`はBSSセグメントに配置される静的変数であり、`default_loop_ptr`はそのアドレスをキャッシュするポインタである。シングルトンパターンの実装に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **290行目**: `uv_default_loop()`のAPI宣言 |
| 2-2 | uv-common.c | `src/uv-common.c` | **850-859行目**: `uv_default_loop()`の実装 |

**主要処理フロー**:
1. **851-852行目**: `default_loop_ptr`がNULLでなければ即座に返却
2. **854-855行目**: `uv_loop_init(&default_loop_struct)`で初期化、失敗時はNULL返却
3. **857-858行目**: `default_loop_ptr`に格納して返却

#### Step 3: uv_loop_closeとの連動を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-common.c | `src/uv-common.c` | **878-905行目**: `uv_loop_close()`の実装。**901-902行目**で`loop == default_loop_ptr`の場合に`default_loop_ptr = NULL`とリセットする |

**主要処理フロー**:
- **901-902行目**: デフォルトループをクローズした場合、`default_loop_ptr`がNULLにリセットされ、次回`uv_default_loop()`呼び出し時に再初期化が行われる

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

```
uv_default_loop()                       [src/uv-common.c:850]
    |
    +-- [キャッシュ確認] default_loop_ptr != NULL → 即返却
    |
    +-- uv_loop_init(&default_loop_struct)  [src/unix/loop.c:30]
    |       └── (No.1 イベントループ初期化の全処理)
    |
    └── default_loop_ptr設定 → 返却
```

### データフロー図

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

（なし）        -->  default_loop_ptrチェック     -->  uv_loop_t*
                     |                                 (既存ポインタ or
                     +-- uv_loop_init()                 新規初期化 or NULL)
                     |
                     +-- default_loop_ptr設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_default_loop()のAPI宣言 |
| uv-common.c | `src/uv-common.c` | ソース | uv_default_loop()の実装、default_loop_struct/ptrの定義 |
| loop.c | `src/unix/loop.c` | ソース | uv_loop_init()の実装（内部呼び出し先） |
