# 画面設計書 6-イベントループ

## 概要

uv_loop_tのAPIリファレンスページ（loop.rst）に関する画面設計書。イベントループの作成・設定・実行・停止・終了、および関連するデータ型と関数のAPI定義を提供する。

### 本画面の処理概要

本画面はlibuvの中核であるイベントループ（uv_loop_t）の全APIを網羅的に解説するリファレンスページである。イベントループのライフサイクル全体をカバーし、初期化から終了までの全操作を定義する。

**業務上の目的・背景**：イベントループはlibuvの全機能の基盤であり、正しい初期化・実行・終了の手順を理解することはlibuv利用の大前提となる。本画面では `uv_loop_t` 構造体のデータ型定義、実行モード（DEFAULT/ONCE/NOWAIT）、ループオプション設定、時刻管理、ハンドル走査、fork対応などの全APIを提供する。

**画面へのアクセス方法**：APIドキュメント一覧ページ（api.rst）の "uv_loop_t --- Event loop" リンク押下、または `/loop.html` に直接アクセスする。

**主要な操作・処理内容**：
1. データ型定義の参照 - uv_loop_t, uv_loop_option, uv_run_mode, uv_walk_cb の型情報確認
2. ループ初期化・終了API参照 - uv_loop_init(), uv_loop_close(), uv_default_loop()
3. ループ実行・停止API参照 - uv_run(), uv_stop(), uv_loop_alive()
4. ループ設定API参照 - uv_loop_configure()のオプション（BLOCK_SIGNAL, METRICS_IDLE_TIME, IO_URING_SQPOLL）
5. 時刻管理API参照 - uv_now(), uv_update_time()
6. バックエンドAPI参照 - uv_backend_fd(), uv_backend_timeout()
7. ハンドル走査API参照 - uv_walk()
8. fork対応API参照 - uv_loop_fork()
9. データアクセサAPI参照 - uv_loop_get_data(), uv_loop_set_data()

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ページ内のSphinx相互参照を通じてhandle.rst, timer.rst等の関連APIページ

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | イベントループ初期化 | 主機能 | uv_loop_init()によるイベントループ初期化のAPI定義と使用例 |
| 2 | デフォルトループ取得 | 主機能 | uv_default_loop()によるデフォルトイベントループ取得のAPI定義 |
| 3 | イベントループ実行 | 主機能 | uv_run()によるイベントループ実行（DEFAULT/ONCE/NOWAIT）のAPI定義 |
| 4 | イベントループ停止 | 主機能 | uv_stop()によるイベントループ停止のAPI定義 |
| 5 | イベントループ終了 | 主機能 | uv_loop_close()によるイベントループ終了・リソース解放のAPI定義 |
| 6 | イベントループ設定 | 主機能 | uv_loop_configure()によるループオプション設定のAPI定義 |
| 7 | イベントループ存続確認 | 主機能 | uv_loop_alive()によるアクティブハンドル・リクエスト有無確認のAPI定義 |
| 8 | イベントループfork対応 | 主機能 | uv_loop_fork()によるfork後ループ再初期化のAPI定義 |
| 9 | 時刻更新 | 主機能 | uv_update_time()による内部時刻キャッシュ更新のAPI定義 |
| 10 | 現在時刻取得 | 主機能 | uv_now()によるループ内タイムスタンプ取得のAPI定義 |
| 11 | バックエンドFD取得 | 主機能 | uv_backend_fd()によるI/Oポーリング用FD取得のAPI定義 |
| 12 | バックエンドタイムアウト取得 | 主機能 | uv_backend_timeout()によるI/Oポーリングタイムアウト値取得のAPI定義 |
| 13 | ループデータ取得・設定 | 主機能 | uv_loop_get_data()/uv_loop_set_data()によるユーザーデータ関連付けのAPI定義 |
| 18 | ハンドル走査 | 主機能 | uv_walk()による登録済み全ハンドルの走査のAPI定義 |

## 画面種別

APIリファレンスページ（イベントループ）

## URL/ルーティング

