Recomposed
Coroutines

Kotlin Flow:メンタルモデル

Oct 25, 2026 · 13 min read

Kotlin Flow:メンタルモデル

直感的理解

Kotlin Flowは、Kotlinなりのへの取り組みだ。 が値をemitし、コンシューマーがそれをcollectする。flow { }は、すでにどこかで動いているプロデューサーの説明のように読める。 collect { }はコンシューマーとしてそこに接続するだけ、という印象だ。これはListやイベントバスから持ち込んだイメージであり、ある特定の点で間違っている。

  • のビルダーブロックは、実のところプロデューサーそのものであり、動いているプロセスではなく、レシピだ。コンシューマーがcollectするまで、その中身は何も実行されない。
  • .collect()を呼ぶと、そのレシピが最初から実行され、その1人のコンシューマーのためだけに値が作られる。同じFlowに対する2回目の.collect()は、プロデューサーを最初からもう一度、独立して実行する。
  • 2つのコンシューマーは1つの値のストリームを分け合うわけではない。それぞれが、あたかもそのFlowが今まで一度もcollectされたことがないかのように、自分専用のプロデューサーを最初から実行する。

これが、flow { }の中にあるネットワーク呼び出しやログ出力がコンシューマーごとに1回ずつ発火し、合計1回ではない理由だ。Flowが生み出す「あれ、なぜこれが2回実行されたんだ」というバグ報告の中で最も多いパターンである。

デフォルトはコールド:ビルダーはコンシューマーごとに再実行される

val userRequests = flow {
    println("Starting network call")
    emit(api.fetchUser())
}
 
userRequests.collect { println("Collector A got $it") }
userRequests.collect { println("Collector B got $it") }
Starting network call
Collector A got User(...)
Starting network call
Collector B got User(...)

「Starting network call」は1回ではなく2回出力される。userRequestsは結果を保持する値ではなく、レシピを保持するFlowオブジェクトだ。それぞれの.collect()呼び出しは、そのレシピの新しい実行であり、自分専用のapi.fetchUser()呼び出しと自分専用のemissionを持ち、もう一方のコンシューマーの存在にはまったく気づいていない。

同じバグ、より現実的な形

上のおもちゃのような例は、printlnがあるおかげで明らかに間違っているように見える。しかし同じ仕組みは、Flowが1〜2層下に埋もれているときに、実際の重複ネットワーク呼び出しバグを引き起こす。

// ❌ リポジトリがコールドなFlowをそのまま公開している
class UserRepository {
    fun observeUser(id: String): Flow<User> = flow {
        emit(api.fetchUser(id)) // コレクターごとに再実行される
    }
}
 
// 2つのcomposableが、同じ呼び出し箇所のFlowをそれぞれcollectし、
// それぞれが独立して自分の api.fetchUser(id) 呼び出しをトリガーする
@Composable
fun ProfileHeader(repo: UserRepository, id: String) {
    val user by repo.observeUser(id).collectAsState(initial = null)
    // ...
}
 
@Composable
fun ProfileDetails(repo: UserRepository, id: String) {
    val user by repo.observeUser(id).collectAsState(initial = null)
    // ...
}

ここには、ひと目でバグに見えるものは何もない。observeUser(id)は「現在のユーザーを教えてくれ」というふうに読め、getterと同じ形をしている。実際には「ユーザーを取得するためのレシピを教えてくれ」であり、2人の呼び出し元がいれば2つのレシピが実行され、2回のネットワーク呼び出しが発生する。一見1つの状態に見えるものに対して、である。

根本原理

これはコールドストリーム対ホットストリームのセマンティクスだ。コールドストリームのプロデューサーは、コンシューマーがsubscribeするまで何も作業をせず、subscribeするたびに最初から最後まで独立したプロデューサーが用意される。ホットストリームのプロデューサーは、特定のコンシューマーの有無とは無関係に、すでに動いている(あるいはすでに現在値を保持している)。そして、どのコンシューマーも新しいプロデューサーを開始するのではなく、その同じ進行中のプロデューサーに接続する。

Kotlin Flowはデフォルトでコールドだ。StateFlowとSharedFlowは、以下で扱う、意図的なホットの例外である。

