# 画面設計書 14-Pollハンドル

## 概要

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

### 本画面の処理概要

Pollハンドルは、ファイルディスクリプタの読み取り可能・書き込み可能・切断状態を `poll(2)` に類似した方法で監視するために使用される。本ページでは、Pollハンドルの初期化・監視開始・停止に関するAPIおよびイベント型を詳細に解説する。

**業務上の目的・背景**：Pollハンドルの主な目的は、外部ライブラリ（c-aresやlibssh2など）をlibuvのイベントループに統合することである。これらの外部ライブラリはソケット状態変更の通知をイベントループに委任する設計であり、Pollハンドルがその橋渡しを行う。ただし、TCP/UDP等のlibuv自身が提供するハンドルの代替として使用することは推奨されない（より高速でスケーラブルな実装が用意されているため）。本ページは、外部ライブラリ統合の開発者がPollハンドルの動作特性（レベルトリガー動作、プラットフォーム差異）を正確に理解するための公式リファレンスである。

**画面へのアクセス方法**：トップページ → APIドキュメント一覧（api.rst） → Pollハンドル（poll.rst）の順にナビゲーションリンクを辿ってアクセスする。

**主要な操作・処理内容**：
1. `uv_poll_t` 型・`uv_poll_cb` コールバック型・`uv_poll_event` 列挙型の定義を閲覧する
2. `uv_poll_init()` / `uv_poll_init_socket()` による初期化APIの仕様を確認する
3. `uv_poll_start()` によるイベント監視開始の仕様（ビットマスク指定、レベルトリガー動作）を確認する
4. `uv_poll_stop()` による監視停止の仕様を確認する
5. プラットフォーム固有の注意事項（Windows: ソケットのみ、AIX: DISCONNECT非対応）を確認する
6. 基底ハンドル（`uv_handle_t`）の共通API関数へのリンクを辿る

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底ページ（handle.rst）、エラーコードページ（errors.rst）への参照リンク
- 関連ページ：TCPページ（tcp.rst）、UDPページ（udp.rst）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 77 | Pollハンドル初期化 | 主機能 | uv_poll_init()/uv_poll_init_socket()によるPollハンドル初期化のAPI定義 |
| 78 | Pollイベント監視開始・停止 | 主機能 | uv_poll_start()/uv_poll_stop()によるFDイベント監視のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_poll_t` --- Poll handle | ページタイトル |
| 概要説明 | Poll handles are used to watch file descriptors... | Pollハンドルの動作概要と使用上の注意 |
| 注意事項 | 外部ライブラリ統合用途の説明 | uv_tcp_t等との性能差異 |
| 注意事項 | EAGAIN対応の必要性 | 偽のreadable/writableシグナルの可能性 |
| 注意事項 | 同一ソケットに複数Pollハンドル禁止 | busyloop防止 |
| 注意事項 | アクティブなPollハンドル中のFDクローズ禁止 | uv_poll_stop/uv_close後にクローズ可 |
| Note | Windows: ソケットのみ対応 | プラットフォーム制限 |
| Note | AIX: disconnection非対応 | プラットフォーム制限 |
| Data types | `uv_poll_t`, `uv_poll_cb`, `uv_poll_event` | 型定義・列挙型 |
| uv_poll_event | UV_READABLE=1, UV_WRITABLE=2, UV_DISCONNECT=4, UV_PRIORITIZED=8 | イベントビットマスク |
| API - uv_poll_init | FDによる初期化 | v1.2.2でnon-blockingモード設定追加 |
| API - uv_poll_init_socket | ソケットによる初期化 | Windowsでは必須 |
| API - uv_poll_start | 監視開始 | ビットマスク指定、レベルトリガー動作 |
| API - uv_poll_stop | 監視停止 | 即時有効、保留コールバックもキャンセル |
| See also | uv_handle_t API functions | 基底ハンドルAPIへの参照 |

## イベント仕様

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

SphinxのreStructuredTextのcross-referenceにより、`:c:type:`uv_handle_t``、`:c:type:`uv_tcp_t``、`:c:type:`uv_udp_t``、`:ref:`errors`` へのリンクで各ページに遷移する。

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

ドキュメントに記載されるランタイム動作として、`uv_poll_start()` で監視登録したイベント（READABLE/WRITABLE/DISCONNECT/PRIORITIZED）が検出されると、コールバックが `status=0` で呼び出される。エラー時は `status < 0` で呼び出される。`status == UV_EBADF` の場合、ポーリングが中断される。レベルトリガー方式のため、読み書き可能な状態が続く限りコールバックが繰り返し呼ばれる。

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

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

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

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

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

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | ポーリング中にエラー発生 | コールバックのstatus < 0（UV_E*エラーコード） |
| エラー | UV_EBADF | ポーリング中断、uv_closeが必要 |

## 例外処理

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

## 備考

- UV_DISCONNECTイベントはv1.9.0で追加
- UV_PRIORITIZEDイベントはv1.14.0で追加
- v1.2.2以降、初期化時にFDが自動的にnon-blockingモードに設定される
- 既にアクティブなPollハンドルに対する `uv_poll_start()` 再呼び出しは問題なく、イベントマスクの更新として動作する
- `uv_handle_t` の共通メンバーおよびAPI関数がそのまま適用される

---

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

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

### 推奨読解順序

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

まず、`uv_poll_t` の型定義、コールバック型、イベント列挙型を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_poll_t` 構造体定義、`uv_poll_cb` コールバック型、`uv_poll_event` 列挙型の宣言箇所 |
| 1-2 | poll.rst | `docs/src/poll.rst` | 1-151行目: ドキュメント全体構成・注意事項・型定義・API仕様 |

