# 画面設計書 7-ハンドル基底

## 概要

uv_handle_tの基底APIリファレンスページ（handle.rst）に関する画面設計書。全ハンドル型に共通する操作（クローズ、参照カウント、アクティブ判定、バッファサイズ制御等）のAPI定義を提供する。

### 本画面の処理概要

本画面はlibuvの全ハンドル型の基底となる `uv_handle_t` のAPIリファレンスページである。TCP、パイプ、タイマー等のあらゆるハンドルに共通する操作を定義し、ハンドルのライフサイクル管理の基本を提供する。

**業務上の目的・背景**：libuvのハンドルは全て `uv_handle_t` を基底型として共有する。クローズ処理、参照カウント、アクティブ状態判定、ユーザーデータ管理等の共通操作はこの基底型のAPIとして定義される。開発者はこのページを通じてハンドルの共通的な操作方法を理解し、メモリリークやリソースリークを防ぐための正しいライフサイクル管理を習得する。

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

**主要な操作・処理内容**：
1. データ型定義の参照 - uv_handle_t, uv_handle_type, uv_any_handle, uv_alloc_cb, uv_close_cb
2. ハンドルクローズAPI参照 - uv_close()の使い方とメモリ解放タイミング
3. 参照カウントAPI参照 - uv_ref()/uv_unref()/uv_has_ref()
4. 状態判定API参照 - uv_is_active()/uv_is_closing()
5. バッファサイズAPI参照 - uv_send_buffer_size()/uv_recv_buffer_size()
6. ファイルディスクリプタAPI参照 - uv_fileno()
7. 型情報API参照 - uv_handle_get_type()/uv_handle_type_name()/uv_handle_size()
8. データアクセサAPI参照 - uv_handle_get_data()/uv_handle_set_data()

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：Sphinx相互参照を通じてloop.rst, timer.rst, tcp.rst等の関連APIページ

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | ハンドル参照カウント制御 | 主機能 | uv_ref()/uv_unref()/uv_has_ref()による参照カウント制御のAPI定義 |
| 15 | ハンドルクローズ | 主機能 | uv_close()によるハンドルクローズ・リソース解放のAPI定義 |
| 16 | ハンドルアクティブ判定 | 主機能 | uv_is_active()によるハンドルアクティブ状態判定のAPI定義 |
| 17 | ハンドルクローズ中判定 | 主機能 | uv_is_closing()によるクローズ処理中判定のAPI定義 |
| 19 | バッファサイズ制御 | 主機能 | uv_send_buffer_size()/uv_recv_buffer_size()による送受信バッファ制御のAPI定義 |
| 20 | ファイルディスクリプタ取得 | 主機能 | uv_fileno()によるOSファイルディスクリプタ取得のAPI定義 |
| 21 | ハンドルサイズ取得 | 主機能 | uv_handle_size()によるハンドル型メモリサイズ取得のAPI定義 |
| 22 | ハンドル型情報取得 | 主機能 | uv_handle_get_type()/uv_handle_type_name()による型情報取得のAPI定義 |
| 23 | ハンドルデータ取得・設定 | 主機能 | uv_handle_get_data()/uv_handle_set_data()によるユーザーデータ関連付けのAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "uv_handle_t --- Base handle" |
| データ型定義 | 出力 | 型定義 | uv_handle_t, uv_handle_type, uv_any_handle, コールバック型2種 |
| パブリックメンバ | 出力 | メンバ定義 | loop, type, data の3メンバ |
| API関数定義 | 出力 | 関数シグネチャ+説明 | 15個以上のAPI関数 |
| 参照カウント解説 | 出力 | テキスト | Reference counting セクションの説明 |

## 表示項目

### Data types セクション

| データ型 | 説明 |
|----------|------|
| uv_handle_t | 基底ハンドル型。全ハンドルはこの型にキャスト可能 |
| uv_handle_type | ハンドル種別列挙型（UV_ASYNC, UV_CHECK, UV_TIMER等17種） |
| uv_any_handle | 全ハンドル型のユニオン |
| uv_alloc_cb | バッファ割り当てコールバック型（suggested_size=65536） |
| uv_close_cb | クローズコールバック型 |

### Public members セクション

| メンバ | 型 | 説明 |
|--------|-----|------|
| uv_handle_t.loop | uv_loop_t* | ハンドルが動作するループへのポインタ（読み取り専用） |
| uv_handle_t.type | uv_handle_type | ハンドル型（読み取り専用） |
| uv_handle_t.data | void* | ユーザー定義データ |

### API セクション