他のフレームワークでも:同じ根本原理、違うフレームワーク

  • RxJava/RxKotlin:Observable.create { }は同じ意味でコールドであり、subscribe()のたびにemitterブロック全体が再実行される。PublishSubjectとBehaviorSubjectはホットの逃げ道であり、subscriberが再起動するのではなく接続する、動いているパイプだ。
  • Combine(Swift/SwiftUI):普通のPublisherはコールドであり、.share()や.multicast()を挟まない限り、新しいsubscriberごとにupstreamを再実行する。CurrentValueSubjectとPassthroughSubjectはCombineのホットなプリミティブであり、CurrentValueSubjectはStateFlowにほぼそのまま対応する。どちらも常に現在値を保持し、新しいsubscriberにそれを即座に渡す。
  • JavaScriptの非同期ジェネレーター / ReadableStream:同じルールでコールドであり、ジェネレーター関数を(あるいはstreamをpipeで)2回目に呼び出すと、最初から再実行される。EventTarget/EventEmitterはホットだ。何もlistenしていなくても発火し、後から来たlistenerは、すでに起きたことを単に見逃す。
  • Androidの旧LiveData:構造上ホットであり、コールドなビルダーブロックに相当するものは存在しない。すべてのobserverは、すでに生きている同じ値ホルダーにattachする。これが、LiveDataからFlowへの移行で人々が戸惑う理由の一部だ。LiveDataに対して築いたメンタルモデルは、素のflow { }には存在しないホットなセマンティクスを前提にしている。

ホットの例外:StateFlowとSharedFlow

StateFlowとSharedFlowはコンシューマーごとにビルダーを再実行しない。再実行すべきビルダーがそもそも存在しないからだ。何かが1か所から1回だけ、MutableStateFlow.value = xやMutableSharedFlow.emit(x)を呼び出し、すべてのコンシューマーがその同一の単一の更新ストリームを観測する。

class UserViewModel(private val repo: UserRepository) : ViewModel() {
    private val _uiState = MutableStateFlow<User?>(null)
    val uiState: StateFlow<User?> = _uiState.asStateFlow()
 
    init {
        viewModelScope.launch {
            _uiState.value = repo.observeUser(id).first() // ここで1回だけ実行される
        }
    }
}

uiStateをcollectするすべての画面は、同じ値を同じタイミングで更新して受け取る。プロデューサー(上のviewModelScope.launch)がちょうど1つしか存在せず、uiStateはその現在値を映す窓にすぎないからだ。これがStateFlowのすべてだ。conflate(結合)されており(新しいコンシューマーは過去すべての再生ではなく、即座に最新の値を受け取る)、自分自身で完了することはない。

SharedFlowはより汎用的なバージョンであり、StateFlowの固定された「常に最新値だけ」の代わりに、設定可能なreplayカウントを持ち、現在値を保持する必要すらない。StateFlowは、replay = 1と初期値を持ったSharedFlowである。

コールドなFlowを意図的にホットにする:stateIn/shareIn

先ほどのリポジトリのバグには実際の修正方法があり、それは「Flowを使うな」ではなく「コールドなものをshareせよ」だ。

class UserViewModel(repo: UserRepository, id: String) : ViewModel() {
    val user: StateFlow<User?> = repo.observeUser(id)
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = null,
        )
}

stateInはobserveUser(id)のコールドなレシピをちょうど1回、viewModelScopeの中で実行し、その結果をすべてのコンシューマーが共有するStateFlowとして公開する。先ほどの例のProfileHeaderとProfileDetailsは、今度は同じuserをcollectすることになり、両者の背後にapi.fetchUser(id)呼び出しがちょうど1回だけ存在する。

SharingStarted.WhileSubscribed(5_000)は、共有されたプロデューサーが実際にいつ動くかを決める部分だ。最初のコンシューマーが現れたら開始し、最後のコンシューマーが離脱してから5秒間は生かし続け(これにより、クイックな設定変更による再生成が再起動を招かないようにする)、それでも誰もlistenしていなければ停止して破棄する。Eagerlyは即座に開始し、決して停止しない。Lazilyは最初のコンシューマーで開始するが、一度開始したら停止しない。いずれの場合もコールドからホットへの変換は同じで、「共有された実行がいつ始まりいつ終わるか」という問いへの答えが異なるだけだ。

よく使うオペレーター一覧

以下はいずれも、上記のデフォルトでコールドというルールを変えるものではなく、より複雑なレシピにすぎない。コールドなFlowをcombineやflatMapLatestで包んでも、それがホットになるわけではない。合成/マップされたFlowは、何かがstateIn/shareInでそれをshareしない限り、コンシューマーごとにチェーン全体を再実行し続ける。

は、まさにこの問いを指す:プロデューサーがコンシューマーより速いとき、Flowは何をするのか。「いつまでも待つ」が常に正しい答えとは限らないからだ。

