Coroutines on Android: from suspend to structured concurrency

A coroutine is a computation that can suspend at marked points and resume later, possibly on another thread; a thread is an OS resource that a coroutine runs on, and one thread can run many coroutines because a suspended coroutine holds no thread at all.

• Threads cost about a megabyte of stack and a kernel context switch; coroutines are heap objects that cost a few hundred bytes.
• Blocking holds the thread; suspending releases it.
• Which thread a coroutine resumes on is decided by its dispatcher.

An Android app's entire UI logic runs as coroutines on one main thread, and nothing freezes as long as none of them blocks.

It tells the compiler to turn the function into a state machine with a hidden continuation parameter, so the function can return early with a marker when it suspends and be re-entered later at the saved state.

• A suspend function can only be called where a continuation is available: another suspend function or a coroutine.
• Calls between suspension points run normally; nothing is asynchronous by itself.
• Two suspend calls in sequence run sequentially; parallelism needs async.

Decompiled, suspend fun f(): T becomes fun f(cont: Continuation<T>): Any? returning either a value or COROUTINE_SUSPENDED.

The function stores its locals and its position in the continuation, returns COROUTINE_SUSPENDED up the call chain so the thread is released, and later something calls resumeWith on the continuation, which the dispatcher schedules onto the right thread to continue from the saved label.

• Only calls to suspend functions can be suspension points.
• If the value is already available, no suspension happens and execution continues in place.
• Resumption goes through the dispatcher, which is a ContinuationInterceptor in the context.

This is why a callback fired on a background thread can resume a coroutine on Main: the interceptor re-dispatches the resume.

launch starts fire-and-forget work and returns a Job, throwing failures up the hierarchy immediately; async returns a Deferred whose value and exception surface at await; runBlocking blocks the calling thread until the coroutine and its children finish and belongs only in tests and main().

• An async failure still cancels a non-supervisor parent right away; only the rethrow waits for await.
• coroutineScope and withContext are scoping suspend functions, not builders.
• Never call runBlocking on the Android main thread: it is a guaranteed freeze.

Parallel decomposition is the textbook async use: two calls, awaitAll, total time equal to the slower one.

An indexed set of elements (Job, dispatcher, name, exception handler) combined with +; a child's context is the parent's context, overridden by whatever the builder was given, plus a new Job whose parent is the parent's Job.

• Same-key elements on the right win when combining.
• The Job is the one element never inherited as is; the new child Job is what makes structured concurrency work.
• coroutineContext is readable inside any suspend function.

launch(Dispatchers.IO + CoroutineName("sync")) keeps the parent's handler and Job link but runs on IO under a new name.

Main for anything touching the UI, IO for blocking calls that wait on disk or network, Default for CPU-bound work; and no dispatcher at all for calls that are already main-safe such as Retrofit and Room.

• IO is sized for waiting (64 threads or more); Default is sized for computing (one per core).
• Since 1.6 they share a pool, so switching between them is cheap.
• limitedParallelism(n) carves a bounded slice without a new pool.

CPU work on IO is the common mistake: 64 threads parsing JSON starve the file reads the dispatcher exists for.

It is the Main dispatcher that runs the coroutine immediately when the caller is already on the main thread instead of posting to the message queue; lifecycle scopes use it so that a launch from a click handler updates state in the same frame.

• Plain Dispatchers.Main always posts, which costs a frame and can reorder work.
• When called from a background thread, immediate behaves like Main.
• Both scopes combine it with a SupervisorJob.

This is also why the first _uiState.value = Loading in a launch is visible before the function returns.

withContext is a suspend function that runs its block on another dispatcher and returns the result to the caller, sequentially; launch starts a new concurrent coroutine and returns a Job without waiting.

• withContext is the tool for "do this part on IO, then continue here".
• launch is the tool for "start this and move on".
• withContext with the same dispatcher is nearly free; it still creates a child scope.

Replacing withContext(IO) with launch(IO) is a classic bug: the caller continues before the work is done.

New (only if lazy), then Active, then Completing while the body has finished but children still run, then Completed; or from Active or Completing to Cancelling on cancel or failure, then Cancelled once children and finally blocks are done.

• isActive is true in Active and Completing; isCancelled from Cancelling on.
• join waits without throwing; await on a Deferred rethrows.
• invokeOnCompletion gets the cause, null on success.

Completing is the state that shows a parent never finishes before its children.

That every coroutine has a parent scope, a scope does not complete until all its children have, cancelling a scope cancels everything inside it, and a child's failure is reported upward; no work is ever lost or orphaned.

