# 機能設計書 38-書き込みキューサイズ取得

## 概要

本ドキュメントは、libuvにおける書き込みキューサイズ取得機能（uv_stream_get_write_queue_size()）の設計仕様を記述する。

### 本機能の処理概要

**業務上の目的・背景**：ストリームへの書き込みが非同期で行われるため、送信待ちのデータ量を把握することが重要である。書き込みキューのサイズを監視することで、バックプレッシャー（背圧）制御やフロー制御を実装できる。例えば、書き込みキューが一定サイズを超えた場合に読み取りを一時停止し、キューが縮小したら再開する「高水位/低水位」パターンを実現できる。

**機能の利用シーン**：フロー制御の実装、バッファリング状況のモニタリング、メモリ使用量の管理、デバッグ目的での書き込みキュー状態確認に使用される。

**主要な処理内容**：
1. stream->write_queue_sizeフィールドの値を返す

**関連システム・外部連携**：特になし。内部フィールドの参照のみ。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ストリーム | 主機能 | uv_stream_get_write_queue_size()による書き込みキューサイズ取得のAPI定義 |

## 機能種別

状態照会処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| stream | const uv_stream_t* | Yes | 対象ストリーム | NULLでないこと |

### 入力データソース

アプリケーションコードからの直接呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | size_t | 書き込みキューに蓄積されたバイト数 |

### 出力先

戻り値としてアプリケーションに返却。

## 処理フロー

### 処理シーケンス

```
1. stream->write_queue_sizeの値を返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_stream_get_write_queue_size 呼び出し] --> B[stream->write_queue_size 返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-38-01 | キューサイズの意味 | uv_write()でキューに追加されたデータの未書き込みバイト数の合計 | 常時 |
| BR-38-02 | 加算タイミング | uv_write2()呼び出し時にuv__count_bufs()の結果が加算される | 書き込みリクエスト追加時 |
| BR-38-03 | 減算タイミング | uv__write_callbacks()内で書き込み完了リクエストの未送信サイズが減算される | 書き込み完了コールバック時 |
| BR-38-04 | write_queue_sizeフィールドの公開性 | uv_stream_tのwrite_queue_sizeフィールドは公開フィールドでもある | 常時 |

### 計算ロジック

write_queue_size = 全未送信書き込みリクエストの合計バイト数。uv_write2()で加算、uv__write_callbacks()で減算。

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

該当なし。

### 操作別データベース影響一覧

該当なし。

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

エラーを返す仕組みはない。常にsize_t値を返す。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

- フィールドの直接読み取りのみであり、O(1)で即座に結果を返す
- システムコールは一切呼ばない

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

- 特になし。読み取り専用の状態照会のみ。

## 備考

- write_queue_sizeはuv_stream_tのUV_STREAM_FIELDSマクロ内で「public」フィールドとして定義されているため、直接アクセスも可能だが、uv_stream_get_write_queue_size()の使用が推奨される
- write_queue_sizeが非ゼロでもwrite_queueが空の場合がある（write_completed_queueにエラー状態のリクエストがある場合）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **520-522行目**: UV_STREAM_FIELDSマクロ内のwrite_queue_sizeフィールド |
| 1-2 | uv.h | `include/uv.h` | **540行目**: uv_stream_get_write_queue_size()のAPI宣言 |

**読解のコツ**: write_queue_sizeはUV_STREAM_FIELDSの先頭に配置された公開フィールド。

#### Step 2: 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | **77-79行目**: 実装（`return stream->write_queue_size;`） |

**主要処理フロー**:
- **77-79行目**: 単純なフィールドアクセスによる返却

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

```
uv_stream_get_write_queue_size(stream)
    └─ return stream->write_queue_size
```

### データフロー図

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

stream ───────▶ stream->write_queue_size読み取り ───▶ size_t値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言とwrite_queue_sizeフィールド定義 |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | getter関数の実装 |
| stream.c | `src/unix/stream.c` | ソース | write_queue_sizeの加算/減算ロジック |
