# 画面設計書 17-ストリーム

## 概要

本ドキュメントは、libuvドキュメントサイトにおける `uv_stream_t`（ストリームハンドル）APIリファレンスページの画面設計書である。Sphinxにより生成されるHTMLページとして、ストリームハンドルの型定義・リクエスト型・コールバック型・API関数仕様を表示する。

### 本画面の処理概要

ストリームハンドルは、双方向通信チャネルの抽象化を提供する。`uv_stream_t` は抽象型であり、libuvは `uv_tcp_t`、`uv_pipe_t`、`uv_tty_t` の3つのストリーム実装を提供する。本ページでは、全ストリーム実装に共通する読み取り・書き込み・接続待ち受け・接続受け入れ・シャットダウン等のAPIを詳細に解説する。

**業務上の目的・背景**：ネットワーク通信やプロセス間通信において、データの読み書きは最も基本的な操作である。ストリームハンドルは、TCP/パイプ/TTYという異なる通信チャネルに対して統一されたインターフェースを提供し、プロトコルに依存しない汎用的なデータ処理ロジックの実装を可能にする。非同期読み取り（read_start/read_stop）、非同期書き込み（write/write2）、同期書き込み試行（try_write/try_write2）、接続管理（listen/accept）、シャットダウンなど、ストリーム通信に必要な全機能を網羅する。本ページは、TCP/パイプ/TTYの実装詳細に入る前に理解すべき共通基盤のリファレンスである。

**画面へのアクセス方法**：トップページ → APIドキュメント一覧（api.rst） → ストリーム（stream.rst）の順にナビゲーションリンクを辿ってアクセスする。

**主要な操作・処理内容**：
1. `uv_stream_t`、`uv_connect_t`、`uv_shutdown_t`、`uv_write_t` の型定義を閲覧する
2. 各コールバック型（`uv_read_cb`、`uv_write_cb`、`uv_connect_cb`、`uv_shutdown_cb`、`uv_connection_cb`）の仕様を確認する
3. `uv_shutdown()` / `uv_listen()` / `uv_accept()` による接続管理APIを確認する
4. `uv_read_start()` / `uv_read_stop()` による非同期読み取りAPIを確認する
5. `uv_write()` / `uv_write2()` / `uv_try_write()` / `uv_try_write2()` による書き込みAPIを確認する
6. `uv_is_readable()` / `uv_is_writable()` / `uv_stream_set_blocking()` / `uv_stream_get_write_queue_size()` のユーティリティAPIを確認する

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底ページ（handle.rst）への参照リンク
- 関連ページ：TCPページ（tcp.rst）、パイプページ（pipe.rst）、TTYページ（tty.rst）

**権限による表示制御**：なし（公開ドキュメントサイトのため、全ユーザーが同一内容を閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | ストリーム読み取り開始・停止 | 主機能 | uv_read_start()/uv_read_stop()による非同期読み取り制御のAPI定義 |
| 31 | ストリーム書き込み | 主機能 | uv_write()/uv_write2()による非同期書き込みのAPI定義（ハンドル送信対応） |
| 32 | 同期的書き込み試行 | 主機能 | uv_try_write()/uv_try_write2()による同期的書き込み試行のAPI定義 |
| 33 | ストリーム接続待受 | 主機能 | uv_listen()によるストリーム接続待ち受けのAPI定義 |
| 34 | 接続受入 | 主機能 | uv_accept()による接続受け入れのAPI定義 |
| 35 | シャットダウン | 主機能 | uv_shutdown()による書き込み側シャットダウンのAPI定義 |
| 36 | 読み書き可能判定 | 主機能 | uv_is_readable()/uv_is_writable()による読み書き可能判定のAPI定義 |
| 37 | ブロッキングモード設定 | 主機能 | uv_stream_set_blocking()によるブロッキング/ノンブロッキング設定のAPI定義 |
| 38 | 書き込みキューサイズ取得 | 主機能 | uv_stream_get_write_queue_size()による書き込みキューサイズ取得のAPI定義 |

## 画面種別

APIリファレンス詳細ページ

## URL/ルーティング

`docs/src/stream.rst` → ビルド後: `/stream.html`

## 入出力項目

