# 機能設計書 60-UDP送信キュー情報取得

## 概要

本ドキュメントは、libuvにおけるUDP送信キュー情報取得機能（`uv_udp_get_send_queue_size()` / `uv_udp_get_send_queue_count()`）の設計仕様を記述する。UDPハンドルの送信キューに溜まっているデータサイズとリクエスト数を取得する。

### 本機能の処理概要

**業務上の目的・背景**：非同期UDP送信において、送信キューの状態を監視することは、フロー制御やバックプレッシャー機構の実装に不可欠である。送信キューのサイズやリクエスト数を確認することで、アプリケーション側で送信速度を調整したり、キューが溜まりすぎた場合に送信を一時停止する判断が可能になる。

**機能の利用シーン**：
- 送信バックプレッシャーの実装（キューサイズに基づく送信制御）
- 送信キューの監視とデバッグ
- パフォーマンスメトリクスの収集
- 送信完了待ちの判定（キューが空になったか確認）

**主要な処理内容**：
1. get_send_queue_size: handle->send_queue_sizeフィールドの値を返却
2. get_send_queue_count: handle->send_queue_countフィールドの値を返却

**関連システム・外部連携**：特になし（インメモリデータの参照のみ）。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | UDP | 主機能 | uv_udp_get_send_queue_size()/count()による送信キュー情報取得のAPI定義 |

## 機能種別

情報取得 / 状態照会

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | const uv_udp_t* | Yes | UDPハンドル | NULLでないこと |

### 入力データソース

UDPハンドル構造体の内部フィールド。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| get_send_queue_size戻り値 | size_t | 送信キュー内のデータバイト数合計 |
| get_send_queue_count戻り値 | size_t | 送信キュー内の送信リクエスト数 |

### 出力先

呼び出し元への戻り値として返却。

## 処理フロー

### 処理シーケンス

```
[get_send_queue_size]
1. handle->send_queue_sizeを返却

[get_send_queue_count]
1. handle->send_queue_countを返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_udp_get_send_queue_size/count] --> B[構造体フィールド参照]
    B --> C[値を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-01 | サイズ追跡 | send_queue_sizeはuv_udp_send()時に加算、完了時に減算される | 常時 |
| BR-60-02 | カウント追跡 | send_queue_countはuv_udp_send()時にインクリメント、完了時にデクリメントされる | 常時 |
| BR-60-03 | 読み取り専用 | これらのフィールドはread-onlyであり、アプリケーションから変更してはならない | 常時 |
| BR-60-04 | 完了キュー含む | エラー状態で完了キューにあるリクエストもカウントに含まれる場合がある | write_completed_queue非空時 |

### 計算ロジック

- `send_queue_size`の加算: `handle->send_queue_size += uv__count_bufs(req->bufs, req->nbufs)` （uv__udp_send内、L691）
- `send_queue_size`の減算: `handle->send_queue_size -= uv__count_bufs(req->bufs, req->nbufs)` （uv__udp_run_completed内、L112）
- `send_queue_count`の加算: `handle->send_queue_count++` （uv__udp_send内、L692）
- `send_queue_count`の減算: `handle->send_queue_count--` （uv__udp_run_completed内、L113）

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

該当なし。

## エラー処理

### エラーケース一覧

本関数にはエラーケースはない。常に有効な値を返す。

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

O(1)のフィールド参照のみ。オーバーヘッドは無視できる。

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

特になし。

## 備考

- これらの関数はスレッドセーフではなく、イベントループスレッドからのみ呼び出すべき
- uv_udp_s構造体のsend_queue_sizeとsend_queue_countフィールドは直接アクセスも可能だが、getter関数の使用が推奨される
- uv_udp_try_send()は送信キューを使用しないため、これらの値に影響しない

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L721-734行目**: uv_udp_s構造体。send_queue_size（L728）とsend_queue_count（L732）フィールド |
| 1-2 | uv.h | `include/uv.h` | **L797-798行目**: uv_udp_get_send_queue_size()/uv_udp_get_send_queue_count()のAPI宣言 |

**読解のコツ**: send_queue_sizeはバイト数（データ量）、send_queue_countはリクエスト数（メッセージ数）を表す。両方ともread-onlyフィールドである。

#### Step 2: getter関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | **L81-87行目**: 両関数の実装。単純なフィールド参照を返すだけ |

**主要処理フロー**:
- **L81-83行目**: uv_udp_get_send_queue_size() - `return handle->send_queue_size;`
- **L85-87行目**: uv_udp_get_send_queue_count() - `return handle->send_queue_count;`

#### Step 3: 値の更新箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | udp.c (unix) | `src/unix/udp.c` | **L691-692行目**: uv__udp_send()内での加算処理 |
| 3-2 | udp.c (unix) | `src/unix/udp.c` | **L112-113行目**: uv__udp_run_completed()内での減算処理 |
| 3-3 | udp.c (unix) | `src/unix/udp.c` | **L938-961行目**: uv__udp_init_ex()内での初期化（0に設定） |

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

```
uv_udp_get_send_queue_size(handle)
    └─ return handle->send_queue_size

uv_udp_get_send_queue_count(handle)
    └─ return handle->send_queue_count

[値の更新]
uv__udp_send()
    ├─ handle->send_queue_size += uv__count_bufs(bufs, nbufs)
    └─ handle->send_queue_count++

uv__udp_run_completed()
    ├─ handle->send_queue_size -= uv__count_bufs(bufs, nbufs)
    └─ handle->send_queue_count--
```

### データフロー図

```
[入力/更新元]                    [フィールド]                  [出力]

uv__udp_send() ──加算──▶ handle->send_queue_size ──▶ uv_udp_get_send_queue_size()
                          handle->send_queue_count ──▶ uv_udp_get_send_queue_count()
uv__udp_run_completed() ──減算──▶
uv__udp_init_ex() ──初期化(0)──▶
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言とuv_udp_s構造体定義 |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | getter関数実装 |
| udp.c (unix) | `src/unix/udp.c` | ソース | フィールド更新処理（送信・完了） |
