Flow

A Flow is a stream of values produced over time, one after another. Unlike a list, the values can arrive asynchronously without blocking. It is Kotlin's coroutine-based answer to reactive streams.

Cold means the flow does nothing until someone collects it. The producer code only runs when collect is called, and it runs fresh for each collector. No collector, no work.

A flow runs inside the coroutine that collects it. So it uses that coroutine's thread and lifecycle: if the collecting coroutine is cancelled, the flow stops too. Producer and consumer share one structured scope.

When the collector is slow, the producer's emit call simply suspends and waits. No values are dropped or buffered by default — the producer politely pauses until the collector is ready for the next value.

Building Flow on coroutines lets async stream code read like normal sequential code, with built-in cancellation and backpressure via suspension. The trade-off is that the default Flow lacks multicasting and needs adapters to talk to RxJava/Reactor.

flowOf takes a fixed set of values and wraps them in a Flow, emitting each one in order when you collect it. A list just holds values; a Flow streams them on demand.

flow { } makes a stream of values. Inside the block you call emit(value) to send each item. Nothing runs until someone collects it. A cold flow re-runs its code fresh for every collector.

A cold Flow does nothing on its own. The code inside it runs only when you collect it. Until someone collects, no values are produced and no work happens.

It means the code that produces values runs in the same place that collects them. By default, emit runs in the collector's coroutine, so the flow uses whatever context the collector started in.

asFlow() is an extension that turns something you already have — a list, sequence, or range — into a Flow that emits each element. Use it when the values live in a collection; use flowOf for literal values you type out.

zip waits for one new item from each flow and pairs them in lockstep. combine fires whenever either flow emits, using the newest value from the other flow.

Each emitted value can itself produce a flow. These operators flatten those inner flows into one stream. Concat runs them one after another, Merge runs them at the same time, Latest cancels the old inner flow when a new value comes.

A terminal operator is the function that actually starts a Flow running and consumes its values. Without one, nothing happens because Flows are lazy. Examples: collect and toList.

map turns each emitted value into a new value; filter keeps only values matching a condition. They do nothing until a terminal operator (like collect) runs the flow, and each collection re-runs the work.

Concat processes inner flows one at a time, so output keeps the input order. Merge processes several at once, so faster inner flows can finish first and outputs interleave. Merge lets you cap how many run together; the default is 16.

SharedFlow is a hot stream that broadcasts the same values to all collectors at the same time. A regular Flow is cold and re-runs its code separately for each collector.

Both turn a normal Flow that restarts for each collector into a shared one that runs once for everybody. shareIn gives a SharedFlow; stateIn gives a StateFlow that always has a current value.

StateFlow is a flow that always holds one current value you can read at any time through .value. A plain Flow holds nothing on its own and only produces values when someone collects it.

replay sets how many recent values new collectors get. extraBufferCapacity adds room for emitters when collectors are slow. onBufferOverflow decides what happens when both are full: suspend, drop oldest, or drop newest.

Eagerly starts the upstream right away and never stops. Lazily starts on the first collector and never stops. WhileSubscribed starts on the first collector and stops when the last one leaves, optionally after a timeout.

buffer() lets the part producing values and the part collecting them run at the same time instead of taking turns. Producers can race ahead into a small queue, so a slow collector no longer slows the producer.

collectLatest runs your handling code for each value, but if a new value arrives before the previous one finishes, it stops the previous work and starts on the new value. Plain collect always finishes every value first.

conflate() lets a fast producer skip ahead: if the collector is busy, in-between values are dropped and it only gets the newest one. Good when you only care about the latest value, like a live counter.

When the buffer fills up: SUSPEND pauses the producer until there is room (nothing lost); DROP_OLDEST throws away the oldest queued item to make space for the new one; DROP_LATEST throws away the new item and keeps what is already queued.

Cancellation only happens when the running code reaches a pause point. If your block does heavy non-stop computation, there's no pause point, so the old block keeps running. Add checks like ensureActive() or yield() so it can stop.

callbackFlow turns an old-style callback or listener API into a Flow. You use it when values arrive through a callback you register, not from suspending code you call directly.

channelFlow builds a cold Flow but lets you emit values from several coroutines at once using send(). The plain flow builder only lets you emit from one place, sequentially.

A Channel is like a queue that passes items between coroutines; each item is taken by one receiver. A Flow is a recipe that re-runs from the start for every collector. Channel is hot (always live); Flow is cold (starts when collected).

awaitClose keeps the flow alive until it is cancelled or closed, then runs cleanup like unregistering the listener. If you leave it out, the flow ends immediately and Kotlin throws an error.

flow { } requires that all emit() calls happen in the same coroutine, so emitting from a new coroutine breaks that rule and throws. channelFlow uses a channel and a thread-safe send(), so any coroutine can produce values.

catch runs when something fails earlier in the flow (upstream). It only catches errors from the parts above it, lets you log them, and can send a backup value instead of crashing.

onStart runs once right before a flow starts producing values. onCompletion runs once after the flow finishes, whether it ended normally, was cancelled, or threw an error.

retry re-subscribes to the flow when it fails with an error, trying again up to the given number of times before letting the error through.

Exception transparency means a flow must let downstream errors flow back out, not swallow them. So you should never put a try/catch around emit, because that would accidentally hide errors that really belong to the collector.

retryWhen runs a function each time the flow fails. You get the error and how many times it has already retried, and you return true to try again or false to give up.