# 機能設計書 85-asyncstreams

## 概要

本ドキュメントは、Nim標準ライブラリのasyncstreamsモジュールに関する機能設計書である。非同期データストリームを実現するFutureStream型を提供し、非同期パイプライン処理を可能にする。

### 本機能の処理概要

asyncstreamsモジュールは、FutureStream[T]型を実装する。これは通常のFuture[T]が単一の値を返すのに対し、複数の値を非同期で順次生成・消費できるストリーム型である。キュー構造を内部に持ち、プロデューサー・コンシューマーパターンを非同期で実現する。

**業務上の目的・背景**：HTTPレスポンスのストリーミング、ファイルの逐次読み込み、リアルタイムデータフィードなど、データが時間をかけて段階的に生成される場面で使用される。メモリ効率が良く、大量データの処理に適している。

**機能の利用シーン**：HTTPレスポンスのチャンク読み込み、大規模ファイルの非同期読み書き、WebSocketメッセージの処理、イベントストリームの購読など。

**主要な処理内容**：
1. FutureStream[T]の生成（newFutureStream関数）
2. ストリームへのデータ書き込み（write関数）
3. ストリームからのデータ読み出し（read関数）
4. ストリームの完了処理（complete関数）

**関連システム・外部連携**：asyncdispatch、asyncfileと連携してストリーム処理を実現。

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

## 関連画面

該当なし（ライブラリモジュールのため画面との直接的な関連はない）

## 機能種別

データストリーム / 非同期キュー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fromProc | string | No | デバッグ用のプロシージャ名 | デフォルト"unspecified" |
| value | T | Yes | ストリームに書き込む値 | 型Tに応じた値 |

### 入力データソース

非同期操作からのデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FutureStream[T] | ref object | 非同期ストリームオブジェクト |
| (bool, T) | tuple | 読み出し結果（成功フラグと値） |

### 出力先

コールバック関数 / await式

## 処理フロー

### 処理シーケンス

```
1. FutureStream生成
   └─ newFutureStream[T]()
      ├─ finished = false
      ├─ queue = initDeque[T]()
      └─ cb = nil

2. データ書き込み
   └─ write(value)
      ├─ finished=trueなら → fail
      ├─ queue.addLast(value)
      ├─ cb呼び出し（存在する場合）
      └─ Future[void].complete()

3. データ読み出し
   └─ read()
      ├─ 新規Future[(bool, T)]生成
      ├─ コールバック設定
      │    └─ queue.popFirst()またはfinished状態に応じて完了
      └─ queueが空でないか完了済みなら即座にコールバック実行

4. ストリーム完了
   └─ complete()
      ├─ finished = true
      └─ cb呼び出し（存在する場合）
```

### フローチャート

```mermaid
flowchart TD
    A[newFutureStream] --> B[FutureStream生成]
    B --> C{操作}

    C -->|write| D{finished?}
    D -->|Yes| E[ValueError]
    D -->|No| F[queue.addLast]
    F --> G[cb呼び出し]
    G --> H[Future.complete]

    C -->|read| I[新規Future生成]
    I --> J{queue空?}
    J -->|No| K[popFirstで値取得]
    K --> L[complete true,value]
    J -->|Yes| M{finished?}
    M -->|Yes| N[complete false,default]
    M -->|No| O[コールバック設定して待機]

    C -->|complete| P[finished=true]
    P --> Q[cb呼び出し]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-85-01 | 完了後の書き込み禁止 | finished=trueのストリームへのwriteはエラー | write呼び出し時 |
| BR-85-02 | 読み出し結果判定 | readの戻り値(bool, T)のboolでデータ有無を判定 | read完了時 |
| BR-85-03 | FIFO順序保証 | writeした順序でreadされる | 常時 |
| BR-85-04 | コールバック継承 | readコールバック設定時、既存コールバックを保存 | callback=呼び出し時 |

### 計算ロジック

**finished判定**（finished関数）:
- future.finished AND future.queue.len == 0 のときtrue
- キューにデータが残っている場合はfalse

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ValueError | 完了後write | finished=trueのストリームにwrite | 書き込み前にfinished確認 |
| エラー伝播 | fail時のread | ストリームがfailした場合 | read側でエラー処理 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- write: O(1) amortized（Deque追加）
- read: O(1) amortized（Deque取り出し）
- メモリ: キューサイズに比例（無制限成長に注意）

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

- キューの無制限成長によるメモリ枯渇に注意
- プロデューサーとコンシューマーの速度バランスが重要

## 備考

- APIはまだ実験的（Unstable API）
- 将来的にキューサイズ制限機能が追加される可能性

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | asyncstreams.nim | `lib/pure/asyncstreams.nim` | FutureStream型（19-27行目） |

**読解のコツ**:
- queue: Deque[T]でFIFOキューを実装
- finished: ストリーム完了フラグ
- cb: データ到着時のコールバック
- error: 例外情報

#### Step 2: 生成と完了を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | asyncstreams.nim | `lib/pure/asyncstreams.nim` | newFutureStream関数（29-43行目） |
| 2-2 | asyncstreams.nim | `lib/pure/asyncstreams.nim` | complete関数（45-50行目） |
| 2-3 | asyncstreams.nim | `lib/pure/asyncstreams.nim` | fail関数（52-58行目） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | asyncstreams.nim | `lib/pure/asyncstreams.nim` | write関数（85-98行目） |
| 3-2 | asyncstreams.nim | `lib/pure/asyncstreams.nim` | read関数（100-143行目） |

**主要処理フロー**:
- **85-98行目**: writeは即座にqueueに追加し、コールバックを呼び出す
- **100-143行目**: readはコールバックベースでキューからデータを取得

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

```
アプリケーションコード
    │
    ├─ newFutureStream[T]()
    │      └─ FutureStream初期化
    │
    ├─ write(value)
    │      ├─ queue.addLast(value)
    │      ├─ cb()呼び出し
    │      └─ Future[void].complete()
    │
    ├─ read()
    │      ├─ newFuture[(bool, T)]
    │      ├─ callback設定
    │      │      └─ queue.popFirst() or finished処理
    │      └─ Future[(bool, T)]返却
    │
    └─ complete()
           ├─ finished = true
           └─ cb()呼び出し
```

### データフロー図

```
[プロデューサー]          [FutureStream]           [コンシューマー]

write(val1) ────────▶ queue: [val1]
                            │
write(val2) ────────▶ queue: [val1, val2]
                            │
                            │ ◀──────────── read()
                            │                  │
                     queue: [val2]             ▼
                            │            (true, val1)
                            │
                            │ ◀──────────── read()
                            │                  │
                     queue: []                 ▼
                            │            (true, val2)
                            │
complete() ─────────▶ finished: true
                            │
                            │ ◀──────────── read()
                            │                  │
                            │                  ▼
                                         (false, default)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| asyncstreams.nim | `lib/pure/asyncstreams.nim` | メインソース | FutureStream実装 |
| asyncfutures.nim | `lib/pure/asyncfutures.nim` | 依存 | callSoon, Future関連 |
| deques.nim | `lib/pure/collections/deques.nim` | 依存 | Deque実装 |
| asyncdispatch.nim | `lib/pure/asyncdispatch.nim` | 利用元 | readAllなどで使用 |
| asyncfile.nim | `lib/pure/asyncfile.nim` | 利用元 | ファイルストリーミング |