| API関数 | シグネチャ | 説明 |
|---------|-----------|------|
| uv_is_active | `int uv_is_active(const uv_handle_t* handle)` | ハンドルがアクティブかを判定 |
| uv_is_closing | `int uv_is_closing(const uv_handle_t* handle)` | クローズ中/クローズ済みかを判定 |
| uv_close | `void uv_close(uv_handle_t* handle, uv_close_cb close_cb)` | ハンドルクローズ要求。メモリはclose_cb内で解放 |
| uv_ref | `void uv_ref(uv_handle_t* handle)` | 参照追加（冪等） |
| uv_unref | `void uv_unref(uv_handle_t* handle)` | 参照解除（冪等） |
| uv_has_ref | `int uv_has_ref(const uv_handle_t* handle)` | 参照状態確認 |
| uv_handle_size | `size_t uv_handle_size(uv_handle_type type)` | ハンドルサイズ取得（FFI用） |
| uv_send_buffer_size | `int uv_send_buffer_size(uv_handle_t* handle, int* value)` | 送信バッファサイズ取得/設定 |
| uv_recv_buffer_size | `int uv_recv_buffer_size(uv_handle_t* handle, int* value)` | 受信バッファサイズ取得/設定 |
| uv_fileno | `int uv_fileno(const uv_handle_t* handle, uv_os_fd_t* fd)` | OSファイルディスクリプタ取得 |
| uv_handle_get_loop | `uv_loop_t* uv_handle_get_loop(const uv_handle_t* handle)` | handle->loop取得（v1.19.0） |
| uv_handle_get_data | `void* uv_handle_get_data(const uv_handle_t* handle)` | handle->data取得（v1.19.0） |
| uv_handle_set_data | `void uv_handle_set_data(uv_handle_t* handle, void* data)` | handle->data設定（v1.19.0） |
| uv_handle_get_type | `uv_handle_type uv_handle_get_type(const uv_handle_t* handle)` | handle->type取得（v1.19.0） |
| uv_handle_type_name | `const char* uv_handle_type_name(uv_handle_type type)` | 型名文字列取得（v1.19.0） |

## イベント仕様

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

`:c:func:` や `:c:type:` 参照リンクを押下すると、対応するAPIリファレンスページへ遷移する。

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- uv_close()は全ハンドルに対してメモリ解放前に必ず呼ぶ必要がある（最重要API）
- 参照カウントはカウンタではなくフラグベース（ref/unrefは冪等操作）
- uv_alloc_cbのsuggested_sizeは65536だが、ユーザーは任意のサイズを割り当て可能
- uv_fileno()はTCP、パイプ、TTY、UDP、Pollハンドルでのみサポート
- Linuxでは送受信バッファサイズは設定値の2倍が設定・返却される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_handle_type列挙型定義、uv_alloc_cb/uv_close_cb型定義 |
| 1-2 | handle.rst | `docs/src/handle.rst` | 全APIのドキュメント定義 |

**読解のコツ**: `uv_handle_type` 列挙型の各値（UV_ASYNC, UV_CHECK等）がそれぞれのハンドル型構造体に対応していることを理解する。UV_HANDLE_TYPE_MAPマクロで全型を列挙できる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.c | `src/unix/core.c` | uv_close()（159行目）- ハンドル型別のクローズ処理分岐 |
| 2-2 | core.c | `src/unix/core.c` | uv_is_closing()（383行目）, uv_backend_fd()（388行目） |

**主要処理フロー**:
1. **core.c 159行目**: `uv_close()` - UV_HANDLE_CLOSINGフラグ設定
2. **core.c 162行目**: `handle->close_cb = close_cb` - コールバック保存
3. **core.c 165-235行目**: switch-caseで型別クローズ関数を呼び出し
4. **core.c 237行目**: `uv__make_close_pending()` - クローズ待ちリストへ追加

#### Step 3: 共通ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-common.c | `src/uv-common.c` | uv_handle_size()（166行目）- UV_HANDLE_TYPE_MAPマクロ展開 |

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

```
uv_close(handle, close_cb) [src/unix/core.c:159]
    |
    +-- handle->flags |= UV_HANDLE_CLOSING
    +-- handle->close_cb = close_cb
    +-- switch(handle->type)
    |       +-- UV_TIMER: uv__timer_close()
    |       +-- UV_TCP:   uv__tcp_close()
    |       +-- UV_PREPARE: uv__prepare_close()
    |       +-- ... (全ハンドル型)
    |
    +-- uv__make_close_pending(handle) [core.c:268]
            +-- handle->next_closing = loop->closing_handles
            +-- loop->closing_handles = handle
```

### データフロー図

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

uv_handle_t* handle  --> uv_close()                --> クローズ待ちキューに追加
                          (型別クローズ+フラグ設定)

uv_handle_t* handle  --> uv_is_active()            --> int (0 or 非0)
                          (フラグ確認)

uv_handle_type type  --> uv_handle_size()           --> size_t (構造体サイズ)
                          (UV_HANDLE_TYPE_MAP展開)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| handle.rst | `docs/src/handle.rst` | テンプレート | ハンドル基底ページのRSTソース |
| uv.h | `include/uv.h` | ソース | uv_handle_t, uv_handle_type等のパブリック型定義 |
| core.c | `src/unix/core.c` | ソース | uv_close(), uv_is_closing()等のUnix実装 |
| uv-common.c | `src/uv-common.c` | ソース | uv_handle_size()等のクロスプラットフォーム実装 |
| handle.c | `src/win/handle.c` | ソース | Windows固有のハンドル操作実装 |