• It is implemented by the parent-child links between Jobs.
• coroutineScope { } gives a suspend function a scope that waits for its own launches.
• GlobalScope is the one escape hatch, and it breaks every guarantee.

Cancelling viewModelScope in onCleared stopping every load on the screen is the guarantee in action.

coroutineScope when the children only make sense together, so one failure should cancel the rest and be reported to the caller; supervisorScope when the children are independent and each should fail alone.

• In coroutineScope, the exception is rethrown from the scope call.
• In supervisorScope, a failed launch child needs a handler or it crashes; a failed async child surfaces at await.
• Both wait for all children before returning.

A dashboard with five independent widgets is supervisorScope; fetching a user and their orders to build one object is coroutineScope.

It works as the Job of a scope, supervising the coroutines launched directly in that scope; passed as a parameter to launch it does nothing useful and actually detaches the coroutine from the scope's Job.

• CoroutineScope(SupervisorJob() + dispatcher) is the right shape.
• scope.launch(SupervisorJob()) { } makes a coroutine the scope can no longer cancel.
• Supervision applies only to direct children; grandchildren still fail their own parents normally.

viewModelScope is built exactly this way.

Cancelling a Job sets it to Cancelling and cancels its children, but the coroutine only stops when it next reaches a suspension point or checks its own state, which is why code must cooperate by suspending or checking.

• All kotlinx suspend functions check; a CPU loop needs ensureActive(), isActive or yield().
• Cancellation is delivered as a CancellationException so finally blocks run.
• A cancelled coroutine cannot suspend again except inside withContext(NonCancellable).

A loop that parses a big file without ever suspending will finish the file even after the user left the screen.

Because it is the signal that carries cancellation; a coroutine that catches it and continues is a zombie that keeps running after its scope was cancelled, holding resources and updating dead UI.

• catch (e: Exception) and runCatching both catch it.
• Rethrow it, or catch only the specific exceptions you expect.
• Timeouts use a subclass, so the same rule applies inside withTimeout blocks.

The usual fix is a two-line guard: if (e is CancellationException) throw e.

In a finally block wrapped in withContext(NonCancellable), because a cancelled coroutine throws on any further suspension unless it is inside a NonCancellable context.

• Non-suspending cleanup (closing a stream) works in a plain finally.
• Keep NonCancellable blocks short; nothing can stop them.
• use { } covers the common resource case.

Writing a draft to disk when the editor screen is cancelled is the typical example.

In a launch child the exception fails the child, cancels its siblings, fails the parent and climbs until a supervisor or the root, where a CoroutineExceptionHandler or the uncaught handler gets it; in an async child the same cancellation of a regular parent happens immediately, but the exception itself is stored and rethrown by await.

• Under a supervisor, a failing launch child needs a handler in its context.
• A root async never uses the handler; it waits for await.
• A try/catch inside the coroutine prevents the failure from ever reaching the Job.

The surprise for most people is that an un-awaited async in coroutineScope still takes the scope down.

Only where the exception stops climbing: in the context of a root coroutine's scope, or on a direct child of a supervisor; on a nested child of a regular Job it is ignored because the exception is passed to the parent instead.

• It is a last resort for logging, not a way to recover.
• It never applies to async.
• On Android, an unhandled root exception crashes the app.

Putting it in the application scope's constructor is the standard placement.

A cold flow's producer code runs from the start for every collector and does nothing without one; a hot flow exists and emits regardless of collectors, and collectors share what it holds.

• flow { }, Room queries and callbackFlow are cold.
• StateFlow, SharedFlow and channels are hot.
• stateIn and shareIn convert cold to hot inside a scope.

Two collectors on a cold Retrofit-backed flow make two network calls; two on a stateIn of it make one.

StateFlow holds one current value, requires an initial value and skips equal updates, so it models state; SharedFlow broadcasts every emission with a configurable replay and models events; LiveData is the older lifecycle-aware holder that StateFlow with repeatOnLifecycle replaces.

• StateFlow is a SharedFlow with replay 1, conflation and equality dedupe.
• LiveData is main-thread only with a handful of transformations; flows compose with the full operator set.
• A SharedFlow with no subscriber drops emissions unless it replays or buffers.

Google's guidance is StateFlow for state, with LiveData kept only for existing code.

It turns a cold flow into a StateFlow that starts collecting the upstream when the first subscriber appears and stops five seconds after the last one leaves; five seconds outlasts a configuration change but not a trip to the background.

