Dart Stream ストリーム

Stream(ストリーム)は、Dart で連続的な非同期イベントシーケンスを処理する仕組みです。

Future が一回限りの非同期結果であるとすれば、Stream は複数回の、途切れることのない非同期データフローです。

この章では、Stream の概念、await for によるリッスン、StreamController による生成、そしてシングルサブスクリプションとブロードキャストストリームの違いを紹介します。


Stream とイベントシーケンス

Stream はまるでベルトコンベアのようなもので、データが時間の経過とともに次々に到着します。

すべてのデータを一括で待つ必要はなく、データが来るたびに処理します。

Stream の代表的なユースケース:

シーン例
ユーザー入力イベントボタンクリック、マウス移動、キーボード入力
ファイル読み込み大きなファイルを1行ずつ読み込む
ネットワークデータWebSocket メッセージ、リアルタイム API
タイマー毎秒1回トリガーされるタイマーイベント
状態変化Flutter における状態管理ストリーム

例

Stream の基本的な使い方——listen によるリッスン:

void main() {
  // Stream を作成: 1秒ごとに数字を発信する
  var stream = Stream<int>.periodic(
    Duration(seconds: 1),
    (count) => count + 1,  // count は 0 から始まる
  );

  print('Stream のリッスンを開始...');

  // listen で Stream を購読する
  var subscription = stream.listen(
    (data) {
      // 新しいデータが到着するたびに呼び出される
      print('サンプル データを受信: $data');
    },
    onError: (error) {
      // Stream でエラーが発生したときに呼び出される
      print('エラー: $error');
    },
    onDone: () {
      // Stream が閉じられたときに呼び出される
      print('Stream は閉じられました');
    },
  );

  // 5秒後に購読を解除する
  Future.delayed(Duration(seconds: 5), () {
    subscription.cancel();
    print('購読を解除しました');
  });
}
开始监听 Stream...
サンプル 收到数据: 1
サンプル 收到数据: 2
サンプル 收到数据: 3
サンプル 收到数据: 4
サンプル 收到数据: 5
已取消订阅

listen() は StreamSubscription オブジェクトを返します。これを使って購読を制御できます:

メソッド機能
subscription.pause()データの受信を一時停止する
subscription.resume()データの受信を再開する
subscription.cancel()購読を解除する
subscription.isPaused一時停止状態かどうか

await for によるリッスン

listen() のコールバック方式のほかに、await for ループを使って Stream を消費することもできます。

await for を使うと、Stream の処理ロジックが通常の for ループのように明確になります。

例

// 有限のデータストリームを生成する
Stream<int> countStream(int max) async* {
  for (int i = 1; i <= max; i++) {
    await Future.delayed(Duration(milliseconds: 300));
    yield i;  // yield でデータを Stream に発信する
  }
}

Future<void> main() async {
  print('await for で Stream の消費を開始...');

  // await for: 各データの到着を待ち、1つずつ処理する
  await for (var value in countStream(5)) {
    print('サンプル カウント: $value');
  }

  print('Stream の消費が完了しました');
}
开始用 await for 消费 Stream...
サンプル 计数: 1
サンプル 计数: 2
サンプル 计数: 3
サンプル 计数: 4
サンプル 计数: 5
Stream 消费完毕

await for の特徴:

  • 通常の for ループと書き方は似ていますが、各反復で次のデータの到着を待ちます
  • Stream が閉じられると、ループは自動的に終了します
  • async 関数内でのみ使用できます
  • 途中で抜けたい場合は break を使用します(通常の for ループと同じ)

await for は「すべてのデータを順番に処理する必要がある」シーンに適しています。例えば、ファイルの全行を読み込む場合です。listen() は「継続的にイベントに応答する必要がある」シーンに適しています。例えば、ボタンクリックの場合です。両者は互いに代替できますが、それぞれ得意な分野があります。


StreamController による Stream の生成

StreamController は、Stream を手動で作成・制御するためのツールです。

