L'intuition
Kotlin Flow est la vision de Kotlin de la :
un
émet des valeurs, un consommateur les collecte. flow { } se lit comme
la description d'un producteur déjà présent, en cours d'exécution, et
collect { } ne ferait que s'y brancher en tant que consommateur. C'est
l'image que les gens transposent depuis une List ou un bus d'événements,
et elle est fausse d'une manière bien spécifique.
- Le bloc du builder d'un est le producteur, et ce n'est pas un processus en cours d'exécution, c'est une recette. Rien à l'intérieur ne s'exécute avant qu'un consommateur ne le collecte.
- Appeler
.collect()exécute cette recette depuis le début, produisant des valeurs pour ce seul consommateur. Un second.collect()sur le mêmeFlowréexécute le producteur, depuis le début, indépendamment. - Deux consommateurs ne se partagent pas un seul flux de valeurs. Chacun
obtient son propre producteur, exécuté depuis le début, comme si le
Flown'avait jamais été collecté auparavant.
C'est pourquoi un appel réseau ou une ligne de log à l'intérieur d'un
flow { } se déclenche une fois par collecteur, pas une fois au total,
le rapport de bug « attends, pourquoi ça s'est exécuté deux fois » le
plus courant que produit Flow.
Froid par défaut : le builder se réexécute par collecteur
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 » s'affiche deux fois, pas une. userRequests
n'est pas une valeur contenant un résultat, c'est un objet Flow
contenant une recette. Chaque appel à .collect() est une nouvelle
invocation de cette recette, avec son propre appel à api.fetchUser()
et sa propre émission, totalement inconsciente de l'existence de
l'autre collecteur.
Le même bug, sous une forme plus réaliste
L'exemple jouet ci-dessus a l'air manifestement faux parce que le
println le trahit. Le même mécanisme cause de vrais bugs d'appels
réseau dupliqués lorsque le Flow est enfoui une ou deux couches plus
bas :
// ❌ le repository expose directement un Flow froid
class UserRepository {
fun observeUser(id: String): Flow<User> = flow {
emit(api.fetchUser(id)) // se réexécute pour chaque collecteur
}
}
// Deux composables, chacun collectant le Flow du même point d'appel, chacun
// déclenchant son propre appel indépendant à 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)
// ...
}Rien ici n'a l'air d'un bug à première vue. observeUser(id) se lit
comme « donne-moi l'utilisateur actuel », la même forme qu'un getter.
C'est en réalité « donne-moi une recette pour récupérer l'utilisateur »,
et deux appelants signifient deux recettes exécutées, deux appels
réseau, pour ce qui ressemble à un seul morceau d'état.
Le fondamental
C'est la sémantique flux froid vs. flux chaud. Le producteur d'un flux froid n'effectue aucun travail avant qu'un consommateur ne s'abonne, et chaque abonnement obtient son propre producteur indépendant, du début à la fin. Le producteur d'un flux chaud est déjà en cours d'exécution (ou détient déjà une valeur actuelle) indépendamment de tout consommateur particulier, et chaque consommateur se branche sur ce même producteur en cours plutôt que d'en démarrer un nouveau.
Kotlin Flow est froid par défaut. StateFlow et SharedFlow sont
l'exception chaude délibérée, couverte plus bas.
Ailleurs : même fondamental, framework différent
- RxJava/RxKotlin :
Observable.create { }est froid de la même manière, chaquesubscribe()réexécute tout le bloc émetteur.PublishSubjectetBehaviorSubjectsont les échappatoires chaudes, un tuyau en cours d'exécution auquel les abonnés se branchent plutôt que de le redémarrer. - Combine (Swift/SwiftUI) : un simple
Publisherest froid, réexécutant son amont pour chaque nouvel abonné à moins d'insérer.share()ou.multicast().CurrentValueSubjectetPassthroughSubjectsont les primitives chaudes de Combine, etCurrentValueSubjectcorrespond presque exactement àStateFlow: les deux détiennent toujours une valeur actuelle et la transmettent immédiatement à chaque nouvel abonné. - Générateurs async/
ReadableStreamen JavaScript : froids selon la même règle, appeler la fonction génératrice (ou brancher le stream) une seconde fois le réexécute depuis le début. UnEventTarget/EventEmitterest chaud : il se déclenche peu importe si quelque chose écoute, et les écouteurs tardifs manquent simplement ce qui s'est déjà produit. - L'ancien
LiveDatad'Android : chaud par construction, il n'y a pas d'équivalent à un bloc de builder froid, chaque observateur se rattache au même détenteur de valeur déjà vivant. C'est en partie pourquoi migrer deLiveDatavers Flow déroute les gens : le modèle mental qu'ils avaient construit pourLiveDatasuppose une sémantique chaude qu'un simpleflow { }n'a pas.
L'exception chaude : StateFlow et SharedFlow
StateFlow et SharedFlow ne réexécutent pas un builder par
collecteur, parce qu'il n'y a pas de builder à réexécuter. Quelque chose
appelle MutableStateFlow.value = x ou MutableSharedFlow.emit(x)
exactement une fois, depuis un seul endroit, et chaque collecteur
observe ce même flux unique de mises à jour.
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() // s'exécute une fois, ici
}
}
}Chaque écran qui collecte uiState voit la même valeur, mise à jour
aux mêmes moments, parce qu'il y a exactement un producteur
(viewModelScope.launch ci-dessus) et que uiState n'est qu'une
fenêtre sur sa valeur actuelle. C'est tout l'intérêt de StateFlow :
il est conflaté (les nouveaux collecteurs obtiennent immédiatement la
dernière valeur, pas une relecture de toutes celles passées) et il ne
se termine jamais de lui-même.
SharedFlow est la version plus générale : un nombre de replay
configurable au lieu du « toujours exactement la dernière valeur » fixe
de StateFlow, et aucune obligation de détenir une valeur actuelle.
StateFlow est un SharedFlow avec replay = 1 et une valeur initiale.
Transformer délibérément un Flow froid en flux chaud : stateIn/shareIn
Le bug de repository évoqué plus haut a une vraie solution, et ce n'est
pas « n'utilisez pas Flow », c'est « partagez celui qui est froid » :
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 exécute la recette froide de observeUser(id) exactement une
fois, à l'intérieur de viewModelScope, et expose le résultat sous
forme de StateFlow que tous les collecteurs partagent.
ProfileHeader et ProfileDetails de l'exemple précédent
collecteraient désormais le même user, avec exactement un appel à
api.fetchUser(id) derrière les deux.
SharingStarted.WhileSubscribed(5_000) est le détail qui décide quand
le producteur partagé s'exécute réellement : le démarrer dès que le
premier collecteur apparaît, le maintenir en vie 5 secondes après le
départ du dernier collecteur (pour qu'une rapide rotation de
changement de configuration ne le redémarre pas), puis l'arrêter et le
détruire si plus personne n'écoute. Eagerly le démarre immédiatement
et ne s'arrête jamais ; Lazily démarre au premier collecteur mais ne
s'arrête jamais une fois lancé. Même conversion froid-vers-chaud dans
les deux cas, juste une réponse différente à « quand l'exécution
partagée commence-t-elle et se termine-t-elle ».
Opérateurs courants en un coup d'œil
Aucun de ceux-ci ne change la règle du froid-par-défaut ci-dessus, ce
sont juste des recettes plus élaborées. Envelopper un Flow froid dans
combine ou flatMapLatest ne le rend pas chaud, le Flow
combiné/transformé réexécute toujours toute sa chaîne par collecteur à
moins que quelque chose ne le partage avec stateIn/shareIn.
La
ci-dessous est précisément cette question : que fait un Flow quand le
producteur est plus rapide que le collecteur, puisque « attendre
indéfiniment » n'est pas toujours la bonne réponse.
| Opérateur | Catégorie | Ce qu'il fait |
|---|---|---|
map / filter | Transformation | Remodèle ou abandonne les émissions une par une, comme Sequence/List |
combine | Combiner plusieurs flows | Recalcule à partir de la dernière valeur de chaque source dès que l'une d'elles émet |
zip | Combiner plusieurs flows | Associe la n-ième émission de chaque source ; attend que chaque côté émette avant de produire une paire |
merge | Combiner plusieurs flows | Entrelace les émissions de plusieurs sources en une seule, dans l'ordre d'arrivée |
flatMapLatest | Basculer vers un nouveau flow | Annule le Flow interne précédent et bascule vers un nouveau chaque fois que le Flow externe émet |
flatMapConcat | Basculer vers un nouveau flow | Exécute les flows internes un par un, dans l'ordre, jamais en chevauchement |
flatMapMerge | Basculer vers un nouveau flow | Exécute les flows internes simultanément, en entrelaçant leurs émissions |
debounce | Limitation de débit | Abandonne les émissions jusqu'à ce qu'un intervalle calme passe, puis n'émet que la dernière |
distinctUntilChanged | Limitation de débit | Abandonne une nouvelle émission si elle est égale à la dernière réellement émise |
buffer | Pression contre-amont | Fait tourner le producteur en avance sur un collecteur lent dans un tampon de taille fixe, au lieu de le suspendre immédiatement ; onBufferOverflow décide de ce qui se passe une fois ce tampon plein |
conflate | Pression contre-amont | Raccourci pour buffer(capacity = 0, onBufferOverflow = BufferOverflow.DROP_OLDEST) : pas de vrai tampon, on garde toujours la dernière valeur et on abandonne ce que le collecteur n'a pas encore traité |
catch | Gestion des erreurs | Rattrape une exception en amont sans annuler le collecteur |
buffer est le cadran dont conflate n'est qu'un réglage fixe :
buffer(capacity = 1, onBufferOverflow = BufferOverflow.DROP_OLDEST)
conserve une valeur en attente et abandonne la précédente dès qu'une
nouvelle valeur arrive, ce qui est exactement ce que fait conflate()
sous un nom plus court. Choisissez buffer directement à la place
quand vous voulez une fenêtre plus large qu'une seule valeur, ou
BufferOverflow.DROP_LATEST/SUSPEND au lieu d'abandonner la plus
ancienne.
combine est celui qui cache le plus souvent un bug de réexécution à
froid dans la pratique :
// ❌ combine enveloppe deux flows froids ; les deux réexécutent toujours leur propre recette
// par collecteur, donc deux écrans combinant les mêmes deux flows de
// repository signifient QUATRE récupérations sous-jacentes, pas deux
val summary = combine(repo.observeUser(id), repo.observeOrders(id)) { user, orders ->
Summary(user, orders)
}
// ✅ partagez le résultat combiné une seule fois, pour que chaque collecteur se branche sur
// la même exécution unique de combine au lieu d'en démarrer une à lui
val summary = combine(repo.observeUser(id), repo.observeOrders(id)) { user, orders ->
Summary(user, orders)
}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)Erreurs courantes
catch ne voit que les exceptions levées au-dessus de lui dans la chaîne
flow {
emit(1)
throw RuntimeException("boom")
}
.catch { e -> emit(-1) } // ✅ rattrape le throw au-dessus, puisque catch se trouve en dessous
.map { value ->
if (value == 1) throw RuntimeException("boom downstream")
value
}
.collect { println(it) }
// Plante malgré tout : le second throw survient *après* catch dans la chaîne,
// donc catch ne le voit jamais. catch n'est qu'un autre maillon froid de la recette,
// pas un try/catch global autour de toute la collecte.Les gens se tournent vers catch en s'attendant à ce qu'il se comporte
comme un bloc try/catch englobant, rattrapant tout, n'importe où dans
le pipeline. Ce n'est pas le cas. catch est un maillon ordinaire dans
la même chaîne froide que map/filter, donc il ne rattrape qu'une
exception levée par quelque chose en amont de lui (plus proche du
builder flow { }), jamais quelque chose levé par un opérateur placé
après lui. Placez catch comme dernier maillon avant collect si vous
voulez qu'il voie tout ce qui se trouve au-dessus.
Émettre depuis le mauvais CoroutineContext plante avec « Flow invariant is violated »
// ❌ withContext à l'intérieur du builder change le contexte dans lequel emit() s'exécute,
// ce qui brise la garantie de préservation de contexte de Flow
flow {
withContext(Dispatchers.IO) {
emit(api.fetchUser()) // IllegalStateException à l'exécution
}
}
// ✅ flowOn déplace le travail en amont vers IO sans que emit() ne s'exécute jamais
// dans un contexte différent de celui dans lequel flow { } a été construit
flow {
emit(api.fetchUser())
}.flowOn(Dispatchers.IO)Un builder flow { } garantit que emit() s'exécute toujours dans le
même CoroutineContext que le collecteur, de sorte qu'un collecteur
puisse faire confiance au fait que rien de ce qu'il collecte ne s'est
glissé sur un autre dispatcher en plein milieu du flux. Appeler
withContext autour de emit() lui-même brise cette garantie et lève
une exception. flowOn est l'outil correct : il déplace tout ce qui
est en amont de lui vers le dispatcher donné, tout en laissant
intacte la promesse de préservation de contexte de emit() pour
quiconque le collecte.
StateFlow ne réémet pas une valeur structurellement égale à l'actuelle
data class UiState(val items: List<Item>)
val _state = MutableStateFlow(UiState(items = mutableListOf()))
// ❌ muter la même liste sur place, puis réassigner la même
// référence : structurellement égale à l'ancienne valeur, donc rien n'émet
_state.value.items as MutableList
(_state.value.items as MutableList).add(newItem)
_state.value = _state.value // ne fait rien, les collecteurs ne voient jamais newItem
// ✅ une valeur véritablement nouvelle, donc equals() voit une différence et émet
_state.value = _state.value.copy(items = _state.value.items + newItem)StateFlow est conflaté : assigner .value n'émet vers les
collecteurs que si la nouvelle valeur n'est pas equals() à
l'actuelle. Muter une collection détenue sur place et réassigner la
même référence ressemble à une mise à jour mais n'en est pas une pour
StateFlow, puisque rien dans la référence n'a réellement changé.
C'est la même raison pour laquelle les data classes immuables et
copy() sont la convention autour de StateFlow, pas une préférence
de style.
Oublier awaitClose fait planter callbackFlow immédiatement
Le
existe précisément pour les API qu'un simple flow { } ne peut pas
exprimer : quelque chose qui vous transmet des valeurs via un
callback/listener au lieu de vous laisser emit() directement, comme
un fournisseur de localisation ou le listener de clic d'une View.
C'est quand même un Flow froid en dessous, construit de la même
manière que flow { }, juste avec un callback enregistré qui tient
lieu d'émissions.
// ❌ le bloc retourne juste après avoir enregistré le callback, sans
// point de suspension : callbackFlow considère cela comme un bug et lève une exception
fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
val callback = object : LocationCallback() {
override fun onLocationResult(result: LocationResult) {
trySend(result.lastLocation)
}
}
client.requestLocationUpdates(callback)
// IllegalStateException : le bloc callbackFlow s'est terminé, mais le
// channel n'a jamais été fermé, donc il n'y a aucun moment déterministe
// restant pour désenregistrer le callback ci-dessus
}
// ✅ awaitClose suspend jusqu'à ce que le collecteur annule (ou que le channel
// soit fermé d'une autre manière), ce qui est aussi le seul endroit sûr pour
// désenregistrer le callback
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) }
}Tout le contrat de callbackFlow repose sur le fait d'avoir un moment
déterministe unique pour nettoyer le callback qu'il a enregistré. Si
le bloc peut se terminer de lui-même, il n'y a pas un tel moment, le
callback fuirait simplement, enregistré pour toujours sans plus rien
capable de le désenregistrer. Donc callbackFlow impose le contrat au
moment de l'exécution : le bloc doit se terminer par un point de
suspension, presque toujours awaitClose { }, sinon il lève une
exception au lieu de fuir silencieusement.
callbackFlow est froid aussi, ce qui signifie que le callback se réenregistre par collecteur
fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
val callback = object : LocationCallback() {
override fun onLocationResult(result: LocationResult) {
trySend(result.lastLocation)
}
}
client.requestLocationUpdates(callback) // réenregistré pour chaque collecteur
awaitClose { client.removeLocationUpdates(callback) }
}Envelopper un callback dans callbackFlow ne le fait pas échapper au
froid-par-défaut, c'est toujours construit à partir de la même recette
en forme de flow { }. Deux collecteurs enregistrent deux listeners de
localisation séparés auprès de l'OS, chacun détruit indépendamment à
l'annulation de son propre collecteur. La correction est la même que
ci-dessus : partagez-le avec shareIn une seule fois dans un scope qui
survit à n'importe quel collecteur unique, au lieu de laisser chaque
écran qui veut des données de localisation appeler
locationUpdates() lui-même.
Flow n'a pas de .value, StateFlow oui, et se tromper de l'un pour l'autre est une erreur de type qui attend de se produire
Un simple Flow<T> ne peut pas être lu de manière synchrone, il n'y a
pas de valeur actuelle à lire puisque rien ne s'exécute avant que vous
ne le collectiez. StateFlow<T> en a toujours une. Un code qui prend
génériquement un paramètre Flow<T> mais a en réalité besoin de
.value est un signe que la fonction a silencieusement supposé une
sémantique chaude qui n'était jamais garantie.
Un Flow est une recette, pas un tuyau qui transporte déjà des
valeurs : froid par défaut, chaque collect() réexécute sa propre
copie indépendante, et StateFlow/SharedFlow (ou stateIn/shareIn
au-dessus d'un Flow froid) sont l'adhésion délibérée à l'exécuter une
fois et laisser tout le monde partager le résultat.



