# 画面設計書 10-Prepareハンドル

## 概要

uv_prepare_tのAPIリファレンスページ（prepare.rst）に関する画面設計書。I/Oポーリング前に毎イテレーションで呼ばれるコールバックを管理するPrepareハンドルの初期化・開始・停止のAPI定義を提供する。

### 本画面の処理概要

本画面はlibuvのPrepareハンドル（uv_prepare_t）のAPIリファレンスページである。イベントループの各イテレーションにおいてI/Oポーリングの直前に実行されるコールバックを登録・管理するための3つのAPI関数を定義する。

**業務上の目的・背景**：Prepareハンドルはイベントループの各イテレーションでI/Oポーリング前に処理を実行する必要がある場合に使用される。I/Oの前処理、ソケットやバッファの準備、メトリクスの記録などのユースケースがある。Check（I/Oポーリング後）やIdle（毎イテレーション）と合わせて、ループイテレーションの特定フェーズにフックを挿入するための仕組みである。

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

**主要な操作・処理内容**：
1. データ型定義の参照 - uv_prepare_t, uv_prepare_cb の型情報確認
2. 初期化API参照 - uv_prepare_init()
3. 開始API参照 - uv_prepare_start()でコールバックを登録
4. 停止API参照 - uv_prepare_stop()でコールバック呼び出しを停止

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：Sphinx相互参照を通じてhandle.rst（uv_handle_t基底API）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 85 | Prepare初期化・開始・停止 | 主機能 | uv_prepare_init()/uv_prepare_start()/uv_prepare_stop()のAPI定義 |

## 画面種別

APIリファレンスページ（Prepareハンドル）

## URL/ルーティング

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

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "uv_prepare_t --- Prepare handle" |
| データ型定義 | 出力 | 型定義 | uv_prepare_t, uv_prepare_cb |
| パブリックメンバ | 出力 | テキスト | N/A（uv_handle_tメンバを参照） |
| API関数定義 | 出力 | 関数シグネチャ+説明 | 3個のAPI関数 |

## 表示項目

### Data types セクション

| データ型 | 説明 |
|----------|------|
| uv_prepare_t | Prepareハンドル型 |
| uv_prepare_cb | Prepareコールバック型 `void (*uv_prepare_cb)(uv_prepare_t* handle)` |

### Public members セクション

- N/A と記載。uv_handle_tのメンバが適用される旨の参照リンクあり。

### API セクション

| API関数 | シグネチャ | 説明 | 戻り値 |
|---------|-----------|------|--------|
| uv_prepare_init | `int uv_prepare_init(uv_loop_t* loop, uv_prepare_t* prepare)` | ハンドル初期化。常に成功 | 0 |
| uv_prepare_start | `int uv_prepare_start(uv_prepare_t* prepare, uv_prepare_cb cb)` | コールバック付きで開始。cb==NULLの場合のみ失敗 | 0 or UV_EINVAL |
| uv_prepare_stop | `int uv_prepare_stop(uv_prepare_t* prepare)` | 停止。コールバックは呼ばれなくなる。常に成功 | 0 |

## イベント仕様

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

`:c:type:` 参照リンク（uv_handle_t）を押下すると、ハンドル基底ページへ遷移する。"seealso" セクションのリンクからuv_handle_t API関数一覧にアクセス可能。

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Prepareハンドルはイベントループの設計概要（design.rst）で説明されている「ステップ6: Prepareハンドルコールバック」に対応
- uv_prepare_init()は常に成功する（戻り値0）
- uv_prepare_start()はcb==NULLの場合のみUV_EINVALを返す
- uv_prepare_stop()は常に成功する（戻り値0）
- Prepare/Check/Idleハンドルは同様のパターン（init/start/stop）を共有するが、実行タイミングがループイテレーション内で異なる
- Prepareコールバックの実行順序は `uv_run()` 内の `uv__run_prepare()` 呼び出し時点（I/Oポーリング直前）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_prepare_t構造体の定義。UV_PREPARE_PRIVATE_FIELDS マクロで内部フィールドが定義される |
| 1-2 | prepare.rst | `docs/src/prepare.rst` | PrepareハンドルのAPI仕様書 |

**読解のコツ**: Prepare/Check/Idleの3種のハンドルはlibuvではマクロベースの共通実装パターンを使用している。`src/unix/loop-watcher.c` や類似ファイルで UV_LOOP_WATCHER_DEFINE マクロにより3種の関数が一括生成される場合がある。

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

Prepareハンドルの実装はプラットフォーム依存のマクロ展開で生成されることが多い。Unix系ではloop-watcher.cに定義される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.c | `src/unix/core.c` | uv_close()内のUV_PREPAREケース（182-184行目）でuv__prepare_close()が呼ばれる |
| 2-2 | core.c | `src/unix/core.c` | uv_run()内の `uv__run_prepare(loop)` 呼び出し（452行目） |

**主要処理フロー**:
1. **core.c 452行目**: `uv__run_prepare(loop)` - イベントループイテレーション内でI/Oポーリング前に呼ばれる
2. **core.c 182行目**: `uv_close()` のUV_PREPAREケースで `uv__prepare_close()` を呼び出し

#### Step 3: イベントループ内での位置づけを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | uv_run()のメインループ内の呼び出し順序を確認 |

**主要処理フロー**:
- **core.c 450行目**: `uv__run_pending()` - 保留コールバック
- **core.c 451行目**: `uv__run_idle()` - Idleハンドル
- **core.c 452行目**: `uv__run_prepare()` - **Prepareハンドル（ここ）**
- **core.c 460行目**: `uv__io_poll()` - I/Oポーリング
- **core.c 474行目**: `uv__run_check()` - Checkハンドル

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

```
uv_run(loop, mode) [src/unix/core.c:427]
    |
    +-- ... (pending, idle)
    |
    +-- uv__run_prepare(loop) [src/unix/core.c:452]
    |       |
    |       +-- (prepare_handles キュー走査)
    |               +-- prepare_cb(handle) [ユーザーコールバック]
    |
    +-- uv__io_poll(loop, timeout) [I/Oポーリング]
    |
    +-- uv__run_check(loop) [Checkハンドル]
    |
    +-- ...

uv_prepare_init(loop, prepare)
    +-- uv__handle_init(loop, handle, UV_PREPARE)

uv_prepare_start(prepare, cb)
    +-- prepare->prepare_cb = cb
    +-- uv__queue_insert_tail(&loop->prepare_handles, ...)
    +-- uv__handle_start(handle)

uv_prepare_stop(prepare)
    +-- uv__queue_remove(...)
    +-- uv__handle_stop(handle)
```

### データフロー図

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

uv_prepare_t*, cb        --> uv_prepare_start()        --> prepare_handlesキューに登録
                              (コールバック設定+キュー追加)

ループイテレーション      --> uv__run_prepare()          --> prepare_cb(handle) 呼び出し
(I/Oポーリング直前)          (キュー走査)

uv_prepare_t*            --> uv_prepare_stop()          --> キューから除去
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| prepare.rst | `docs/src/prepare.rst` | テンプレート | PrepareハンドルページのRSTソース |
| uv.h | `include/uv.h` | ソース | uv_prepare_t型定義 |
| core.c | `src/unix/core.c` | ソース | uv_close()のPREPAREケース、uv_run()内のuv__run_prepare()呼び出し |
| handle.c | `src/win/handle.c` | ソース | Windows固有のPrepareハンドル実装 |
| design.rst | `docs/src/design.rst` | テンプレート | ループイテレーションにおけるPrepareの位置づけ説明 |
