# 画面設計書 2-設計概要

## 概要

libuvのアーキテクチャ設計概要ページ（design.rst）に関する画面設計書。ハンドル/リクエストの概念、I/Oループのイテレーション、ファイルI/Oの設計思想を解説するドキュメントページである。

### 本画面の処理概要

本画面はlibuvの設計思想と内部アーキテクチャを開発者に解説するための技術ドキュメントページである。ライブラリを利用する開発者がlibuvの動作原理を深く理解し、適切な設計判断を行うための基礎知識を提供する。

**業務上の目的・背景**：libuvはイベント駆動型の非同期I/Oモデルを採用しており、そのアーキテクチャを理解することは正しいAPIの使用に不可欠である。本画面ではハンドルとリクエストの2つの抽象概念、イベントループのライフサイクル、ファイルI/Oのスレッドプール利用について体系的に解説し、開発者がlibuvを効果的に活用できるよう支援する。

**画面へのアクセス方法**：トップページ（index.rst）のDocumentationセクションにあるtoctreeリンク "Design overview" を押下、またはURLパス `/design.html` に直接アクセスする。

**主要な操作・処理内容**：
1. アーキテクチャ図の閲覧 - libuvの各サブシステム構成図（architecture.png）の確認
2. ハンドルとリクエストの概念理解 - 長寿命のハンドルと短寿命のリクエストの違い、ライフサイクル管理ガイドラインの確認
3. I/Oループの動作理解 - ループイテレーション図（loop_iteration.png）に基づく12段階の処理フロー確認
4. ファイルI/Oの設計理解 - スレッドプールによる非同期ファイルI/Oの実装戦略確認

**画面遷移**：
- 遷移元：トップページ（index.rst）
- 遷移先：なし（末端コンテンツページ）。ただしページ内リンクとして `uv_close()`, `uv_cancel()`, `uv_fs_req_cleanup()`, `uv_freeaddrinfo()`, `uv_queue_work` 等のAPIリファレンスへの相互参照がある

**権限による表示制御**：なし。公開ドキュメントであり全ユーザーが同一内容を閲覧可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | イベントループ実行 | 主機能 | イベントループの設計思想とイテレーション図を用いた動作原理の解説 |
| 15 | ハンドルクローズ | 補助機能 | ハンドル・リクエストのライフサイクル管理の概念説明 |
| 14 | ハンドル参照カウント制御 | 補助機能 | ハンドルの参照カウントによるループ存続制御の説明 |

## 画面種別

解説・リファレンスページ（設計概要）

## URL/ルーティング

- ソースファイル: `docs/src/design.rst`
- 生成先URL: `/design.html`（例: `https://docs.libuv.org/en/v1.x/design.html`）
- Sphinxアンカー: `.. _design:` によるクロスリファレンスターゲット

## 入出力項目

本画面は静的HTMLとして生成されるため、ユーザーからの入力項目は存在しない。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "Design overview" |
| 概要説明文 | 出力 | テキスト | libuvのクロスプラットフォーム設計の説明 |
| アーキテクチャ図 | 出力 | 画像 | `static/architecture.png`（75%スケール） |
| ループイテレーション図 | 出力 | 画像 | `static/loop_iteration.png`（75%スケール） |
| ハンドル/リクエスト説明 | 出力 | テキスト | ライフサイクルガイドライン7項目 |
| I/Oループ説明 | 出力 | テキスト | ループイテレーション12段階の説明 |
| ファイルI/O説明 | 出力 | テキスト | スレッドプール利用戦略の説明 |

## 表示項目

### Handles and requests セクション

| 表示項目 | 内容 | 備考 |
|----------|------|------|
| ハンドルの定義 | 長寿命オブジェクト。アクティブ時に特定操作を実行 | prepareハンドル、TCPサーバーハンドル等を例示 |
| リクエストの定義 | 短寿命操作。ハンドル上またはスタンドアロンで動作 | writeリクエスト、getaddrinfoリクエスト等を例示 |
| ガイドライン1 | uv_foo_init()成功時は必ずuv_close()を呼ぶ | |
| ガイドライン2 | ハンドルのみcloseする。リクエストはcloseしない | uv_tcp_t vs uv_write_t |
| ガイドライン3 | ハンドルのメモリはuv_close_cb内またはその後にのみ回収可能 | |
| ガイドライン4 | 多くのハンドルはinit + start/stop関数を持つ | uv_tcp_t vs uv_process_t |
| ガイドライン5 | リクエストは完了またはuv_cancel()で自動クローズ | |
| ガイドライン6 | uv_fs_tとuv_getaddrinfo_tのみ追加クリーンアップが必要 | uv_fs_req_cleanup(), uv_freeaddrinfo() |
| ガイドライン7 | リクエストのメモリはその時点以降にのみ回収可能 | |

### The I/O loop セクション

| 表示項目 | 内容 |
|----------|------|
| ステップ1 | loopの"now"概念が初期設定される |
| ステップ2 | 期限到来タイマーが実行される（UV_RUN_DEFAULT時） |
| ステップ3 | ループが"alive"か判定。alive = アクティブref'd handles or アクティブrequests or closing handles |
| ステップ4 | 保留コールバックが呼ばれる |
| ステップ5 | Idleハンドルコールバックが呼ばれる |
| ステップ6 | Prepareハンドルコールバックが呼ばれる |
| ステップ7 | Pollタイムアウトが計算される |
| ステップ8 | I/Oブロッキング |
| ステップ9 | Checkハンドルコールバックが呼ばれる |
| ステップ10 | クローズコールバックが呼ばれる |
| ステップ11 | "now"が更新される |
| ステップ12 | 期限到来タイマーが実行される。イテレーション終了 |

