Dart Streamクラスdrain()メソッド

Dart Streamクラスのdrain()メソッドについてメモ書き。

drain()は全Streamイベントを破棄し、完了通知(doneイベント)をするメソッド。
drain()を使うとcancelOnErrorが有効となり、エラー発生時点でサブスクリプションがキャンセルされる。
drain()の戻り値はFuture<E>で、オプション引数(省略可)で戻り値を指定する。drain()完了時にdoneイベント共に指定した値が返される。

それではコーディングで確認。
動きを理解するために、先ずはdrain()を使わないケースを見てみる。

void main() {
  final stream = () async* {
    List<String> str = ["Data:a", "Data:b"];
    for (String s in str) {
      yield s;
    }
  }()
      .asBroadcastStream();

  stream.listen(
    ((event) => print(event)),
    onDone: () => print("Done"),
  );
}

実行結果。
str配列の要素を出力後、Streamイベント完了時に実行されるonDone:が処理されていることが分かる。

Data:a
Data:b
Done

次はlisten()前にdrain()を実行する。

void main() async {
  final stream = () async* {
    List<String> str = ["Data:a", "Data:b"];
    for (String s in str) {
      yield s;
    }
  }()
      .asBroadcastStream();
  await stream.drain("drain").then(print);
  stream.listen(
    ((event) => print(event)),
    onDone: () => print("Done"),
  );
}

実行結果。
drain()実行でstr配列の要素が破棄されたことが分かる。

drain
Done

それでは以下ケースの場合はどうなるか？予想して欲しい。

void main() async {
  final listTest =
      Stream.fromIterable(["Apple", "Orange", "Banana", "pineapple"]);

  await listTest.drain("drain").then(print);

  listTest.listen(
    (print),
    onDone: () => print("Done"),
  );
}

実行結果。

drain
Apple
Orange
Banana
pineapple
Done

drain()を実行しているのだから、listTest配列のデータは出力されないように思われるが、fromIterableはコンストラクなので、listTest.listen()を実行したタイミングで新しいストリームが作成され、値が出力される。