**読解のコツ**: `uv_poll_event` の各値（UV_READABLE=1, UV_WRITABLE=2, UV_DISCONNECT=4, UV_PRIORITIZED=8）はビットマスクとして組み合わせて使用される。

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

Unix用のPoll実装を中心に、初期化と監視の仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | poll.c | `src/unix/poll.c` | 67-93行目: `uv_poll_init` - FD存在チェック、non-blocking設定、I/Oウォッチャー初期化 |
| 2-2 | poll.c | `src/unix/poll.c` | 96-99行目: `uv_poll_init_socket` - Unixではuv_poll_initと同一 |

**主要処理フロー**:
1. **67行目**: `uv_poll_init` - `uv__fd_exists` で既存FDチェック
2. **73行目**: `uv__io_check_fd` でFDの有効性確認
3. **80行目**: `uv__nonblock` でnon-blockingモード設定
4. **89行目**: `uv__handle_init` と `uv__io_init` でハンドルとI/Oウォッチャーを初期化

#### Step 3: イベント監視の開始・停止を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | poll.c | `src/unix/poll.c` | 118-154行目: `uv_poll_start` - イベントマスク変換、I/O開始、コールバック設定 |
| 3-2 | poll.c | `src/unix/poll.c` | 111-115行目: `uv_poll_stop` - I/O停止とハンドル停止 |

**主要処理フロー**:
- **134行目**: 既存のポーリングを一旦停止（`uv__poll_stop`）
- **139-147行目**: UV_*イベントをPOLL*イベントに変換
- **149行目**: `uv__io_start` でI/Oウォッチャーを開始

#### Step 4: I/Oコールバック処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | poll.c | `src/unix/poll.c` | 29-64行目: `uv__poll_io` - POLL*イベントからUV_*イベントへの変換、コールバック実行 |

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

```
uv_poll_init(loop, handle, fd) [src/unix/poll.c:67]
    |
    +-- uv__fd_exists() [FD存在チェック]
    +-- uv__io_check_fd() [FD有効性確認]
    +-- uv__nonblock() [non-blocking設定]
    +-- uv__handle_init() [ハンドル初期化]
    +-- uv__io_init() [I/Oウォッチャー初期化]

uv_poll_start(handle, events, cb) [src/unix/poll.c:118]
    |
    +-- uv__poll_stop() [既存ポーリング停止]
    +-- イベントマスク変換（UV_* → POLL*）
    +-- uv__io_start() [I/Oウォッチャー開始]
    +-- uv__handle_start() [ハンドル開始]

uv__poll_io(loop, w, events) [src/unix/poll.c:29]
    |
    +-- イベントマスク変換（POLL* → UV_*）
    +-- handle->poll_cb(handle, status, events) [ユーザーコールバック]

uv_poll_stop(handle) [src/unix/poll.c:111]
    |
    +-- uv__poll_stop() [src/unix/poll.c:102]
           +-- uv__io_stop() [I/O停止]
           +-- uv__handle_stop() [ハンドル停止]
           +-- uv__platform_invalidate_fd() [FD無効化]
```

### データフロー図

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

uv_poll_init(fd)       ---> FDチェック・non-blocking設定 ---> 初期化済みpollハンドル

uv_poll_start(events)  ---> UV_*→POLL*変換             ---> I/O監視開始
                            I/Oウォッチャー登録

I/Oポーリング検出      ---> uv__poll_io()               ---> ユーザーコールバック
                            POLL*→UV_*変換                   (status, events)

uv_poll_stop()         ---> I/O停止・FD無効化           ---> 監視停止
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| poll.rst | `docs/src/poll.rst` | テンプレート | Pollハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_poll_t構造体・uv_poll_event列挙型・API関数宣言 |
| poll.c | `src/unix/poll.c` | ソース | Unix用poll init/start/stop/io/close実装 |
| poll.c | `src/win/poll.c` | ソース | Windows用poll実装（ソケット専用） |
| core.c | `src/unix/core.c` | ソース | イベントループメインロジック |