オペレーターカテゴリ動作
map / filter変換Sequence/Listと同様、emissionを1つずつ変形または除外する
combine複数のflowの結合いずれかのソースがemitするたびに、各ソースの最新値から再計算する
zip複数のflowの結合各ソースのn番目のemissionをペアにする。すべての側がemitするまでペアを作らずに待つ
merge複数のflowの結合複数のソースからのemissionを、到着順にそのまま1つにインターリーブする
flatMapLatest新しいflowへの切り替えouterのFlowがemitするたびに、前のinner Flowをキャンセルして新しいものに切り替える
flatMapConcat新しいflowへの切り替えinner flowを順番に1つずつ実行し、重複させない
flatMapMerge新しいflowへの切り替えinner flowを並行して実行し、それぞれのemissionをインターリーブする
debounceレート制限静かな間隔が過ぎるまでemissionを捨て、最後の1つだけをemitする
distinctUntilChangedレート制限新しいemissionが、実際に最後にemitされた値と等しければ捨てる
bufferバックプレッシャープロデューサーをすぐにsuspendさせるのではなく、固定サイズのバッファに先行して流し込む。onBufferOverflowが、そのバッファが満杯になったときの動作を決める
conflateバックプレッシャーbuffer(capacity = 0, onBufferOverflow = BufferOverflow.DROP_OLDEST)の短縮形:実質的なバッファは持たず、常に最新値だけを保持し、コンシューマーが処理できていないものは捨てる
catchエラーハンドリングコンシューマーをキャンセルすることなく、upstreamの例外をキャッチする

bufferは、conflateがその1つの固定設定にすぎないダイヤルだ。buffer(capacity = 1, onBufferOverflow = BufferOverflow.DROP_OLDEST)は1つの保留中の値を保持し、新しい値が来たら前の値を捨てる。これはまさにconflate()が短い名前の下で行っていることだ。1つの値より大きなウィンドウが欲しいとき、あるいは最も古いものを捨てる代わりにBufferOverflow.DROP_LATEST/SUSPENDを使いたいときは、直接bufferを選ぶとよい。

実際のコードでコールドな再実行バグを最もよく隠すのはcombineだ。

// ❌ combineは2つのコールドなflowをラップするが、どちらも自分のレシピを
// コレクターごとに再実行する。つまり2つの画面が同じ2つのリポジトリ
// flowをcombineすると、裏側のフェッチは2回ではなく4回になる
val summary = combine(repo.observeUser(id), repo.observeOrders(id)) { user, orders ->
    Summary(user, orders)
}
 
// ✅ combineした結果を1回だけshareし、すべてのコレクターが
// 自分の実行を始めるのではなく、同じ1つのcombineの実行に接続するようにする
val summary = combine(repo.observeUser(id), repo.observeOrders(id)) { user, orders ->
    Summary(user, orders)
}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)

よくある間違い

catchは、チェーンの中で自分より上流でthrowされた例外しか見えない

flow {
    emit(1)
    throw RuntimeException("boom")
}
.catch { e -> emit(-1) } // ✅ catchが上のthrowをキャッチできるのは、catchがそれより下流にあるから
.map { value ->
    if (value == 1) throw RuntimeException("boom downstream")
    value
}
.collect { println(it) }
// それでもクラッシュする:2つ目のthrowはチェーンの中でcatchより
// *後*で起きるので、catchには見えない。catchはレシピの中の
// 単なるコールドなリンクで、collection全体を囲むグローバルなtry/catchではない。

人はcatchが、パイプライン中のどこで起きたものでもキャッチする、周囲を囲むtry/catchブロックのように振る舞うことを期待してしまう。しかし実際はそうではない。catchはmap/filterと同じコールドなチェーンの中にある通常のリンクであり、それより上流(flow { }ビルダーに近い側)で何かがthrowした例外だけをキャッチする。それより後に配置されたオペレーターがthrowしたものは決してキャッチしない。すべてを上から見てキャッチしたいなら、catchはcollectの直前の最後のリンクに置くこと。

間違ったCoroutineContextからemitすると「Flow invariant is violated」でクラッシュする

// ❌ withContextをビルダーの中に置くとemit()が実行されるcontextが変わり、
// Flowのcontext保存の保証を破ってしまう
flow {
    withContext(Dispatchers.IO) {
        emit(api.fetchUser()) // 実行時にIllegalStateException
    }
}
 
// ✅ flowOnはupstreamの作業をIOに移すが、emit()が
// flow { }が作られたcontextとは別のcontextで実行されることはない
flow {
    emit(api.fetchUser())
}.flowOn(Dispatchers.IO)

flow { }ビルダーは、emit()が常にコンシューマーがいるのと同じCoroutineContextで実行されることを保証する。そのため、コンシューマーは、collectしたものの途中で別のdispatcherに密かに移動していないと信頼できる。emit()自体をwithContextで囲むと、この保証が破られ、例外がthrowされる。正しい道具はflowOnだ。flowOnは自分よりupstreamのすべてを指定したdispatcherに移動させるだけで、それをcollectする側に対するemit()のcontext保存の約束はそのまま保たれる。

StateFlowは、現在の値と構造的に等しい値を再emitしない

data class UiState(val items: List<Item>)
 
