# 画面設計書 11-Checkハンドル

## 概要

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

### 本画面の処理概要

Checkハンドルは、イベントループの各イテレーションにおいてI/Oポーリング完了直後に指定コールバックを実行するためのハンドルである。本ページでは、Checkハンドルの初期化・開始・停止に関するAPIを詳細に解説する。

**業務上の目的・背景**：Checkハンドルは、I/Oポーリング後に必ず実行される処理を登録するために使用される。Prepareハンドル（I/Oポーリング前）と対をなすもので、I/Oイベント処理後のポスト処理やフレームワーク内部のタスクスケジューリングに利用される。Node.jsの `setImmediate` の実装基盤としても使われている。本ページは、libuvを利用する開発者がCheckハンドルのAPIを正確に把握し、適切にコールバックを登録・解除するための公式リファレンスである。

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

**主要な操作・処理内容**：
1. `uv_check_t` 型の説明とコールバック型 `uv_check_cb` の定義を閲覧する
2. `uv_check_init()` による初期化APIの仕様を確認する
3. `uv_check_start()` によるコールバック登録と開始の仕様を確認する
4. `uv_check_stop()` によるコールバック停止の仕様を確認する
5. 基底ハンドル（`uv_handle_t`）の共通API関数へのリンクを辿る

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 86 | Check初期化・開始・停止 | 主機能 | uv_check_init()/uv_check_start()/uv_check_stop()のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_check_t` --- Check handle | ページタイトル |
| 概要説明 | Check handles will run the given callback... | Checkハンドルの動作概要 |
| Data types | `uv_check_t`, `uv_check_cb` | 型定義 |
| Public members | N/A | 固有のパブリックメンバーはなし |
| API - uv_check_init | 初期化関数の仕様 | 常に成功し0を返す |
| API - uv_check_start | 開始関数の仕様 | cbがNULLの場合UV_EINVALを返す |
| API - uv_check_stop | 停止関数の仕様 | 常に成功し0を返す |
| See also | uv_handle_t API functions | 基底ハンドルAPIへの参照 |

## イベント仕様

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

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

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

ドキュメントに記載されるランタイム動作として、`uv_check_start()` で登録したコールバックは、イベントループの各イテレーションにおいてI/Oポーリング完了直後に呼び出される。

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

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

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

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

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

該当なし

## メッセージ仕様

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

## 例外処理

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

## 備考

- Checkハンドルは、Prepareハンドル・Idleハンドルと同じ「ループウォッチャー」カテゴリに属し、実装上は `UV_LOOP_WATCHER_DEFINE` マクロで共通的に生成される
- `uv_handle_t` の共通メンバーおよびAPI関数がそのまま適用される

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | 935-942行目: `uv_check_s` 構造体定義と `uv_check_init`/`uv_check_start`/`uv_check_stop` の関数宣言 |
| 1-2 | check.rst | `docs/src/check.rst` | 1-55行目: ドキュメント全体構成・型定義・API仕様の記載内容 |

**読解のコツ**: `uv_check_s` 構造体は `UV_HANDLE_FIELDS` と `UV_CHECK_PRIVATE_FIELDS` マクロで展開される。プライベートフィールドはプラットフォーム別ヘッダで定義されている。

#### 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. **67行目**: `UV_LOOP_WATCHER_DEFINE(check, CHECK)` によりcheck用関数群が展開される
2. **26-30行目**: `uv_check_init` - `uv__handle_init` で初期化しコールバックをNULLに設定
3. **32-39行目**: `uv_check_start` - アクティブ判定後、ループのcheck_handlesキューに挿入
4. **41-46行目**: `uv_check_stop` - キューから削除しハンドルを停止

#### Step 3: イベントループでの実行タイミングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | `uv__run_check` の呼び出し箇所を確認し、I/Oポーリング後に実行されることを把握 |

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

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

```
uv_run() [src/unix/core.c]
    |
    +-- uv__run_check() [src/unix/loop-watcher.c (マクロ展開)]
           |
           +-- handle->check_cb(handle) [ユーザー定義コールバック]

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

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

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

### データフロー図

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

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

uv_check_start(handle,    キューへ挿入                   アクティブな
 cb)                --->  コールバック設定            ---> checkハンドル

I/Oポーリング完了   --->  uv__run_check()           ---> コールバック実行
                          キュー走査・コールバック呼出

uv_check_stop(handle) --> キューから削除             ---> 非アクティブ状態
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check.rst | `docs/src/check.rst` | テンプレート | Checkハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_check_t構造体・API関数宣言（935-942行目） |
| loop-watcher.c | `src/unix/loop-watcher.c` | ソース | Unix用check init/start/stop/run/close実装（マクロ展開） |
| loop-watcher.c | `src/win/loop-watcher.c` | ソース | Windows用check実装 |
| core.c | `src/unix/core.c` | ソース | イベントループメインロジック（uv__run_check呼び出し箇所） |
| handle.c | `src/win/handle.c` | ソース | Windows用ハンドル共通処理（uv_check_stop呼び出し: 112行目） |