- ソースファイル: `docs/src/loop.rst`
- 生成先URL: `/loop.html`
- Sphinxアンカー: `.. _loop:`

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "uv_loop_t --- Event loop" |
| データ型定義 | 出力 | 型定義 | uv_loop_t, uv_loop_option, uv_run_mode, uv_walk_cb |
| パブリックメンバ | 出力 | メンバ定義 | uv_loop_t.data |
| API関数定義 | 出力 | 関数シグネチャ+説明 | 18個のAPI関数 |

## 表示項目

### Data types セクション

| データ型 | 説明 |
|----------|------|
| uv_loop_t | ループデータ型 |
| uv_loop_option | ループオプション列挙型（UV_LOOP_BLOCK_SIGNAL=0, UV_METRICS_IDLE_TIME, UV_LOOP_USE_IO_URING_SQPOLL） |
| uv_run_mode | 実行モード列挙型（UV_RUN_DEFAULT=0, UV_RUN_ONCE, UV_RUN_NOWAIT） |
| uv_walk_cb | uv_walk用コールバック型定義 |

### Public members セクション

| メンバ | 型 | 説明 |
|--------|-----|------|
| uv_loop_t.data | void* | ユーザー定義データ。libuvは使用・変更しない |

### API セクション

| API関数 | シグネチャ | 説明 | バージョン |
|---------|-----------|------|-----------|
| uv_loop_init | `int uv_loop_init(uv_loop_t* loop)` | ループ構造体を初期化 | - |
| uv_loop_configure | `int uv_loop_configure(uv_loop_t* loop, uv_loop_option option, ...)` | ループオプション設定 | v1.0.2追加 |
| uv_loop_close | `int uv_loop_close(uv_loop_t* loop)` | 内部リソース解放。全ハンドル・リクエストがクローズ済みであること | - |
| uv_default_loop | `uv_loop_t* uv_default_loop(void)` | デフォルトループ取得（スレッドセーフでない） | - |
| uv_run | `int uv_run(uv_loop_t* loop, uv_run_mode mode)` | イベントループ実行。再入不可 | - |
| uv_loop_alive | `int uv_loop_alive(const uv_loop_t* loop)` | ループ生存確認 | - |
| uv_stop | `void uv_stop(uv_loop_t* loop)` | ループ停止要求 | - |
| uv_loop_size | `size_t uv_loop_size(void)` | uv_loop_t構造体サイズ取得（FFI用） | - |
| uv_backend_fd | `int uv_backend_fd(const uv_loop_t* loop)` | バックエンドFD取得 | - |
| uv_backend_timeout | `int uv_backend_timeout(const uv_loop_t* loop)` | ポーリングタイムアウト取得（ミリ秒/-1） | - |
| uv_now | `uint64_t uv_now(const uv_loop_t* loop)` | キャッシュされた現在時刻（ミリ秒） | - |
| uv_update_time | `void uv_update_time(uv_loop_t* loop)` | 内部時刻キャッシュ更新 | - |
| uv_walk | `void uv_walk(uv_loop_t* loop, uv_walk_cb walk_cb, void* arg)` | 全ハンドルを走査 | - |
| uv_loop_fork | `int uv_loop_fork(uv_loop_t* loop)` | fork後のカーネル状態再初期化（実験的） | v1.12.0追加 |
| uv_loop_get_data | `void* uv_loop_get_data(const uv_loop_t* loop)` | loop->data取得 | v1.19.0追加 |
| uv_loop_set_data | `void uv_loop_set_data(uv_loop_t* loop, void* data)` | loop->data設定 | v1.19.0追加 |

## イベント仕様

### 1-Sphinx相互参照リンク押下

API説明文内の `:c:func:` や `:c:type:` 参照リンクを押下すると、対応するAPIページの該当セクションへ遷移する。

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | データベースアクセスなし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| N/A | N/A | N/A | 静的HTMLのため動的メッセージなし |

## 例外処理

本画面は静的リファレンスドキュメントのため、画面固有の例外処理は存在しない。

## 備考

- uv_default_loop()はスレッドセーフではないと明記されている
- uv_run()は再入不可（コールバック内からの呼び出し禁止）
- uv_loop_fork()は実験的APIと位置付けられている
- uv_loop_configure()のUV_LOOP_USE_IO_URING_SQPOLLはv1.49.0追加のLinux固有オプション

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_loop_t構造体、uv_loop_option列挙型、uv_run_mode列挙型の定義 |
| 1-2 | unix.h | `include/uv/unix.h` | Unix固有のuv_loop_t内部メンバ定義 |

