# 機能設計書 68-パイプ保留ハンドル情報取得

## 概要

本ドキュメントは、IPCパイプで受信待ちのハンドル数と型を取得する機能（`uv_pipe_pending_count()`/`uv_pipe_pending_type()`）の設計を記述する。

### 本機能の処理概要

IPCパイプ経由で受信した保留中のハンドル（ファイルディスクリプタ/ソケット）の数と型を取得する。これによりuv_accept()で受け取るべきハンドルの種類を事前に判定できる。

**業務上の目的・背景**：IPC通信でプロセス間のハンドル受け渡しを行う際、受信側はどのようなハンドルが届いているかを事前に確認する必要がある。pending_countで保留数を確認し、pending_typeでハンドル型を特定した上でuv_accept()を呼び出す。

**機能の利用シーン**：マルチプロセスサーバーでの負荷分散（マスターからワーカーへのソケット受け渡し）、プロセス間でのファイルディスクリプタ共有など、IPC通信でハンドルを受け渡す場面で使用される。

**主要な処理内容**：
1. uv_pipe_pending_count(): IPCパイプの保留ハンドル数を返す
2. uv_pipe_pending_type(): 次に受信するハンドルの型を返す

**関連システム・外部連携**：Unix sendmsg()/recvmsg()のSCM_RIGHTS機能、Windows Named Pipe IPCプロトコル。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | パイプ | 主機能 | uv_pipe_pending_count()/uv_pipe_pending_type()による保留ハンドル情報取得のAPI定義 |

## 機能種別

情報取得（IPC受信ハンドル状態の照会）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_pipe_t* | Yes | IPCパイプハンドル | ipc非0で初期化されていること |

### 入力データソース

パイプハンドルの内部状態（accepted_fd、queued_fds等）。

## 出力仕様

### 出力データ

#### uv_pipe_pending_count()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 保留中のハンドル数。IPC無効の場合は0 |

#### uv_pipe_pending_type()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uv_handle_type | 次のハンドルの型（UV_TCP等）。IPC無効または保留なしの場合はUV_UNKNOWN_HANDLE |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
[pending_count]
1. IPCモードチェック
   └─ handle->ipc が0なら0を返す
2. accepted_fdチェック
   └─ accepted_fd == -1 なら0を返す
3. キューされたFDの確認
   └─ Unix: queued_fds が NULL なら1、それ以外は queued_fds->offset + 1
   └─ Windows: ipc_xfer_queue_length を返す

[pending_type]
1. IPCモードチェック
   └─ handle->ipc が0ならUV_UNKNOWN_HANDLEを返す
2. 保留ハンドル確認
   └─ Unix: accepted_fd == -1 ならUV_UNKNOWN_HANDLE、それ以外はuv_guess_handle(accepted_fd)
   └─ Windows: ipc_xfer_queue_length == 0 ならUV_UNKNOWN_HANDLE、それ以外はUV_TCP
```

### フローチャート

```mermaid
flowchart TD
    A[uv_pipe_pending_count] --> B{handle->ipc?}
    B -->|0| C[return 0]
    B -->|非0| D{accepted_fd == -1?}
    D -->|Yes| C
    D -->|No| E{queued_fds == NULL?}
    E -->|Yes| F[return 1]
    E -->|No| G[return queued_fds->offset + 1]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | IPC必須 | ipcフラグが0のパイプでは常に0/UV_UNKNOWN_HANDLEを返す | 常に適用 |
| BR-02 | Unix型推定 | Unix版のpending_type()はuv_guess_handle()でFDからハンドル型を推定する | Unix環境 |
| BR-03 | Windows固定型 | Windows版のpending_type()は常にUV_TCPを返す（IPCでのハンドル受け渡しはTCPのみ） | Windows環境 |

### 計算ロジック

pending_count (Unix): `queued_fds->offset + 1`（accepted_fd分の+1）

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

該当なし。

## エラー処理

### エラーケース一覧

本関数にはエラーコードは定義されていない。IPC無効や保留なしの場合は0/UV_UNKNOWN_HANDLEを返す。

### リトライ仕様

リトライ不要。

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

該当なし。

## パフォーマンス要件

フィールド参照のみでO(1)。

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

特になし。

## 備考

- uv_pipe_pending_count()で保留数を確認し、uv_pipe_pending_type()で型を確認してからuv_accept()でハンドルを受け取るのが標準的な使用パターン
- Unix版ではuv_guess_handle()を使用するため、TCPソケット以外（UDP等）のハンドルも受け渡し可能
- Windows版ではIPCプロトコルの制約上、TCPソケットのみがサポートされる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | L899-900: uv_pipe_pending_count()/uv_pipe_pending_type()の関数宣言 |
| 1-2 | pipe.c (Unix) | `src/unix/pipe.c` | L420-434: uv_pipe_pending_count() Unix版実装 |
| 1-3 | pipe.c (Unix) | `src/unix/pipe.c` | L437-445: uv_pipe_pending_type() Unix版実装 |
| 1-4 | pipe.c (Win) | `src/win/pipe.c` | L2598-2601: uv_pipe_pending_count() Windows版実装 |
| 1-5 | pipe.c (Win) | `src/win/pipe.c` | L2642-2649: uv_pipe_pending_type() Windows版実装 |

**主要処理フロー（Unix版 pending_count L420-434）**:
1. **423-424行目**: `!handle->ipc` なら0を返す
2. **426-427行目**: `accepted_fd == -1` なら0を返す
3. **429-430行目**: `queued_fds == NULL` なら1を返す
4. **432-433行目**: `queued_fds->offset + 1` を返す

**主要処理フロー（Unix版 pending_type L437-445）**:
1. **438-439行目**: `!handle->ipc` ならUV_UNKNOWN_HANDLEを返す
2. **441-444行目**: `accepted_fd == -1` ならUV_UNKNOWN_HANDLE、それ以外は`uv_guess_handle(accepted_fd)`

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

```
uv_pipe_pending_count(handle)
    |
    +-- [Unix] handle->queued_fds チェック
    +-- [Windows] handle->pipe.conn.ipc_xfer_queue_length

uv_pipe_pending_type(handle)
    |
    +-- [Unix] uv_guess_handle(handle->accepted_fd)
    +-- [Windows] return UV_TCP (固定)
```

### データフロー図

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

uv_pipe_t* handle -----> uv_pipe_pending_count() ------> int (保留数)
                          uv_pipe_pending_type()  ------> uv_handle_type (型)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（L899-900） |
| pipe.c (Unix) | `src/unix/pipe.c` | ソース | Unix版実装（L420-445） |
| pipe.c (Win) | `src/win/pipe.c` | ソース | Windows版実装（L2598-2649） |