val _state = MutableStateFlow(UiState(items = mutableListOf()))
 
// ❌ 同じリストをその場でmutateし、同じ参照を再代入する:
// 構造的に古い値と等しいので、何もemitされない
_state.value.items as MutableList
(_state.value.items as MutableList).add(newItem)
_state.value = _state.value // no-op:コレクターはnewItemを決して見ない
 
// ✅ 本当に新しい値なので、equals()が差分を検知してemitされる
_state.value = _state.value.copy(items = _state.value.items + newItem)

StateFlowはconflateされている。.valueの代入は、新しい値が現在の値とequals()でない場合にのみコンシューマーにemitされる。保持しているコレクションをその場でmutateして同じ参照を再代入する方法は、更新に見えるが、StateFlowから見れば参照自体は何も変わっていないため、更新とはみなされない。これが、StateFlowの周りでイミュータブルなデータクラスとcopy()が単なるスタイルの好みではなく慣習になっている理由だ。

awaitCloseを忘れるとcallbackFlowは即座にクラッシュする

は、まさに素のflow { }では表現できないAPIのために存在する。位置情報プロバイダーやViewのクリックリスナーのように、直接emit()させてくれるのではなく、コールバック/リスナー経由で値を渡してくるものだ。これも依然として内部ではコールドなFlowであり、同じflow { }の形で構築されていて、emissionの代わりに登録されたコールバックが立っているだけだ。

// ❌ コールバックを登録した直後にブロックがreturnしてしまい、
// suspension pointがない:callbackFlowはこれをバグとみなしてthrowする
fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
    val callback = object : LocationCallback() {
        override fun onLocationResult(result: LocationResult) {
            trySend(result.lastLocation)
        }
    }
    client.requestLocationUpdates(callback)
    // IllegalStateException: callbackFlowブロックが終了したが
    // channelは一度も閉じられていないので、上のコールバックを
    // 解除できる決定論的な瞬間が残っていない
}
 
// ✅ awaitCloseはコレクターがキャンセルする(あるいはchannelが
// 別の方法で閉じられる)までsuspendし、これがコールバックを
// 解除できる唯一の安全な場所でもある
fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
    val callback = object : LocationCallback() {
        override fun onLocationResult(result: LocationResult) {
            trySend(result.lastLocation)
        }
    }
    client.requestLocationUpdates(callback)
    awaitClose { client.removeLocationUpdates(callback) }
}

callbackFlowの契約全体は、登録したコールバックを後片付けするための、決定論的な瞬間を1つ持つことを前提に組み立てられている。ブロックが自分だけで戻ってしまえるなら、そうした瞬間は存在せず、コールバックはずっと登録されたままで、誰もそれを解除できないままリークしてしまう。そこでcallbackFlowはこの契約を実行時に強制する。ブロックはsuspension pointで終わらなければならず、ほぼ常にawaitClose { }を使う必要があり、そうでなければ黙ってリークするのではなく例外をthrowする。

callbackFlowもコールドであり、つまりコールバックはコンシューマーごとに再登録される

fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
    val callback = object : LocationCallback() {
        override fun onLocationResult(result: LocationResult) {
            trySend(result.lastLocation)
        }
    }
    client.requestLocationUpdates(callback) // コレクターごとに再登録される
    awaitClose { client.removeLocationUpdates(callback) }
}

コールバックをcallbackFlowで包んでも、デフォルトでコールドという性質から逃れるわけではない。これもやはり同じflow { }形のレシピから作られている。2人のコンシューマーがいれば、OSに対して2つの別々の位置情報リスナーが登録され、それぞれが自分のコンシューマーのキャンセルによって独立して解除される。修正方法は上と同じだ。位置情報データを欲しい画面ごとにlocationUpdates()を自分で呼ばせるのではなく、どの1コンシューマーよりも長生きするスコープで一度だけshareInすること。

Flowには.valueがなく、StateFlowにはある。片方で済ませようとするところにもう片方を使うのは、起こるのを待っている型エラーだ

素のFlow<T>は同期的に読むことができない。collectするまで何も実行されないので、読み取るべき現在値がそもそも存在しない。StateFlow<T>は常にそれを持っている。汎用的にFlow<T>パラメータを取るが実際には.valueを必要とするコードは、その関数が、保証されていないホットなセマンティクスを暗黙に前提にしていたことのサインだ。

Flowはすでに値を運んでいるパイプではなく、レシピである。デフォルトでコールドであり、collect()のたびに独自のコピーが再実行される。そしてStateFlow/SharedFlow(あるいはコールドなFlowの上にかけるstateIn/shareIn)は、それを1回だけ実行し、全員でその結果を共有する、という意図的なオプトインである。

Keep reading

Related reads

新しい記事をメールで受け取る