Skip to content
AppDues
Log in
Contact salesSign up

Kotlin Flow, StateFlow and SharedFlow Internals

Flow looks small from the outside: one suspending collect function. The interesting engineering is underneath, in how context is protected, how hot streams buffer values, and how StateFlow keeps a single value consistent across concurrent updates. This guide walks through those mechanisms and turns them into choices you can apply when picking a stream type or buffer policy.

Why Flow is a cold stream with hard guarantees

A Flow emits values in sequence, but two rules shape its behavior. Context preservation means the flow carries its own execution context and does not leak it downstream, so an emission cannot quietly move to another dispatcher. Exception transparency means a failed emission stops the flow and propagates the error, so error handling stays local and predictable.

These are runtime rules, not style advice. The supplied code module code0001 shows a flow builder that tries to switch context with withContext(Dispatchers.IO) around an emit; collecting it produces java.lang.IllegalStateException: Flow invariant is violated. The same module shows that emitting inside coroutineScope remains valid because the coroutine context is unchanged.

Because Flow is cold, each collection starts a new execution. That is why the interface can stay minimal and why operators can be composed without hidden shared state.

The Flow interface and the SafeCollector guardrail

The Flow interface exposes a single suspending function, collect(collector). The recommended implementation path is AbstractFlow, which wraps each collector in a SafeCollector. That wrapper is the enforcer: it compares the current coroutine context with the collector's context and throws IllegalStateException when they differ.

The supplied code module code0002 shows the minimal interface, and code0003 shows AbstractFlow allocating a SafeCollector and releasing it in a finally block. The emit path in code0004 records a DownstreamExceptionContext when an emission throws, which is how the flow preserves exception transparency.

A useful distinction: a context violation is a programming error and fails fast. A full buffer under a suspending overflow policy is normal backpressure and makes the emitter wait. Treating these as the same failure leads to confusing retries.

Hot streams: what SharedFlow changes

SharedFlow is a broadcast mechanism. It shares emitted values among active collectors and keeps emitting whether or not anyone is listening, although its behavior adapts when there are no subscribers. Its collect function returns Nothing, which signals that a SharedFlow never completes on its own; collection runs until it is cancelled.

The interface in code0005 also exposes replayCache, the list of values a new collector receives immediately. That single property explains much of the design: SharedFlow has to retain values for late subscribers while also managing collectors that fall behind.

Inside the SharedFlow circular buffer

SharedFlowImpl manages a circular array that logically holds three regions: the replay cache that new collectors receive, buffered values available to current collectors, and queued emitters that are suspended waiting for slow collectors. The supplied code module code0006 documents those regions and the invariants that keep the indices consistent.

The array is always a power of two, so index lookup uses a bitwise AND instead of division. The supplied code module code0007 shows getBufferAt and setBufferAt applying index.toInt() and (size - 1). This is a deliberate allocation and CPU trade-off: the buffer grows in powers of two and wraps without shifting elements.

When you size a replay cache, remember that replay values are part of this same structure. A large replay cache is not free; it keeps values reachable for new collectors.

Slot allocation and collector positions

Both StateFlow and SharedFlow track active collectors through slots managed by AbstractSharedFlow. The supplied code module code0008 shows the slot array, the collector count and a nextIndex oracle. Allocation in code0009 reuses free slots, doubles the array when full, and starts searching from the remembered next index.

For SharedFlow, each slot also stores the collector's position in the buffer. The supplied code module code0010 shows a SharedFlowSlot with an index field and a continuation for a waiting collector. When a value is emitted, SharedFlow checks slots and resumes those whose index is behind the buffer.

This design favors allocation reuse over complex indexing. Slots are never destroyed, only marked free, which keeps churn low when collectors subscribe and unsubscribe repeatedly.

Emission paths and buffer overflow behavior

tryEmit runs in two phases: it updates state under a lock, then resumes continuations outside the lock. The supplied code module code0011 shows that pattern, and code0012 shows the branch that decides what happens when the buffer is full. With BufferOverflow.SUSPEND, tryEmit returns false and the emitter must suspend. DROP_LATEST returns true and discards the incoming value. DROP_OLDEST forces an enqueue and drops the oldest value.

When there are no collectors, SharedFlow takes a fast path. The supplied code module code0013 shows that if replay is zero the value is simply forgotten; otherwise only the replay cache is maintained. In that state, overflow strategies do not apply, and the behavior is effectively DROP_OLDEST with a buffer equal to replay.

If tryEmit returns false, emit suspends. The supplied code module code0014 stores the suspended emitter in the buffer as an Emitter object, and code0015 shows how those emitters are later resumed and their values moved into the buffer. Queued emitters live in the same circular array as values, which keeps buffer management unified.

StateFlow as a constrained SharedFlow

StateFlow is a SharedFlow with a fixed shape: it always has exactly one value and uses equality-based conflation. The supplied code module code0016 shows MutableStateFlow constructing a StateFlowImpl, and code0017 shows the atomic _state plus a sequence counter that serializes updates.

