# 画面設計書 38-イベントループ応用

## 概要

libuvユーザーガイドのイベントループ応用ページ（guide/eventloops.rst）に関する画面設計書。イベントループの高度な使い方、特にuv_stop()の動作セマンティクスとループ停止のメカニズムを解説するページの構造と仕様を定義する。

### 本画面の処理概要

本ページはlibuvのイベントループに関する高度なトピックを扱うガイドページである。複数ループの運用やlibuvイベントループの他ライブラリへの組み込みについての概要、およびuv_stop()によるループ停止の詳細なセマンティクスを解説する。libuvのCソースコード（src/unix/core.c）のuv_run()実装を直接引用して内部動作を説明する。

**業務上の目的・背景**：イベントループの停止タイミングは、正しく理解しないとリソースリークや予期しない動作を引き起こす。本ページでは、uv_stop()が「次のイテレーション」で効果を発揮すること、現在のイテレーションのイベントは引き続き処理されること、stop_flagがuv_backend_timeout()に与える影響を、libuvの実装コードを引用しながら正確に解説する。Qt等の他のイベントループライブラリとの統合についても概要が述べられている。

**画面へのアクセス方法**：ユーザーガイド一覧（No.31）のtoctreeリンク、またはプロセス（No.37）からのNextナビゲーションでアクセスする。URLパスは `/guide/eventloops.html` となる。

**主要な操作・処理内容**：
1. 複数ループの運用と他ライブラリ組み込みの概要説明
2. uv_stop()の動作セマンティクスの詳細解説
3. libuvのuv_run()実装コード（src/unix/core.c）の引用表示
4. stop_flagの動作メカニズムの説明
5. uvstop/main.cサンプルの表示と解説

**画面遷移**：
- 遷移元：ユーザーガイド一覧（No.31）、プロセス（No.37）
- 遷移先：ユーティリティ（No.39）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | イベントループ初期化 | 主機能 | 複数イベントループの管理方法・他ライブラリへの組み込みの解説 |
| 3 | イベントループ実行 | 主機能 | NOWAITモードでのループ実行の使用例 |
| 4 | イベントループ停止 | 補助機能 | ループ停止タイミングの説明 |
| 11 | バックエンドFD取得 | 補助機能 | 他イベントループへの組み込み時のバックエンドFD使用例 |

## 画面種別

チュートリアル（実装コード引用付き解説）

## URL/ルーティング

- ソースファイル：`docs/src/guide/eventloops.rst`
- 生成先URL：`/guide/eventloops.html`
- Sphinxルーティング：guide.rstのtoctreeから参照

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ループ応用概要 | 出力 | テキスト | 複数ループ運用と他ライブラリ統合の概要 |
| uv_run実装コード | 出力 | Cソースコード | src/unix/core.cの行304-324（行番号・ハイライト付き） |
| stop_flag説明 | 出力 | テキスト | uv_stop()のセマンティクス詳細説明 |
| uvstop/main.cコード | 出力 | Cソースコード | ループ停止サンプル（行番号・ハイライト付き） |

## 表示項目

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| セクションタイトル | "Advanced event loops" | ページ見出し（h1） |
| Stopping an event loop (h2) | uv_stop()の動作セマンティクス | |
| uv_run実装 | src/unix/core.cの行304-324 | literalinclude、ハイライト行: 10,19,21 |
| stop_flagの説明 | uv_backend_timeout()への影響等 | |
| uvstop/main.c | ループ停止のデモ | literalinclude、ハイライト行: 11 |

## イベント仕様

### 1-uv_stop()の動作メカニズム

uvstop/main.cで示される動作：
1. uv_idle_t と uv_prepare_t を登録しループを開始
2. idle_cbが5回呼ばれた時点でuv_stop()を呼び出す
3. uv_stop()は現在のイテレーションを完了してから効果を発揮する
4. prep_cbも同じイテレーションで呼ばれる（停止後も現在イテレーションは実行される）

### 2-libuvソースコード参照

src/unix/core.cのuv_run()関数の実装コードが直接引用される。stop_flagのチェックタイミングとuv_backend_timeout()の関係を示す。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | 静的HTMLページのため該当なし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| - | - | - | 特別なメッセージ表示なし |

## 例外処理

静的HTMLページのため、アプリケーションレベルの例外処理は発生しない。

## 備考

- 本ページは他のガイドページと比べて短い内容であり、主にuv_stop()のセマンティクスに焦点を当てている。
- libuvの実装コード（src/unix/core.c）を直接引用している点が他のガイドページとの大きな違いである。
- Qt等の他のイベントループへの組み込みについては概要のみで、具体的なコード例は提供されていない。
- uvstop/main.cではuv_idle_tとuv_prepare_tの両方を使用して、uv_stop()後も現在イテレーションの残りのコールバックが実行されることを実証する。

