# 画面設計書 12-Idleハンドル

## 概要

本ドキュメントは、libuvドキュメントサイトにおける `uv_idle_t`（Idleハンドル）APIリファレンスページの画面設計書である。Sphinxにより生成されるHTMLページとして、Idleハンドルの型定義・API関数仕様を表示する。

### 本画面の処理概要

Idleハンドルは、イベントループの各イテレーションにおいてPrepareハンドルの直前に指定コールバックを実行するためのハンドルである。名前に反して、ループが「アイドル」のときだけ呼ばれるのではなく、毎イテレーションで呼ばれる点に注意が必要である。

**業務上の目的・背景**：Idleハンドルは、イベントループの各イテレーションで確実に実行される処理を登録するために使用される。Prepareハンドルとの重要な違いは、アクティブなIdleハンドルが存在する場合、ループはI/Oポーリングでブロックせずにゼロタイムアウトのポーリングを行う点である。これにより、バックグラウンドで処理を継続しつつもI/Oイベントにも即座に反応できる仕組みを提供する。本ページは、libuvを利用する開発者がIdleハンドルの動作特性（特にゼロタイムアウトポーリング）を正確に理解するための公式リファレンスである。

**画面へのアクセス方法**：トップページ → APIドキュメント一覧（api.rst） → Idleハンドル（idle.rst）の順にナビゲーションリンクを辿ってアクセスする。Sphinxの目次ツリー（toctree）からも直接アクセス可能である。

**主要な操作・処理内容**：
1. `uv_idle_t` 型の説明とコールバック型 `uv_idle_cb` の定義を閲覧する
2. Idleハンドルとprepareハンドルの違い（ゼロタイムアウトポーリング）に関するnoteを確認する
3. Idleハンドルの名前に反する動作に関するwarningを確認する
4. `uv_idle_init()` / `uv_idle_start()` / `uv_idle_stop()` の各API仕様を確認する
5. 基底ハンドル（`uv_handle_t`）の共通API関数へのリンクを辿る

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底ページ（handle.rst）への参照リンク、Prepareハンドルページ（prepare.rst）への参照リンク
- 関連ページ：Prepareハンドル（prepare.rst）、Checkハンドル（check.rst）

**権限による表示制御**：なし（公開ドキュメントサイトのため、全ユーザーが同一内容を閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 87 | Idle初期化・開始・停止 | 主機能 | uv_idle_init()/uv_idle_start()/uv_idle_stop()のAPI定義 |

## 画面種別

APIリファレンス詳細ページ

## URL/ルーティング

`docs/src/idle.rst` → ビルド後: `/idle.html`

## 入出力項目