The update protocol in code0018 is flat combining. An even sequence means the state is quiescent. The first updater makes it odd and takes responsibility for applying updates. A concurrent updater increments the sequence by two and returns; the first updater notices the change and loops again. This batches rapid updates into a single pass over collectors.

StateFlow slots are simpler than SharedFlow slots because there is only one value to track. The supplied code module code0019 shows four slot states: null for free, NONE for allocated but idle, PENDING for a value waiting to be collected, and a CancellableContinuationImpl for a suspended collector. Transitions use compare-and-swap operations, so makePending does not block even while the StateFlow lock is held.

Collection in code0020 compares oldState and newState and skips emission when they are equal. That is the distinct-until-changed behavior. The loop first calls takePending for a fast path and only suspends through awaitPending when no value is pending; code0021 shows the race-safe await.

Why subscriptionCount is not a plain StateFlow

Both SharedFlow and StateFlow expose subscriptionCount, but the implementation is a SharedFlow pretending to be a StateFlow. The supplied code module code0022 shows SubscriptionCountStateFlow extending SharedFlowImpl with replay 1, a very large buffer capacity and BufferOverflow.DROP_OLDEST.

The reason is conflation. If subscriptionCount were a regular StateFlow, a sequence of 0 to 1 to 0 could collapse to 0, and listeners would never see the intermediate 1. The supplied code module code0023 gives the library's own example: a shared flow started with SharingStarted.Lazily, where first() sees the initial value and immediately unsubscribes, leaving the asynchronous start with a conflated zero. Using a SharedFlow with DROP_OLDEST and an unlimited buffer delivers every subscription change, which SharingStarted strategies need.

A practical check: if you are building a counter or event stream where intermediate values matter, do not assume StateFlow semantics. StateFlow is for current state, not for every transition.

Collector index management and resumption

The most intricate part of SharedFlow is updating collector indices when a collector advances or frees its slot. The supplied code module code0024 shows updateCollectorIndexLocked doing several things under one lock: recomputing minCollectorIndex, calculating freed buffer space, resuming queued emitters, updating replayIndex, minCollectorIndex, bufferSize and queueSize, and resuming waiting collectors. Continuations are resumed after the lock is released to avoid deadlocks.

This is the mechanism that connects backpressure to buffer state. A slow collector holds minCollectorIndex back; when it catches up, space opens and suspended emitters can move their values into the buffer.

Performance trade-offs and a selection checklist

The implementation makes pragmatic choices. StateFlow updates are O(N) in the number of collectors because every update iterates all slots to call makePending. SharedFlow emissions are also O(N) because finding slots to resume requires a scan. For typical collector counts, a linear scan is faster and simpler than maintaining a heap or skip list.

The design also prioritizes allocation reduction over raw CPU efficiency: the circular buffer, slot reuse and flat combining all avoid churn, which matters on a garbage-collected JVM. Synchronization uses locks rather than pure lock-free algorithms; uncontended locks are cheap, and the complex lock-free alternatives would be harder to maintain. Resuming continuations outside the lock is a recurring pattern because resumed code can run arbitrary user logic.

Use this checklist when choosing a stream type:

  • Need a new execution per collector and a completion signal? Use cold Flow.
  • Need to broadcast to many collectors with a replay cache? Use SharedFlow and size replay deliberately.
  • Need a single current value with equality conflation? Use StateFlow.
  • Need every subscription transition, including 0 to 1 to 0? Do not use a plain StateFlow; the subscriptionCount design shows why.
  • Expect slow collectors and a bounded buffer? Choose SUSPEND if the emitter can wait, or DROP_OLDEST if the newest value matters more than the oldest.
  • Need to observe completion? SharedFlow collect returns Nothing, so plan cancellation explicitly.

Frequently asked questions

What is the difference between a cold Flow and a hot SharedFlow?

A cold Flow starts a new execution for each collector and can complete. A SharedFlow broadcasts values to active collectors and its collect function returns Nothing, so it does not complete on its own; collection continues until cancelled.

Why does StateFlow skip equal values?

StateFlow uses equality-based conflation. During collection it compares the previous state with the new state and emits only when they differ, which gives distinct-until-changed behavior.

When does SharedFlow suspend an emitter?

When the buffer is full and the overflow policy is BufferOverflow.SUSPEND, tryEmit returns false and emit suspends. The suspended emitter is stored in the buffer and resumed when space becomes available.

Why is subscriptionCount implemented as a SharedFlow?

A plain StateFlow would conflate a sequence such as 0 to 1 to 0 into 0, hiding the intermediate subscription. The SharedFlow-based implementation with DROP_OLDEST and an unlimited buffer delivers every change, which SharingStarted strategies rely on.

private class SubscriptionCountStateFlow(initialValue: Int) : StateFlow<Int>,
    SharedFlowImpl<Int>(1, Int.MAX_VALUE, BufferOverflow.DROP_OLDEST)
{
    init { tryEmit(initialValue) }

    override val value: Int
        get() = synchronized(this) { lastReplayedLocked }

    fun increment(delta: Int) = synchronized(this) {
        tryEmit(lastReplayedLocked + delta)
    }
}