**読解のコツ**: uv_loop_tの定義はプラットフォーム依存部分を含むため、uv.hとプラットフォーム固有ヘッダを併せて確認する必要がある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | loop.c | `src/unix/loop.c` | uv_loop_init()（30行目）- ループの初期化処理全体 |
| 2-2 | core.c | `src/unix/core.c` | uv_run()（427行目）- ループの実行メインループ |

**主要処理フロー**:
1. **loop.c 30行目**: `uv_loop_init()` - memsetでゼロ初期化後、各サブシステムを順次初期化
2. **loop.c 51行目**: `heap_init()` - タイマーヒープの初期化
3. **loop.c 52-57行目**: 各キューの初期化（wq, idle_handles, async_handles, check_handles, prepare_handles, handle_queue）
4. **loop.c 79行目**: `uv__platform_loop_init()` - プラットフォーム固有初期化（epoll/kqueue等）
5. **core.c 427行目**: `uv_run()` - ループイテレーションの実行
6. **core.c 432行目**: `uv__loop_alive()` - アクティブハンドル/リクエスト/保留キュー/クローズ中ハンドルの確認

#### Step 3: ループ設定とフォーク対応を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | loop.c | `src/unix/loop.c` | uv__loop_configure()（214行目）- オプション別の分岐処理 |
| 3-2 | loop.c | `src/unix/loop.c` | uv_loop_fork()（135行目）- fork後のI/O/async/signal再初期化 |

**主要処理フロー**:
- **loop.c 218行目**: UV_METRICS_IDLE_TIMEオプション処理
- **loop.c 224行目**: UV_LOOP_USE_IO_URING_SQPOLLオプション処理（Linux限定）
- **loop.c 231行目**: UV_LOOP_BLOCK_SIGNALオプション処理（SIGPROFのみ）
- **loop.c 135-164行目**: fork後のwatcher再登録処理

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

```
uv_loop_init() [src/unix/loop.c:30]
    |
    +-- memset(loop, 0, sizeof(*loop))
    +-- heap_init() [タイマーヒープ]
    +-- uv__queue_init() x 7 [各種キュー]
    +-- uv__platform_loop_init() [epoll/kqueue等]
    +-- uv__signal_global_once_init()
    +-- uv__process_init()
    +-- uv_rwlock_init() / uv_mutex_init()
    +-- uv_async_init() [wq_async]

uv_run() [src/unix/core.c:427]
    |
    +-- uv__loop_alive()
    +-- uv__update_time()
    +-- uv__run_timers()
    +-- uv__run_pending()
    +-- uv__run_idle()
    +-- uv__run_prepare()
    +-- uv__io_poll()
    +-- uv__run_check()
    +-- uv__run_closing_handles()

uv_loop_close() [src/uv-common.c]
    |
    +-- uv__loop_close() [src/unix/loop.c:168]
            +-- uv__signal_loop_cleanup()
            +-- uv__platform_loop_delete()
            +-- uv__async_stop()
```

### データフロー図

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

uv_loop_t* loop          --> uv_loop_init()            --> 初期化済みloop
                              (メモリゼロ化+各種初期化)

uv_loop_t*, uv_run_mode  --> uv_run()                  --> int (0:完了, 非0:継続)
                              (イテレーション実行)

uv_loop_t*               --> uv_loop_close()            --> int (0:成功, UV_EBUSY:ハンドル未解放)
                              (リソース解放)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| loop.rst | `docs/src/loop.rst` | テンプレート | イベントループページのRSTソース |
| uv.h | `include/uv.h` | ソース | uv_loop_t等のパブリック型定義 |
| loop.c | `src/unix/loop.c` | ソース | uv_loop_init(), uv_loop_fork(), uv__loop_configure()の実装 |
| core.c | `src/unix/core.c` | ソース | uv_run(), uv_stop(), uv_backend_fd()等の実装 |
| uv-common.c | `src/uv-common.c` | ソース | uv_loop_size()等のクロスプラットフォーム実装 |
| core.c | `src/win/core.c` | ソース | Windows固有のuv_run()実装 |