• Eagerly would start at once and never stop; Lazily starts on first subscriber and never stops.
• The initial value is served until the upstream produces one.
• Rotation recreates the UI within the window, so the database query is not rerun.

Five seconds is the value Google recommends: comfortably longer than a configuration change, much shorter than a real stay in the background.

flowOn changes the dispatcher for everything upstream of it and nothing downstream; context preservation is the rule that a flow's emissions happen in the collector's context unless flowOn explicitly moves the upstream, so a flow may not emit from an arbitrary coroutine.

• Several flowOn calls each apply to their own upstream segment.
• flowOn inserts a buffer, so the producer can run ahead.
• callbackFlow and channelFlow exist for producers that emit from callbacks on other threads.

Room's flows already run their queries off the main thread, so they rarely need flowOn.

All three handle a producer that is faster than its collector: buffer queues values so the producer runs ahead, conflate keeps only the newest value and drops the rest, and collectLatest cancels the collector's block for the previous value when a new one arrives.

• Default flow behaviour is fully sequential: emit waits for collect to finish.
• conflate suits UI state; intermediate frames do not matter.
• collectLatest and flatMapLatest suit search-as-you-type.

StateFlow is conflated by design, which is why a burst of updates renders only the last one.

Preferably model them as state that the UI acknowledges; otherwise use a Channel exposed as receiveAsFlow(), which buffers events while nobody collects and delivers each exactly once, or a SharedFlow with a buffer when several listeners must see the event.

• A StateFlow would replay the event on rotation and navigate twice.
• A default SharedFlow drops the event when the UI is in the background.
• Collect events with repeatOnLifecycle(STARTED) so they are handled only while visible.

Google's current guidance leans toward the state approach, with the Channel pattern as the pragmatic alternative.

A Channel delivers each value to exactly one receiver and suspends the sender when its buffer is full, giving backpressure; a SharedFlow broadcasts each value to all current collectors and, by default, drops it when there are none.

• Channels are for work distribution and single-consumer events.
• SharedFlow is for fan-out.
• Both are hot; both are built on the same internals.

produce and receiveAsFlow are the two builders most Android code touches.

A CoroutineScope with SupervisorJob() + Dispatchers.Main.immediate, created lazily on first access and cancelled in onCleared(), which happens when the owner is finished for good, not on rotation.

• Supervisor: one failed load does not cancel the others.
• Main.immediate: state updates from the main thread land in the same frame.
• Work that must survive the screen needs another scope or WorkManager.

lifecycleScope is the same recipe cancelled at DESTROYED.

Because lifecycleScope is cancelled only on destroy, a direct collection keeps running while the screen is stopped, rendering to nothing and keeping upstream work alive; repeatOnLifecycle(STARTED) cancels the block when the lifecycle drops below STARTED and restarts it when it returns.

• Call it from viewLifecycleOwner in Fragments.
• flowWithLifecycle is the single-flow operator form.
• Paired with WhileSubscribed, the whole chain from database to screen sleeps in the background.

collectAsStateWithLifecycle is the Compose equivalent.

collectAsStateWithLifecycle for anything backed by real work, because it stops collecting below STARTED; collectAsState keeps collecting as long as the composable is in the composition, which on Android includes the whole time the app is in the background.

• It comes from lifecycle-runtime-compose.
• Default minimum state is STARTED, adjustable.
• Cheap in-memory flows can use either.

Google's Compose samples use the lifecycle variant everywhere.

Replace Dispatchers.Main with a test dispatcher through Dispatchers.setMain in a JUnit rule, inject any other dispatcher the ViewModel uses, run the test in runTest, and use advanceUntilIdle or Turbine to observe state.

• StandardTestDispatcher queues work so intermediate states can be asserted; UnconfinedTestDispatcher runs eagerly.
• Virtual time makes delay free.
• Hard-coded Dispatchers.IO is untestable; take dispatchers as constructor parameters.

Turbine's test { awaitItem() } is the cleanest way to assert a sequence of StateFlow values.

A main-safe suspend function can be called from the main thread without blocking it, because it moves any blocking work to the right dispatcher inside itself with withContext; callers never need to know.

• Retrofit and Room suspend functions are main-safe already.
• A repository wrapping a blocking file or SDK call wraps that call in withContext(Dispatchers.IO).
• The convention lets ViewModels launch on Main.immediate and stay simple.

If a caller has to add withContext(IO) around your function, the function was not main-safe.