# 機能設計書 62-パイプ初期化

## 概要

本ドキュメントは、libuvにおけるパイプハンドルの初期化機能（`uv_pipe_init()`）について、その設計仕様・処理フロー・プラットフォーム差異を記述する。

### 本機能の処理概要

`uv_pipe_init()`はパイプハンドル（`uv_pipe_t`）をイベントループに登録し、使用可能な状態に初期化する。パイプはUnixではUnixドメインソケット、WindowsではNamed Pipeとして動作し、ローカルプロセス間通信（IPC）やストリームI/Oに利用される。

**業務上の目的・背景**：プロセス間通信やファイルストリーム処理において、パイプは基本的な通信チャネルである。libuvのパイプハンドルは、Unixドメインソケットとwindows Named Pipeの差異を抽象化し、クロスプラットフォームなIPC機構を提供する。初期化関数はパイプの使用開始に必須であり、IPC用途かどうかの設定もこの段階で行う。

**機能の利用シーン**：パイプサーバーの構築（`uv_pipe_bind()`と組み合わせ）、パイプクライアントの接続（`uv_pipe_connect()`と組み合わせ）、子プロセスの標準入出力のリダイレクト、プロセス間でのハンドル受け渡し（IPC）など。

**主要な処理内容**：
1. ストリーム基底構造体をUV_NAMED_PIPEタイプで初期化する（`uv__stream_init()`呼び出し）
2. パイプ固有のフィールド（pipe_fname, ipc等）を初期設定する
3. IPC用途フラグを設定する

**関連システム・外部連携**：Unix系OSのAF_UNIXソケットAPI、WindowsのNamed Pipe API（CreateNamedPipe/CreateFile）。

**権限による制御**：初期化段階では権限制御は不要。パイプのバインドや接続時にファイルシステム権限やNamed Pipe権限が必要になる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | パイプ | 主機能 | uv_pipe_init()によるパイプハンドル初期化のAPI定義（IPC対応） |

## 機能種別

初期化処理（ハンドルの生成・登録）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | パイプハンドルを登録するイベントループ | NULLでないこと |
| handle | uv_pipe_t* | Yes | 初期化するパイプハンドル | NULLでないこと |
| ipc | int | Yes | IPCモードフラグ（0以外でハンドル受け渡し用） | 0または非0 |

### 入力データソース

呼び出し元のアプリケーションコードから直接パラメータとして受け取る。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時は0 |

### 出力先

関数の戻り値として呼び出し元に返す。ハンドル構造体はインプレースで初期化される。

## 処理フロー

### 処理シーケンス

```
1. ストリーム基底構造体の初期化
   └─ uv__stream_init()をUV_NAMED_PIPEタイプで呼び出し
2. パイプ固有フィールドの初期化
   └─ (Unix) shutdown_req, connect_req, pipe_fnameをNULL/0に設定
   └─ (Windows) reqs_pending, handle, name, IPC関連フィールドを初期設定
3. IPCフラグの設定
   └─ handle->ipc = ipc
4. 成功を返す
   └─ return 0
```

### フローチャート

