In Dart, how does an `async*` function produce a stream with `yield` and `yield*`, and what happens to its body on pause and cancel?

## An asynchronous generator Marking a function body `async*` makes it an **asynchronous generator**: it returns a `Stream<T>` and produces that stream's events from ordinary-looking code. ```dart Stream<double> readings(Duration every) async* { final sensor = await Sensor.open(); try { while (true) { await Future.delayed(every); yield sensor.read(); } } finally { await sensor.close(); } } ``` Three keywords do the work: - **`yield value`** emits one data event. - **`yield* stream`** listens to another stream and forwards **all its events, data and errors**, until it closes; then execution continues after the `yield*`. - **`await`** works as in any `async` function, suspending until a future completes. ## Lazy start, unlike `async` An `async` function starts running synchronously as soon as it is called. An `async*` function does not: dart.dev states that **the stream is created when the function is called, and the body starts running when the stream is listened to**. So `final s = readings(oneSecond);` opens no sensor at all; the first `listen` or `await for` does. Each call returns a **new single-subscription stream** with its own run of the body. Two listeners on one returned stream are an error; two calls give two independent generators. ## How the stream ends 1. The body **returns** normally: the stream sends done. 2. The body **throws**, or an error arrives through `await for` inside it and is not caught: the error is **emitted** on the stream, which then **closes**. 3. The subscriber **cancels**: see below. ## Pause and cancel An `async*` function handles its subscriber's requests automatically, which is its main advantage over hand-written producers: | Subscriber does | Generator does | |---|---| | `pause()` | stops at the next `yield` until resumed, producing nothing meanwhile | | `resume()` | continues from that `yield` | | `cancel()` | the next `yield` acts as `return`: `finally` blocks run and the body exits | Details worth knowing: - Because the body stops at `yield` while paused, a paused generator does not build an ever-growing buffer. - After cancellation, a `yield` that would emit a value fails and acts as a return instead. - The `Future` returned by `subscription.cancel()` completes when the function has actually exited; if the body exits with an error, that future completes with the error. In the example, awaiting `cancel()` guarantees `sensor.close()` has finished. - Cleanup therefore belongs in `finally`, not after the loop, because a cancelled generator never reaches code after `while (true)`. ## `yield*` for composition `yield*` lets one generator delegate to another stream: ```dart Stream<double> calibrated(Stream<double> raw, double offset) async* { yield* raw.map((t) => t + offset); } Stream<double> session() async* { yield* readings(const Duration(seconds: 1)).take(3); yield double.nan; // marker after the first three readings } ``` Errors from the delegated stream are forwarded too, so a failure in `readings` reaches whoever listens to `session`. ## `async*` versus a hand-built producer dart.dev's guide to creating streams compares the two ways of producing events. An `async*` function **automatically pauses at a `yield`** while its subscription is paused, and stops at the next `yield` after a cancel. A producer built by hand with a controller, by contrast, **buffers** events during a pause unless it is written to honour the pause state, so a producer that ignores pauses can grow its buffer without limit. The generator is therefore the default for streams whose events come from the generator's own code, such as polling a sensor or reading lines. A hand-built producer is still needed when events are pushed in from outside, for example from callbacks, or when the stream must be broadcast from the start. ## Common mistakes - Expecting side effects before the first `listen`; the body has not started. - Putting cleanup after an infinite loop instead of in `finally`. - Listening twice to one returned stream instead of calling the function twice or sharing with `asBroadcastStream`. - Using `yield` with a stream value where `yield*` was intended, which emits the stream object as an event and does not compile when the element type is not a stream.