# 機能設計書 21-ハンドルサイズ取得

## 概要

本ドキュメントは、libuv の `uv_handle_size()` 関数によるハンドル型ごとのメモリサイズ取得機能の設計を記述する。

### 本機能の処理概要

本機能は、指定されたハンドル型（`uv_handle_type`）に対応する構造体のメモリサイズをバイト単位で返却する。これにより、動的なメモリ確保を行う際に必要なサイズを事前に知ることができる。

**業務上の目的・背景**：libuvを利用するアプリケーションが、ハンドル構造体を動的にメモリ確保する必要がある場合（カスタムアロケータ使用時やバインディング言語でのメモリ管理時など）、各ハンドル型の正確なメモリサイズを知る必要がある。コンパイル時に`sizeof()`を使えない言語バインディング（FFI等）において特に重要な機能である。

**機能の利用シーン**：他言語バインディング（Node.js、Python、Rustなど）からlibuvを利用する際に、ハンドル構造体を確保するためのメモリサイズを動的に取得するシーン。また、カスタムメモリプールを実装する際にも使用される。

**主要な処理内容**：
1. 引数として渡された`uv_handle_type`列挙値をswitch文で分岐
2. `UV_HANDLE_TYPE_MAP`マクロにより各ハンドル型に対応する`sizeof(uv_XXX_t)`を返却
3. 未知の型が渡された場合は`(size_t)-1`を返却

**関連システム・外部連携**：特になし。ライブラリ内部で完結する純粋な情報取得関数である。

**権限による制御**：なし。任意のスレッドから呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | ハンドル基底 | 主画面 | uv_handle_size()によるハンドル型メモリサイズ取得のAPI定義 |

## 機能種別

情報取得処理（ハンドル型に応じたメモリサイズの返却）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | uv_handle_type | Yes | サイズを取得したいハンドルの型 | UV_HANDLE_TYPE_MAP に定義された型であること |

### 入力データソース

呼び出し元から直接引数として渡される。`uv_handle_type`列挙型の値で、以下の型が有効：ASYNC, CHECK, FS_EVENT, FS_POLL, HANDLE, IDLE, NAMED_PIPE, POLL, PREPARE, PROCESS, STREAM, TCP, TIMER, TTY, UDP, SIGNAL

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | size_t | 指定されたハンドル型に対応する構造体のバイトサイズ。不正な型の場合は`(size_t)-1` |

### 出力先

関数の戻り値として呼び出し元に返却される。

## 処理フロー

### 処理シーケンス

```
1. uv_handle_size(type) 呼び出し
   └─ 引数 type を受け取る
2. switch文による型の判定
   └─ UV_HANDLE_TYPE_MAP(XX) マクロが展開され、各case文が生成される
3. 該当する型の場合
   └─ sizeof(uv_XXX_t) を返却
4. 該当しない型の場合（default）
   └─ (size_t)-1 を返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_handle_size 呼び出し] --> B{type の判定}
    B -->|UV_ASYNC| C1["return sizeof(uv_async_t)"]
    B -->|UV_CHECK| C2["return sizeof(uv_check_t)"]
    B -->|UV_TCP| C3["return sizeof(uv_tcp_t)"]
    B -->|...その他| C4["return sizeof(uv_xxx_t)"]
    B -->|default| D["return (size_t)-1"]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-21-01 | マクロ展開による網羅性保証 | UV_HANDLE_TYPE_MAPマクロにより、すべてのハンドル型が自動的にカバーされる | 常時 |
| BR-21-02 | 不正型のエラー返却 | 未知のハンドル型に対しては(size_t)-1を返す | switch文のdefaultに到達した場合 |

### 計算ロジック

各ハンドル型に対する`sizeof()`演算子の結果をそのまま返す。マクロ`XX(uc, lc)`は`case UV_##uc: return sizeof(uv_##lc##_t);`に展開される。

## データベース操作仕様

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

データベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| (size_t)-1 | 不正引数 | 未定義のuv_handle_type値が渡された場合 | 呼び出し元で戻り値を確認し、不正値の場合はエラー処理を行う |

### リトライ仕様

リトライは不要。純粋な情報取得関数であり、同じ入力に対して常に同じ結果を返す。

## トランザクション仕様

トランザクションは存在しない。

## パフォーマンス要件

O(1)の定数時間で処理が完了する。switch文による分岐のみであり、メモリ確保や I/O 操作は一切行わない。

## セキュリティ考慮事項

特になし。読み取り専用の情報取得関数であり、副作用を持たない。

## 備考

- `uv_handle_size()`と対になる`uv_req_size()`が存在し、リクエスト型のサイズ取得に使用される（No.27参照）。
- `uv_loop_size()`も同じファイルで定義されており、ループ構造体のサイズを返す。
- コンパイル時の`sizeof()`が使えない環境（FFI、動的ローディング等）で特に有用。

---

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

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

### 推奨読解順序

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

まず、`uv_handle_type`列挙型と`UV_HANDLE_TYPE_MAP`マクロの定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_handle_type列挙型の定義（L198-205）とUV_HANDLE_TYPE_MAP マクロの定義（L161-177） |

**読解のコツ**: `UV_HANDLE_TYPE_MAP(XX)`はX-Macroパターンで、`XX`マクロを各ハンドル型に適用する。このパターンにより、新しいハンドル型が追加された際に一箇所の変更で全関連箇所が更新される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | uv_handle_size()の関数宣言（L483） |
| 2-2 | uv-common.c | `src/uv-common.c` | uv_handle_size()の実装（L164-172） |

**主要処理フロー**:
1. **164行目**: `XX`マクロを`case UV_##uc: return sizeof(uv_##lc##_t);`として定義
2. **166-172行目**: `uv_handle_size()`関数本体。switch文で`UV_HANDLE_TYPE_MAP(XX)`を展開し、各型のサイズを返却
3. **170行目**: default節で`(size_t)-1`を返却（不正な型の場合）

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

```
uv_handle_size(type)
    │
    └─ switch(type)
           ├─ case UV_ASYNC:  return sizeof(uv_async_t)
           ├─ case UV_CHECK:  return sizeof(uv_check_t)
           ├─ case UV_FS_EVENT: return sizeof(uv_fs_event_t)
           ├─ ... (UV_HANDLE_TYPE_MAP による展開)
           └─ default: return (size_t)-1
```

### データフロー図

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

uv_handle_type ───▶ switch分岐 ───▶ size_t (構造体サイズ)
  (列挙値)           (マクロ展開)      またはエラー値(-1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_handle_type列挙型・UV_HANDLE_TYPE_MAPマクロ・関数宣言 |
| uv-common.c | `src/uv-common.c` | ソース | uv_handle_size()の実装 |