本ページはドキュメント表示ページのため、ユーザー入力項目はない。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページコンテンツ | 出力 | HTML | rstファイルからSphinxによって生成されたHTML |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_idle_t` --- Idle handle | ページタイトル |
| 概要説明 | Idle handles will run the given callback... | Idleハンドルの動作概要 |
| Note | prepareハンドルとの違い（ゼロタイムアウトポーリング） | 重要な動作差異 |
| Warning | 名前に反して毎イテレーションで呼ばれる点 | 誤解防止の警告 |
| Data types | `uv_idle_t`, `uv_idle_cb` | 型定義 |
| Public members | N/A | 固有のパブリックメンバーはなし |
| API - uv_idle_init | 初期化関数の仕様 | 常に成功し0を返す |
| API - uv_idle_start | 開始関数の仕様 | cbがNULLの場合UV_EINVALを返す |
| API - uv_idle_stop | 停止関数の仕様 | 常に成功し0を返す |
| See also | uv_handle_t API functions | 基底ハンドルAPIへの参照 |

## イベント仕様

### 1-ページ内リンク遷移

SphinxのreStructuredTextのcross-referenceにより、`:c:type:`uv_handle_t`` へのリンクをクリックすると、ハンドル基底ページに遷移する。`:c:type:`uv_prepare_t`` のリンクでPrepareハンドルページに遷移する。

### 2-Idleコールバック実行（ランタイム動作）

ドキュメントに記載されるランタイム動作として、`uv_idle_start()` で登録したコールバックは、毎ループイテレーションでPrepareハンドルの直前に呼び出される。アクティブなIdleハンドルが存在する場合、I/Oポーリングのタイムアウトが0に設定される。

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

本ページは静的ドキュメント表示のため、データベース操作は存在しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | 静的HTMLドキュメントのためDB操作なし |

### テーブル別更新項目詳細

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | uv_idle_start()にcb=NULLを渡した場合 | UV_EINVAL返却（ドキュメント記載の仕様） |

## 例外処理

- ページが見つからない場合：Webサーバーの404エラーが表示される
- Sphinxビルドエラー：rstファイルの構文エラー時にビルド時エラーとして検出される

## 備考

- Idleハンドルは、Prepareハンドル・Checkハンドルと同じ「ループウォッチャー」カテゴリに属し、実装上は `UV_LOOP_WATCHER_DEFINE` マクロで共通的に生成される
- 重要な動作特性：アクティブなIdleハンドルが存在する場合、ループはI/Oブロッキングを行わない（ゼロタイムアウトポーリング）
- `uv_handle_t` の共通メンバーおよびAPI関数がそのまま適用される

---

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

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

### 推奨読解順序

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

まず、`uv_idle_t` の型定義とコールバック型を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | 945-952行目: `uv_idle_s` 構造体定義と `uv_idle_init`/`uv_idle_start`/`uv_idle_stop` の関数宣言 |
| 1-2 | idle.rst | `docs/src/idle.rst` | 1-63行目: ドキュメント全体構成・note/warningの記載内容 |

**読解のコツ**: `uv_idle_s` 構造体は `UV_HANDLE_FIELDS` と `UV_IDLE_PRIVATE_FIELDS` マクロで展開される。Idleハンドルがゼロタイムアウトポーリングを引き起こす仕組みは、イベントループのタイムアウト計算ロジックに実装されている。

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

ループウォッチャー共通実装マクロによりAPI関数が生成される仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | loop-watcher.c | `src/unix/loop-watcher.c` | 25-68行目: `UV_LOOP_WATCHER_DEFINE` マクロによる init/start/stop/run/close 関数の一括生成 |

**主要処理フロー**:
1. **68行目**: `UV_LOOP_WATCHER_DEFINE(idle, IDLE)` によりidle用関数群が展開される
2. **26-30行目**: `uv_idle_init` - `uv__handle_init` で初期化しコールバックをNULLに設定
3. **32-39行目**: `uv_idle_start` - アクティブ判定後、ループのidle_handlesキューに挿入
4. **41-46行目**: `uv_idle_stop` - キューから削除しハンドルを停止

#### Step 3: ゼロタイムアウトポーリングの仕組みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | `uv__run_idle` の呼び出し箇所とタイムアウト計算ロジックでアクティブなidle_handlesが存在する場合にタイムアウト=0となる処理を確認 |

**主要処理フロー**:
- **48-60行目（マクロ展開）**: `uv__run_idle` - キュー内の全idleハンドルのコールバックを順番に実行

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

```
uv_run() [src/unix/core.c]
    |
    +-- uv__run_idle() [src/unix/loop-watcher.c (マクロ展開)]
    |      |
    |      +-- handle->idle_cb(handle) [ユーザー定義コールバック]
    |
    +-- uv__backend_timeout() [タイムアウト計算]
           |
           +-- idle_handles が空でない場合 → timeout = 0

uv_idle_init() [src/unix/loop-watcher.c (マクロ展開)]
    |
    +-- uv__handle_init() [内部初期化]

uv_idle_start() [src/unix/loop-watcher.c (マクロ展開)]
    |
    +-- uv__queue_insert_head() [キュー操作]
    +-- uv__handle_start() [ハンドル開始]

uv_idle_stop() [src/unix/loop-watcher.c (マクロ展開)]
    |
    +-- uv__queue_remove() [キュー操作]
    +-- uv__handle_stop() [ハンドル停止]
```

### データフロー図

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

uv_idle_init(loop,        uv__handle_init()              初期化済み
 handle)            --->  コールバック=NULL設定      ---> uv_idle_tハンドル

uv_idle_start(handle,     キューへ挿入                   アクティブな
 cb)                --->  コールバック設定            ---> idleハンドル
                          (ゼロタイムアウトに影響)

各ループイテレーション --> uv__run_idle()            ---> コールバック実行
                          キュー走査・コールバック呼出

uv_idle_stop(handle)  --> キューから削除             ---> 非アクティブ状態
                          (タイムアウト通常化に影響)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| idle.rst | `docs/src/idle.rst` | テンプレート | Idleハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_idle_t構造体・API関数宣言（945-952行目） |
| loop-watcher.c | `src/unix/loop-watcher.c` | ソース | Unix用idle init/start/stop/run/close実装（マクロ展開） |
| loop-watcher.c | `src/win/loop-watcher.c` | ソース | Windows用idle実装 |
| core.c | `src/unix/core.c` | ソース | イベントループメインロジック（uv__run_idle呼び出し箇所・タイムアウト計算） |
| handle.c | `src/win/handle.c` | ソース | Windows用ハンドル共通処理（uv_idle_stop呼び出し: 118行目） |