いつでもデータやエラーを追加したり、ストリームを閉じたりできます。

例

import 'dart:async';

// StreamController を使って簡単なカウントダウンタイマーを実装する
class CountdownTimer {
  final StreamController<int> _controller = StreamController<int>();
  Timer? _timer;
  int _remaining = 0;

  // Stream を外部に公開して購読できるようにする
  Stream<int> get tickStream => _controller.stream;

  // カウントダウンを開始
  void start(int seconds) {
    _remaining = seconds;

    // 初期値をすぐに送信
    _controller.add(_remaining);

    _timer = Timer.periodic(Duration(seconds: 1), (timer) {
      _remaining--;

      if (_remaining > 0) {
        _controller.add(_remaining);  // データを送信
      } else {
        _controller.add(0);           // 最後の 0 を送信
        _controller.close();          // Stream を閉じる
        timer.cancel();
      }
    });
  }

  // カウントダウンをキャンセル
  void cancel() {
    _timer?.cancel();
    _controller.addError('カウントダウンはキャンセルされました');  // エラーを送信
    _controller.close();
  }

  // リソースを解放
  void dispose() {
    _controller.close();
  }
}

Future<void> main() async {
  var timer = CountdownTimer();

  // カウントダウンイベントを購読
  timer.tickStream.listen(
    (remaining) {
      print('サンプル カウントダウン: $remaining 秒');
    },
    onError: (error) {
      print('エラー: $error');
    },
    onDone: () {
      print('カウントダウン終了!');
    },
  );

  timer.start(5);

  // カウントダウンの完了を待つ
  await Future.delayed(Duration(seconds: 6));
  timer.dispose();
}
サンプル 倒计时: 5 秒
サンプル 倒计时: 4 秒
サンプル 倒计时: 3 秒
サンプル 倒计时: 2 秒
サンプル 倒计时: 1 秒
サンプル 倒计时: 0 秒
倒计时结束!

async* ジェネレータ関数

単純にデータシーケンスを生成するだけであれば、async* のほうが StreamController より便利です。

例

// async* はこれが非同期ジェネレータ関数であることを示す
// 戻り値の型は Stream でなければならない
Stream<String> readLinesAsync() async* {
  var lines = ['最初の行', '2番目の行', '3番目の行', 'サンプル'];

  for (var line in lines) {
    await Future.delayed(Duration(milliseconds: 500));
    yield line;  // yield でデータを Stream に発信する
  }
  // 関数が終わると Stream は自動的に閉じられる
}

// エラー処理付きの非同期ジェネレータ
Stream<int> generateNumbersWithError() async* {
  for (int i = 1; i <= 5; i++) {
    await Future.delayed(Duration(milliseconds: 300));

    if (i == 3) {
      throw Exception('数字 3 でエラーが発生しました!');
    }
    yield i;
  }
}

Future<void> main() async {
  print('1行ずつ読み取り:');
  await for (var line in readLinesAsync()) {
    print('  $line');
  }

  print('\nエラー付きジェネレータ:');
  try {
    await for (var num in generateNumbersWithError()) {
      print(' 数字: $num');
    }
  } catch (e) {
    print(' エラーを捕捉: $e');
  }
}
逐行读取:
  第一行
  第二行
  第三行
  サンプル

带错误的生成器:
  数字: 1
  数字: 2
  捕获错误: Exception: 数字 3 出错了!

シングルサブスクリプション vs ブロードキャストストリーム

Dart の Stream には2つのタイプがあります:シングルサブスクリプションストリーム(Single-subscription)とブロードキャストストリーム(Broadcast)です。

シングルサブスクリプションストリーム(Single-subscription Stream)

これはデフォルトの Stream タイプです。

それは1つのリスナーのみが購読でき、「最初から最後まで1回だけ消費する」シーンに適しています。

例