### File I/O セクション

| 表示項目 | 内容 |
|----------|------|
| 設計方針 | ネットワークI/Oと異なりプラットフォーム固有のファイルI/Oプリミティブがないため、スレッドプールでブロッキングI/Oを実行 |
| スレッドプール対象 | ファイルシステム操作、DNS関数（getaddrinfo/getnameinfo）、ユーザー指定コード（uv_queue_work） |

## イベント仕様

### 1-ページ内リンク押下

ドキュメント内のSphinx相互参照（`:c:func:` 等）を押下すると、対応するAPIリファレンスページの該当セクションへ遷移する。例: `:c:func:`uv_close()`` はハンドル基底ページ（handle.rst）のuv_close関数定義へ遷移する。

### 2-外部リンク押下

"this post" リンクを押下すると、libtorrentブログの非同期ディスクI/O解説記事（外部サイト）へ遷移する。

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

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

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

## メッセージ仕様

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

## 例外処理

- アーキテクチャ図（architecture.png）やループイテレーション図（loop_iteration.png）が見つからない場合、Sphinxビルドで警告が出力される
- Sphinx相互参照のターゲットが存在しない場合、ビルド時に警告が出力される

## 備考

- 本ページには2つの画像（architecture.png, loop_iteration.png）が含まれ、いずれも75%スケールで中央揃えで表示される
- important/note/warningのSphinxアドモニション（注意書き）が3箇所含まれる
- ファイルI/Oセクションでスレッドプールのサイズ制限に関する警告が表示される

---

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

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

### 推奨読解順序

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

設計概要ページで解説されるハンドルとリクエストの基本データ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_handle_t、uv_req_t の基底型定義。UV_HANDLE_TYPE_MAP/UV_REQ_TYPE_MAP マクロでハンドル・リクエストの全型を列挙 |
| 1-2 | design.rst | `docs/src/design.rst` | 設計概要ページのRSTソース。3セクション（Handles and requests, The I/O loop, File I/O）の構造 |

**読解のコツ**: `uv.h` は非常に大きなファイルだが、まずは `UV_HANDLE_TYPE_MAP` と `UV_REQ_TYPE_MAP` マクロでどのような型が存在するかを把握し、次にそれぞれの型定義を確認するとよい。

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

イベントループの中核実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.c (Unix) | `src/unix/core.c` | uv_run() 関数の実装。ループイテレーションの各ステップがコードに対応 |
| 2-2 | loop.c | `src/unix/loop.c` | uv_loop_init() の実装。ループの初期化処理 |

**主要処理フロー**:
1. **core.c 427行目**: `uv_run()` - イベントループのメインエントリーポイント
2. **core.c 432行目**: `uv__loop_alive()` でループの生存判定
3. **core.c 440-443行目**: UV_RUN_DEFAULT時の初回タイマー実行
4. **core.c 450行目**: `uv__run_pending()` - 保留コールバック実行
5. **core.c 451行目**: `uv__run_idle()` - Idleハンドル実行
6. **core.c 452行目**: `uv__run_prepare()` - Prepareハンドル実行
7. **core.c 460行目**: `uv__io_poll()` - I/Oポーリング
8. **core.c 474行目**: `uv__run_check()` - Checkハンドル実行
9. **core.c 475行目**: `uv__run_closing_handles()` - クローズコールバック実行
10. **core.c 477-478行目**: 時刻更新とタイマー実行

#### Step 3: ハンドルクローズの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c (Unix) | `src/unix/core.c` | uv_close() 関数（159行目）。ハンドル型に応じたクローズ処理の分岐 |
| 3-2 | core.c (Unix) | `src/unix/core.c` | uv__run_closing_handles()（368行目）。クローズ待ちハンドルの最終処理 |

**主要処理フロー**:
- **159行目**: `uv_close()` - UV_HANDLE_CLOSINGフラグ設定、close_cb保存、型別クローズ処理呼び出し
- **268行目**: `uv__make_close_pending()` - クローズ待ちリストに追加
- **368行目**: `uv__run_closing_handles()` - クローズ待ちハンドルのコールバック呼び出し

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

```
uv_run() [src/unix/core.c:427]
    |
    +-- uv__loop_alive() [core.c:393]
    |
    +-- uv__update_time()
    |
    +-- uv__run_timers() [src/timer.c:164]
    |
    +-- uv__run_pending() [core.c:113]
    |
    +-- uv__run_idle()
    |
    +-- uv__run_prepare()
    |
    +-- uv__io_poll()
    |
    +-- uv__run_check()
    |
    +-- uv__run_closing_handles() [core.c:368]
    |       |
    |       +-- uv__finish_close() [core.c:303]
    |               |
    |               +-- handle->close_cb(handle)
    |
    +-- uv__update_time()
    |
    +-- uv__run_timers()
```

### データフロー図

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

docs/src/design.rst  -->  Sphinx ビルドエンジン      -->  _build/html/design.html
static/architecture.png   (RST解析・画像埋め込み・
static/loop_iteration.png  HTML生成)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| design.rst | `docs/src/design.rst` | テンプレート | 設計概要ページのRSTソース |
| architecture.png | `docs/src/static/architecture.png` | 画像 | libuvアーキテクチャ図 |
| loop_iteration.png | `docs/src/static/loop_iteration.png` | 画像 | ループイテレーション図 |
| core.c | `src/unix/core.c` | ソース | uv_run(), uv_close() 等の中核実装 |
| loop.c | `src/unix/loop.c` | ソース | uv_loop_init(), uv_loop_fork() の実装 |
| timer.c | `src/timer.c` | ソース | uv__run_timers() の実装 |
| uv.h | `include/uv.h` | ソース | ハンドル・リクエスト型定義 |