```mermaid
flowchart TD
    A[uv_pipe_init 呼び出し] --> B[uv__stream_init で<br/>UV_NAMED_PIPEとして初期化]
    B --> C{プラットフォーム}
    C -->|Unix| D[shutdown_req = NULL<br/>connect_req = NULL<br/>pipe_fname = NULL]
    C -->|Windows| E[reqs_pending = 0<br/>handle = INVALID_HANDLE_VALUE<br/>name = NULL<br/>IPC関連フィールド初期化]
    D --> F[handle->ipc = ipc]
    E --> F
    F --> G[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-62-01 | IPC専用フラグ | ipcフラグはハンドル受け渡しを行う接続済みパイプにのみ設定すべき。リスニングパイプには設定不要 | パイプ初期化時 |
| BR-62-02 | ストリーム継承 | uv_pipe_tはuv_stream_tのサブクラスであり、ストリーム系APIが使用可能 | 常時 |
| BR-62-03 | 型識別 | UV_NAMED_PIPEタイプとして登録され、uv_handle_type_name()で"pipe"が返る | 常時 |

### 計算ロジック

該当なし（フィールドの直接代入のみ）

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

該当なし（メモリ上の構造体初期化のみ）

## エラー処理

### エラーケース一覧

本関数は常に0を返す。`uv__stream_init()`は内部でassertを使用するため、不正なパラメータではプロセスが異常終了する可能性がある。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

構造体フィールドの初期化のみのため、O(1)で完了する。

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

初期化段階ではセキュリティ上の懸念はない。IPCフラグが設定されたパイプではハンドル（ファイルディスクリプタ/ソケット）の受け渡しが可能になるため、信頼できるプロセス間でのみ使用すべきである。

## 備考

- Unixではパイプハンドルはソケット(AF_UNIX, SOCK_STREAM)として実装される
- Windowsでは`\\?\pipe\`プレフィックスのNamed Pipeとして実装される
- パイプハンドルは`uv_close()`で閉じる必要がある
- Unixでは`pipe_fname`フィールドがバインド時に設定され、クローズ時にunlinkされる

---

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

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

### 推奨読解順序

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

パイプハンドルの構造体定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_pipe_s構造体定義（868-873行目）。UV_HANDLE_FIELDS, UV_STREAM_FIELDS, ipc, UV_PIPE_PRIVATE_FIELDSの構成 |

**読解のコツ**: `uv_pipe_t`は`uv_stream_t`のサブクラス。マクロ`UV_HANDLE_FIELDS`と`UV_STREAM_FIELDS`が先頭に配置されているため、`uv_handle_t*`や`uv_stream_t*`へのキャストが安全に行える。

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

API宣言と各プラットフォームの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | uv_pipe_init()のAPI宣言（875行目） |

#### Step 3: Unix実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | pipe.c (Unix) | `src/unix/pipe.c` | uv_pipe_init()のUnix実装（48-55行目） |

**主要処理フロー**:
- **49行目**: `uv__stream_init(loop, (uv_stream_t*)handle, UV_NAMED_PIPE)` でストリーム基底を初期化
- **50行目**: `handle->shutdown_req = NULL` - シャットダウンリクエストを初期化
- **51行目**: `handle->connect_req = NULL` - 接続リクエストを初期化
- **52行目**: `handle->pipe_fname = NULL` - パイプファイル名を初期化
- **53行目**: `handle->ipc = ipc` - IPCモードフラグを設定

#### Step 4: Windows実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | pipe.c (Win) | `src/win/pipe.c` | uv_pipe_init()のWindows実装（114-128行目） |

**主要処理フロー**:
- **115行目**: `uv__stream_init(loop, (uv_stream_t*)handle, UV_NAMED_PIPE)` でストリーム基底を初期化
- **117行目**: `handle->reqs_pending = 0` - 保留リクエスト数を初期化
- **118行目**: `handle->handle = INVALID_HANDLE_VALUE` - Windowsハンドルを初期化
- **119行目**: `handle->name = NULL` - パイプ名を初期化
- **120-123行目**: IPC関連フィールド（remote_pid, xfer_queue等）を初期化
- **124行目**: `handle->ipc = ipc` - IPCモードフラグを設定

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

```
uv_pipe_init()                              [API関数]
    │
    ├─ uv__stream_init()                     [ストリーム基底初期化]
    │      ├─ uv__handle_init()              [ハンドル基底初期化]
    │      │      └─ ループへのハンドル登録
    │      └─ ストリームフィールド初期化
    │
    └─ パイプ固有フィールド初期化
           ├─ (Unix) pipe_fname = NULL
           └─ (Windows) handle = INVALID_HANDLE_VALUE
```

### データフロー図

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

loop (uv_loop_t*) ──┐
                     ├──> uv_pipe_init() ──────> 初期化済み uv_pipe_t
handle (uv_pipe_t*) ─┤                            (ループに登録済み)
                     │
ipc (int) ──────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（875行目）、uv_pipe_s構造体定義（868-873行目） |
| pipe.c (Unix) | `src/unix/pipe.c` | ソース | Unix実装（48-55行目） |
| pipe.c (Win) | `src/win/pipe.c` | ソース | Windows実装（114-128行目） |
| pipe.rst | `docs/src/pipe.rst` | ドキュメント | APIドキュメント（36-42行目） |
| stream.c | `src/unix/stream.c` | ソース | uv__stream_init()の実装 |
