# 機能設計書 43-Nagle制御

## 概要

本ドキュメントは、libuv の `uv_tcp_nodelay()` APIによりTCP_NODELAYオプション（Nagleアルゴリズム無効化）を設定する機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：TCPにおいてNagleアルゴリズムは、小さなパケットをバッファリングしてネットワーク効率を向上させる。しかし、リアルタイム性が求められるアプリケーション（対話型プロトコル、ゲームサーバー、金融トレーディング等）では、この遅延が問題となる。uv_tcp_nodelay()はTCP_NODELAYソケットオプションを制御し、Nagleアルゴリズムの有効/無効を切り替える機能を提供する。

**機能の利用シーン**：低遅延が要求されるTCP通信、WebSocketサーバー、SSHクライアント、テルネットなどの対話型プロトコル、リアルタイムデータストリーミングで使用される。

**主要な処理内容**：
1. ソケットが既に作成されている場合、setsockopt()でTCP_NODELAYオプションを設定
2. ハンドルフラグ（UV_HANDLE_TCP_NODELAY）を更新
3. ソケット未作成時はフラグのみ設定（ソケット作成時に適用される）

**関連システム・外部連携**：OSのソケットオプション（setsockopt/TCP_NODELAY）を使用する。

**権限による制御**：特別な権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | TCP | 主機能 | uv_tcp_nodelay()によるTCP_NODELAYオプション設定のAPI定義 |

## 機能種別

ソケットオプション設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_tcp_t* | Yes | 初期化済みTCPハンドル | uv_tcp_init()で初期化済みであること |
| enable | int | Yes | 1: TCP_NODELAY有効（Nagle無効化）、0: TCP_NODELAY無効（Nagle有効化） | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、失敗時負のエラーコード |

### 出力先

戻り値として直接返却。

## 処理フロー

### 処理シーケンス

```
1. ソケット存在チェック
   └─ uv__stream_fd(handle) != -1 の場合、setsockoptを即時実行
2. setsockopt実行（ソケット存在時）
   └─ uv__tcp_nodelay(fd, on)でTCP_NODELAYを設定
3. フラグ更新
   └─ on=1: UV_HANDLE_TCP_NODELAY設定、on=0: フラグクリア
```

### フローチャート

```mermaid
flowchart TD
    A[uv_tcp_nodelay 呼び出し] --> B{ソケット存在?}
    B -->|Yes| C[uv__tcp_nodelay呼び出し]
    C --> D{成功?}
    D -->|No| E[エラー返却]
    D -->|Yes| F{enable?}
    B -->|No| F
    F -->|1| G[UV_HANDLE_TCP_NODELAY設定]
    F -->|0| H[UV_HANDLE_TCP_NODELAYクリア]
    G --> I[0 を返す]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-1 | 遅延設定対応 | ソケット未作成時はフラグのみ設定し、ソケット作成時に適用される | uv__stream_fd(handle) == -1 |
| BR-43-2 | 即時適用 | ソケット存在時はsetsockopt()で即時適用される | uv__stream_fd(handle) != -1 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV__ERR(errno) | システムエラー | setsockopt()が失敗した場合 | ソケットの状態を確認する |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

同期的に即座に完了する軽量な操作。

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

特になし。

## 備考

- Nagleアルゴリズムを無効化すると、小さなパケットが即座に送信されるためネットワーク帯域の使用効率が低下する可能性がある。
- 通常、サーバーアプリケーションでは低遅延のためにTCP_NODELAYを有効にすることが推奨される。

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: enable引数は整数型で、0以外の値がTCP_NODELAY有効を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tcp.c | `src/unix/tcp.c` | uv_tcp_nodelay()の実装（573-588行目） |

**主要処理フロー**:
1. **576-580行目**: ソケットが存在する場合、uv__tcp_nodelay()を呼び出してsetsockoptを実行
2. **582-585行目**: on=1ならUV_HANDLE_TCP_NODELAYフラグを設定、on=0ならクリア

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tcp.c | `src/unix/tcp.c` | uv__tcp_nodelay()の実装（453-457行目）。setsockopt(IPPROTO_TCP, TCP_NODELAY)を呼び出す |

**主要処理フロー**:
- **454行目**: setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, &on, sizeof(on))

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

```
uv_tcp_nodelay() [src/unix/tcp.c:573]
    │
    └─ uv__tcp_nodelay() [src/unix/tcp.c:453]
           │
           └─ setsockopt() [OS system call]
```

### データフロー図

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

uv_tcp_t* handle    ──▶  uv_tcp_nodelay()         ──▶  戻り値(0/エラー)
int enable          ──▶  ├ setsockopt(TCP_NODELAY)
                         └ フラグ更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_tcp_nodelay()のAPI宣言 |
| tcp.c (unix) | `src/unix/tcp.c` | ソース | uv_tcp_nodelay()/uv__tcp_nodelay()の実装 |
| tcp.c (win) | `src/win/tcp.c` | ソース | Windows固有の実装 |