---

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

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

### 推奨読解順序

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

イベントループの内部状態（stop_flag）とイテレーションの概念を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | eventloops.rst | `docs/src/guide/eventloops.rst` | 行1-8: 複数ループ運用と他ライブラリ統合の概要 |
| 1-2 | core.c | `src/unix/core.c` | 行304-324: uv_run()の実装、stop_flagのチェックタイミング |

**読解のコツ**: uv_run()のwhile文ループ構造を理解することが最重要。stop_flagが設定されると、uv_backend_timeout()が0を返し、I/Oポーリングでブロックしなくなる。

#### Step 2: uv_run()の内部動作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | eventloops.rst | `docs/src/guide/eventloops.rst` | 行22-26: literalincludeによるcore.cの引用（行304-324、ハイライト: 10,19,21） |
| 2-2 | eventloops.rst | `docs/src/guide/eventloops.rst` | 行28-36: stop_flagの動作メカニズム説明 |

**主要処理フロー（src/unix/core.c uv_run()）**:
1. **行304**: `uv_run()` 関数開始
2. **行313**: タイマー更新
3. **行314**: pending callbacks実行
4. **行315**: idle callbacks実行
5. **行316**: prepare callbacks実行
6. **行317-319**: I/Oポーリング（stop_flagがあるとtimeout=0）
7. **行320**: check callbacks実行
8. **行321**: close callbacks実行
9. **行323**: stop_flagチェック → ループ継続/終了判定

#### Step 3: uvstopサンプルで動作を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uvstop/main.c | `docs/code/uvstop/main.c` | 行20-33: main関数 -- idle + prepare の両方を登録しuv_run |
| 3-2 | uvstop/main.c | `docs/code/uvstop/main.c` | 行6-14: idle_cb -- counter >= 5 でuv_stop()呼び出し |
| 3-3 | uvstop/main.c | `docs/code/uvstop/main.c` | 行16-18: prep_cb -- "Prep callback" を表示 |

**主要処理フロー**:
1. **行24-25**: `uv_idle_init / uv_idle_start` -- Idleハンドル開始
2. **行27-28**: `uv_prepare_init / uv_prepare_start` -- Prepareハンドル開始
3. **行30**: `uv_run(uv_default_loop(), UV_RUN_DEFAULT)` -- ループ実行
4. **行10-12**: idle_cb内で `counter >= 5` のとき `uv_stop()` 呼び出し
5. prep_cbはuv_stop()が呼ばれた同じイテレーションでも実行される

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

```
uvstop/main.c
    |
    +-- uv_idle_init(loop, &idler)
    +-- uv_idle_start(&idler, idle_cb)
    +-- uv_prepare_init(loop, &prep)
    +-- uv_prepare_start(&prep, prep_cb)
    +-- uv_run(loop, UV_RUN_DEFAULT)
            |
            +-- [ループ内イテレーション]
                    +-- idle_cb() [毎回呼ばれる]
                    |       +-- counter++
                    |       +-- [counter >= 5] uv_stop(loop)
                    +-- prep_cb() [毎回呼ばれる]
                    +-- [stop_flag確認] --> ループ終了

src/unix/core.c uv_run()
    |
    +-- while (uv_loop_alive(loop) || ...)
            +-- uv__update_time(loop)
            +-- uv__run_timers(loop)
            +-- uv__run_pending(loop)
            +-- uv__run_idle(loop) <-- idle_cbが呼ばれる
            +-- uv__run_prepare(loop) <-- prep_cbが呼ばれる
            +-- uv__io_poll(loop, timeout) <-- stop_flag時timeout=0
            +-- uv__run_check(loop)
            +-- uv__run_closing_handles(loop)
            +-- [stop_flag?] break
```

### データフロー図

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

イベント登録              --> uv_run()                  --> イテレーション実行
  idle_cb                      uv__run_idle()              idle_cbコールバック
  prep_cb                      uv__run_prepare()           prep_cbコールバック
uv_stop()呼び出し         --> stop_flag = 1             --> 次イテレーションで停止
                               uv_backend_timeout() = 0
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| eventloops.rst | `docs/src/guide/eventloops.rst` | テンプレート | イベントループ応用ガイドページ本体 |
| guide.rst | `docs/src/guide.rst` | テンプレート | 親ページ |
| core.c | `src/unix/core.c` | ソース | uv_run()の実装（literalincludeで引用） |
| uvstop/main.c | `docs/code/uvstop/main.c` | ソース | ループ停止デモサンプル |
| conf.py | `docs/src/conf.py` | 設定 | Sphinxビルド設定 |