本ページはドキュメント表示ページのため、ユーザー入力項目はない。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページコンテンツ | 出力 | HTML | rstファイルからSphinxによって生成されたHTML |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_stream_t` --- Stream handle | ページタイトル |
| 概要説明 | Stream handles provide an abstraction of a duplex communication channel | ストリームの概要 |
| Data types | uv_stream_t, uv_connect_t, uv_shutdown_t, uv_write_t | 型定義 |
| Callback types | uv_read_cb, uv_write_cb, uv_connect_cb, uv_shutdown_cb, uv_connection_cb | コールバック型 |
| Public members | write_queue_size, connect_t.handle, shutdown_t.handle, write_t.handle/send_handle | パブリックメンバー |
| API - uv_shutdown | 書き込み側シャットダウン | pending write完了後に実行 |
| API - uv_listen | 接続待ち受け開始 | backlog指定 |
| API - uv_accept | 接続受け入れ | connection_cb内で呼び出し |
| API - uv_read_start | 非同期読み取り開始 | v1.38.0でUV_EALREADY動作統一 |
| API - uv_read_stop | 読み取り停止 | 冪等操作 |
| API - uv_write/write2 | 非同期書き込み | バッファ順序書き込み、ハンドル送信対応 |
| API - uv_try_write/try_write2 | 同期書き込み試行 | キューイングなし |
| API - uv_is_readable/writable | 読み書き可能判定 | |
| API - uv_stream_set_blocking | ブロッキングモード設定 | v1.4.0でUNIX追加 |
| API - uv_stream_get_write_queue_size | キューサイズ取得 | v1.19.0追加 |

## イベント仕様

### 1-ページ内リンク遷移

`:c:type:`uv_handle_t``、`:c:type:`uv_tcp_t``、`:c:type:`uv_pipe_t``、`:c:type:`uv_tty_t`` 等への参照リンクで各ページに遷移する。

### 2-読み取りコールバック（ランタイム動作）

`uv_read_start()` で読み取りを開始すると、データ到着時に `uv_read_cb` が呼び出される。`nread > 0` はデータ利用可能、`nread == UV_EOF` はストリーム終端、`nread < 0` はエラーを示す。`nread == 0` はEAGAIN相当であり、エラーではない。

### 3-書き込みコールバック（ランタイム動作）

`uv_write()` による書き込み完了時に `uv_write_cb` が呼び出される。`status == 0` は成功を示す。

### 4-接続コールバック（ランタイム動作）

`uv_listen()` で待ち受け中に接続要求が到着すると `uv_connection_cb` が呼び出される。その中で `uv_accept()` を呼んで接続を受け入れる。

## データベース更新仕様

本ページは静的ドキュメント表示のため、データベース操作は存在しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | 静的HTMLドキュメントのためDB操作なし |

### テーブル別更新項目詳細

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | uv_read_startの二重呼び出し | UV_EALREADY（v1.38.0以降） |
| エラー | ストリームクローズ中のuv_read_start | UV_EINVAL |
| エラー | try_writeで即座に書き込み不可 | UV_EAGAIN |

## 例外処理

- ページが見つからない場合：Webサーバーの404エラーが表示される

## 備考

- `uv_stream_t` は抽象型であり、直接インスタンス化しない。`uv_tcp_t`、`uv_pipe_t`、`uv_tty_t` を通じて使用する
- `uv_write_t` オブジェクトの再利用はコールバック実行後のみ安全
- `uv_write()` のバッファメモリはコールバックまで有効である必要がある
- `uv_try_write2()` はv1.42.0で追加
- `uv_stream_set_blocking()` のUNIX実装はv1.4.0で追加
- `uv_stream_get_write_queue_size()` はv1.19.0で追加
- `uv_read_start()` のUV_EALREADY動作統一はv1.38.0

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_stream_t`、`uv_connect_t`、`uv_shutdown_t`、`uv_write_t` の構造体定義 |
| 1-2 | stream.rst | `docs/src/stream.rst` | 1-259行目: 型定義・コールバック型・パブリックメンバー・全API仕様 |

**読解のコツ**: `uv_stream_t` は `uv_handle_t` のサブクラスであり、`UV_HANDLE_FIELDS` と `UV_STREAM_FIELDS` マクロで構成される。`write_queue_size` はreadonly公開メンバーだが、`uv_stream_get_write_queue_size()` でも取得可能。

#### Step 2: 接続管理APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | stream.c | `src/unix/stream.c` | 600行目: `uv_listen` - ストリーム型ごとにディスパッチ |
| 2-2 | stream.c | `src/unix/stream.c` | 535行目: `uv_accept` - クライアントハンドルへの接続移譲 |
| 2-3 | stream.c | `src/unix/stream.c` | 1161行目: `uv_shutdown` - 書き込み側シャットダウン |

#### Step 3: 読み書きAPIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | stream.c | `src/unix/stream.c` | `uv_read_start` - I/Oウォッチャー開始、alloc_cb/read_cb設定 |
| 3-2 | stream.c | `src/unix/stream.c` | 1413行目: `uv_write` - バッファのキューイング |
| 3-3 | stream.c | `src/unix/stream.c` | 1570行目: `uv_stream_set_blocking` - ブロッキングモード設定 |

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

```
uv_listen(stream, backlog, cb) [src/unix/stream.c:600]
    |
    +-- [TCP] uv__tcp_listen()
    +-- [Pipe] uv__pipe_listen()

uv_accept(server, client) [src/unix/stream.c:535]
    |
    +-- accept()系システムコール
    +-- クライアントハンドルへのFD設定

uv_read_start(stream, alloc_cb, read_cb) [src/unix/stream.c]
    |
    +-- uv__io_start() [I/O監視開始]
    +-- [データ到着時] read_cb(stream, nread, buf)

uv_write(req, handle, bufs, nbufs, cb) [src/unix/stream.c:1413]
    |
    +-- uv__write(stream, bufs, nbufs, send_handle, cb)
    +-- [書き込み完了時] write_cb(req, status)

uv_shutdown(req, handle, cb) [src/unix/stream.c:1161]
    |
    +-- shutdown(fd, SHUT_WR)
    +-- [完了時] shutdown_cb(req, status)
```

### データフロー図

```
[クライアント]           [サーバー]

                    uv_listen(stream, backlog, cb)
connect() -------->     |
                    connection_cb(server, 0)
                        |
                    uv_accept(server, client)
                        |
send(data) -------->  uv_read_start(client, alloc_cb, read_cb)
                        |
                    read_cb(client, nread, buf)
                        |
                    uv_write(req, client, bufs, nbufs, write_cb)
<------------- data
                        |
                    uv_shutdown(req, client, shutdown_cb)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| stream.rst | `docs/src/stream.rst` | テンプレート | ストリームハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_stream_t・リクエスト型・コールバック型の定義 |
| stream.c | `src/unix/stream.c` | ソース | Unix用ストリーム read/write/listen/accept/shutdown実装 |
| stream.c | `src/win/stream.c` | ソース | Windows用ストリーム実装 |
| tcp.c | `src/unix/tcp.c` | ソース | TCP固有のlisten/connect実装 |
| pipe.c | `src/unix/pipe.c` | ソース | パイプ固有のlisten/connect実装 |