void main() {
  // シングルサブスクリプションストリーム(デフォルト)
  var stream = Stream.fromIterable([1, 2, 3]);

  // 最初の購読:OK
  stream.listen((data) => print('購読者1: $data'));

  // 2番目の購読:エラー!シングルサブスクリプションストリームは複数回購読できない
  // stream.listen((data) => print('購読者2: $data')); // 実行時エラー
}

ブロードキャストストリーム(Broadcast Stream)

ブロードキャストストリームは複数のリスナーが同時に購読でき、イベントのブロードキャストシーンに適しています。

例

import 'dart:async';

void main() {
  // ブロードキャストストリームを作成する
  var controller = StreamController<int>.broadcast();

  // 複数の購読者が同時にリッスンできる
  controller.stream.listen(
    (data) => print('サンプル 購読者A: 受信 $data'),
  );

  controller.stream.listen(
    (data) => print('サンプル 購読者B: 受信 $data'),
  );

  // データを送信すると、両方の購読者が受け取る
  controller.add(1);
  controller.add(2);
  controller.add(3);

  // 遅れて購読しても以降のデータは受け取れる(ただし、以前のデータは受け取れない)
  Future.delayed(Duration(seconds: 1), () {
    controller.stream.listen(
      (data) => print('サンプル 遅れてきた購読者C: 受信 $data'),
    );
    controller.add(4);
    controller.close();
  });
}
サンプル 订阅者A: 收到 1
サンプル 订阅者B: 收到 1
サンプル 订阅者A: 收到 2
サンプル 订阅者B: 收到 2
サンプル 订阅者A: 收到 3
サンプル 订阅者B: 收到 3
サンプル 订阅者A: 收到 4
サンプル 订阅者B: 收到 4
サンプル 迟到的订阅者C: 收到 4

2つの Stream の比較:

特性シングルサブスクリプションストリームブロードキャストストリーム
購読者数1つのみ複数可
データのリプレイ最初から消費する購読後のデータのみ受け取る
代表的なシーンファイル読み込み、HTTP レスポンスボタンクリック、状態通知
作成方法StreamController()StreamController.broadcast()

ブロードキャストストリームの「遅れてきた購読者」は購読後のイベントのみ受け取れます。以前のイベントはすでに逃しています。これがブロードキャストストリームとシングルサブスクリプションストリームの最も重要な動作の違いです。


Stream のよく使う変換メソッド

Streamは、Listの関数型メソッドに似た、データを変換・処理するための一連のメソッドを提供します。

例

void main() async {
  var numbers = Stream.fromIterable([1, 2, 3, 4, 5, 6]);

  // map:各データを変換
  var doubled = numbers.map((n) => n * 2);
  print('2倍:');
  await for (var n in doubled) {
    print('  $n');
  }

  // where:データをフィルタリング
  var source = Stream.fromIterable([10, 15, 20, 25, 30]);
  var even = source.where((n) => n % 2 == 0);
  print('偶数:');
  await for (var n in even) {
    print('  $n');
  }

  // take:先頭のN個だけを取得
  var infinite = Stream.periodic(
    Duration(milliseconds: 100),
    (i) => i + 1,
  );
  print('先頭の3個だけ:');
  await for (var n in infinite.take(3)) {
    print('  サンプル: $n');
  }

  // skip:先頭のN個をスキップ
  var data = Stream.fromIterable([1, 2, 3, 4, 5]);
  print('先頭の2個をスキップ:');
  await for (var n in data.skip(2)) {
    print('  $n');
  }

  // distinct:重複を除去
  var duplicates = Stream.fromIterable([1, 2, 2, 3, 3, 3]);
  print('重複除去:');
  await for (var n in duplicates.distinct()) {
    print('  $n');
  }
}
翻倍:
  2
  4
  6
  8
  10
  12
偶数:
  10
  20
  30
只取前 3 个:
  サンプル: 1
  サンプル: 2
  サンプル: 3
跳过前 2 个:
  3
  4
  5
去重:
  1
  2
  3
その他の拡張