# 機能設計書 67-パイプ保留インスタンス数設定

## 概要

本ドキュメントは、パイプサーバーの保留インスタンス数を設定する機能（`uv_pipe_pending_instances()`）の設計を記述する。

### 本機能の処理概要

Windows Named Pipeサーバーにおいて、同時に接続を受け入れるために事前に作成するパイプインスタンスの数を設定する。Unix環境ではこの設定は意味を持たない（no-op）。

**業務上の目的・背景**：Windows Named Pipeでは、複数のクライアントからの同時接続要求を処理するために、事前にパイプインスタンスを作成しておく必要がある。このインスタンス数を制御することで、サーバーの同時接続受け入れ能力を調整できる。

**機能の利用シーン**：高負荷のNamed Pipeサーバーで同時接続数を増やしたい場合や、リソース消費を抑えるためにインスタンス数を制限したい場合に使用される。uv_pipe_bind()の前に呼び出す必要がある。

**主要な処理内容**：
1. Windows: pending_instancesフィールドに値を設定し、UV_HANDLE_PIPESERVERフラグを立てる
2. Unix: 何もしない（空関数）

**関連システム・外部連携**：Windows CreateNamedPipeW() API（PIPE_UNLIMITED_INSTANCESパラメータ）。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | パイプ | 主機能 | uv_pipe_pending_instances()による保留インスタンス数設定のAPI定義（Windows用） |

## 機能種別

設定処理（パイプサーバーパラメータ設定）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_pipe_t* | Yes | 設定対象のパイプハンドル | バインド前であること（Windows） |
| count | int | Yes | 保留インスタンス数 | 正の整数が望ましい |

### 入力データソース

呼び出し元アプリケーションから直接提供される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void | なし |

### 出力先

パイプハンドルの内部フィールド（handle->pipe.serv.pending_instances）。

## 処理フロー

### 処理シーケンス

```
1. プラットフォーム判定
   └─ Unix: 何もせずreturn
   └─ Windows: 以下を実行
2. バインド済みチェック（Windows）
   └─ UV_HANDLE_BOUNDフラグが立っている場合はreturn
3. 値の設定（Windows）
   └─ handle->pipe.serv.pending_instances = count
4. フラグ設定（Windows）
   └─ handle->flags |= UV_HANDLE_PIPESERVER
```

### フローチャート

```mermaid
flowchart TD
    A[開始: uv_pipe_pending_instances] --> B{プラットフォーム}
    B -->|Unix| C[何もしない<br/>return]
    B -->|Windows| D{UV_HANDLE_BOUND?}
    D -->|Yes| E[return<br/>既にバインド済み]
    D -->|No| F[pending_instances = count<br/>flags |= UV_HANDLE_PIPESERVER]
    F --> G[return]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | バインド前呼び出し | uv_pipe_bind()の前に呼び出す必要がある。バインド後の呼び出しは無視される | Windows環境 |
| BR-02 | デフォルト値 | 呼び出さない場合、デフォルト値は4（default_pending_pipe_instances） | Windows環境 |
| BR-03 | Unix no-op | Unix環境では空関数であり何も行わない | Unix環境 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

本関数はvoid型でありエラーを返さない。

### リトライ仕様

リトライ不要。

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

該当なし。

## パフォーマンス要件

フィールド代入のみであり、O(1)で完了する。

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

特になし。

## 備考

- Windows版でuv_pipe_pending_instances()を呼び出さずにuv_pipe_bind()を呼んだ場合、デフォルト値4が使用される（src/win/pipe.c L48, L751）
- インスタンス数はuv_pipe_bind2()内でaccept_reqs配列の割り当てサイズとして使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | L898: uv_pipe_pending_instances()の関数宣言 |
| 1-2 | pipe.c (Unix) | `src/unix/pipe.c` | L416-417: Unix版実装（空関数） |
| 1-3 | pipe.c (Win) | `src/win/pipe.c` | L695-700: Windows版実装 |
| 1-4 | pipe.c (Win) | `src/win/pipe.c` | L48: default_pending_pipe_instances定数（値: 4） |

**主要処理フロー（Windows版 L695-700）**:
1. **696行目**: `handle->flags & UV_HANDLE_BOUND`チェック。バインド済みならreturn
2. **698行目**: `handle->pipe.serv.pending_instances = count`
3. **699行目**: `handle->flags |= UV_HANDLE_PIPESERVER`

#### Step 2: 設定値の使用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pipe.c (Win) | `src/win/pipe.c` | L750-756: uv_pipe_bind2()内でpending_instancesがデフォルト設定・accept_reqs配列割り当てに使用される |
| 2-2 | pipe.c (Win) | `src/win/pipe.c` | L761-767: accept_reqs配列の初期化ループ |

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

```
uv_pipe_pending_instances(handle, count)
    |
    +-- [Unix] (空関数)
    |
    +-- [Windows]
        +-- handle->pipe.serv.pending_instances = count
        +-- handle->flags |= UV_HANDLE_PIPESERVER

使用箇所:
uv_pipe_bind2() [Windows]
    |
    +-- pending_instances を使って accept_reqs を割り当て
    +-- 各インスタンスで CreateNamedPipeW() を呼び出し
```

### データフロー図

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

uv_pipe_t* handle ------> uv_pipe_pending_instances() ----> pending_instances設定
int count                   |                                UV_HANDLE_PIPESERVER設定
                            +-- バインド済みチェック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（L898） |
| pipe.c (Unix) | `src/unix/pipe.c` | ソース | Unix版実装（L416-417、空関数） |
| pipe.c (Win) | `src/win/pipe.c` | ソース | Windows版実装（L695-700）、デフォルト値（L48） |
