Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Kotlin concurrency and Flow
Core principle
Give asynchronous work an explicit owner and lifetime, then model durable state and transient events with primitives whose delivery and replay semantics match the product contract.
Procedure
- Identify each coroutine owner, cancellation boundary, producer, consumer,
durable state, and transient event.
- Before changing an API, compare its existing caller-visible contract with
the required owner and lifetime. If a suspend API already gives its caller cancellation, result, and failure ownership, finish with no change; do not add a scope, launch, callback, or deferred wrapper merely for convenience.
- Select a scope whose lifecycle owns the work; do not retain arbitrary scopes
or hide unstructured launches behind non-suspending APIs.
- Model renderable, current data as state and imperative one-shot work as an
event only when its loss and replay behavior are explicitly acceptable. For a one-consumer navigation handoff that must survive a collector gap, choose a buffered Channel exposed as receiveAsFlow(); do not preserve a replay-zero SharedFlow after identifying event loss as the defect.
- Choose Flow sharing and buffering semantics from the producer and consumer
lifetimes rather than from a default.
- Read the focused reference for the material concern below.
- Finish when cancellation, restart, replay, and failure behavior are all
observable from the public API and no caller must guess who owns the work.
Topic router
| Signal | Read |
|---|---|
Stored CoroutineScope, raw Thread or Executor work, init { launch }, fire-and-forget API, runBlocking, broad catch, or cancellation boundary | Structured concurrency |
StateFlow, SharedFlow, Channel, stateIn, SharingStarted, .value, state updates, sentinel values, or one-shot events | Flow state and events |
| Compose collection or UI effect handling | Compose state and effects |
