A intuição
O Kotlin Flow é a visão do Kotlin sobre :
um
emite valores, um consumidor os coleta. flow { } se lê como uma
descrição de um produtor que já está lá fora, em execução, e
collect { } apenas se conecta a ele como o consumidor. Essa é a imagem que as pessoas
carregam de uma List ou de um barramento de eventos, e está errada de uma forma específica.
- O bloco construtor de um é o produtor, e não é um processo em execução, é uma receita. Nada dentro dele executa até que um consumidor o colete.
- Chamar
.collect()executa essa receita do início, produzindo valores para aquele único consumidor. Um segundo.collect()no mesmoFlowexecuta o produtor novamente, do zero, de forma independente. - Dois consumidores não dividem um único stream de valores entre si. Cada um
recebe seu próprio produtor, executado do zero, como se o
Flownunca tivesse sido coletado antes.
É por isso que uma chamada de rede ou uma linha de log dentro de um flow { } dispara uma vez por
coletor, não uma vez no total — o relato de bug mais comum "espera, por que isso executou
duas vezes" que o Flow produz.
Frio por padrão: o construtor é executado novamente por coletor
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" é impresso duas vezes, não uma. userRequests não é um
valor que contém um resultado, é um objeto Flow que contém uma receita. Cada
chamada .collect() é uma nova invocação dessa receita, com sua própria
chamada api.fetchUser() e sua própria emissão, completamente inconsciente de que o outro
coletor existe.
Mesmo bug, uma forma mais realista
O exemplo de brinquedo acima parece obviamente errado porque o println o denuncia. O mesmo mecanismo causa bugs reais de chamadas de rede duplicadas quando o
Flow está enterrado uma ou duas camadas abaixo:
// ❌ o repositório expõe um Flow frio diretamente
class UserRepository {
fun observeUser(id: String): Flow<User> = flow {
emit(api.fetchUser(id)) // executa novamente para cada coletor
}
}
// Dois composables, cada um coletando o Flow do mesmo ponto de chamada, cada
// um disparando sua própria chamada independente de 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)
// ...
}Nada aqui parece um bug à primeira vista. observeUser(id) se lê como
"me dê o usuário atual", a mesma forma de um getter. Na verdade é "me dê
uma receita para buscar o usuário", e dois chamadores significam duas receitas executadas,
duas chamadas de rede, para o que parece ser um único pedaço de estado.
O fundamento
Isso é semântica de stream frio vs. quente. O produtor de um stream frio não faz nenhum trabalho até que um consumidor se inscreva, e cada inscrição recebe seu próprio produtor independente, do início ao fim. O produtor de um stream quente já está em execução (ou já mantém um valor atual) independentemente de qualquer consumidor específico, e cada consumidor se conecta a esse mesmo produtor em andamento em vez de iniciar um novo.
O Kotlin Flow é frio por padrão. StateFlow e SharedFlow são a
exceção quente deliberada, abordada abaixo.
Em outros lugares: mesmo fundamento, framework diferente
- RxJava/RxKotlin:
Observable.create { }é frio da mesma forma, cadasubscribe()executa novamente todo o bloco emissor.PublishSubjecteBehaviorSubjectsão as válvulas de escape quentes, um canal em execução que os assinantes acessam em vez de reiniciar. - Combine (Swift/SwiftUI): um
Publishersimples é frio, reexecutando seu upstream para cada novo assinante, a menos que você insira.share()ou.multicast().CurrentValueSubjectePassthroughSubjectsão os primitivos quentes do Combine, eCurrentValueSubjectmapeia quase exatamente paraStateFlow: ambos sempre mantêm um valor atual e o entregam a cada novo assinante imediatamente. - Geradores assíncronos do JavaScript /
ReadableStream: frios pela mesma regra, chamar a função geradora (ou canalizar o stream) uma segunda vez a executa novamente desde o início. UmEventTarget/EventEmitteré quente: ele dispara independentemente de haver algo ouvindo, e ouvintes tardios apenas perdem o que já aconteceu. - O antigo
LiveDatado Android: quente por construção, não há equivalente a um bloco construtor frio, cada observador se conecta ao mesmo detentor de valor já ativo. Isso é parte do motivo pelo qual migrar deLiveDatapara Flow confunde as pessoas: o modelo mental que elas construíram paraLiveDataassume semântica quente que umflow { }simples não tem.
A exceção quente: StateFlow e SharedFlow
StateFlow e SharedFlow não executam um construtor novamente por coletor, porque
não há construtor para executar novamente. Algo chama MutableStateFlow.value = x
ou MutableSharedFlow.emit(x) exatamente uma vez, de um só lugar, e cada
coletor observa esse mesmo único stream de atualizações.
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() // executa uma vez, aqui
}
}
}Toda tela que coleta uiState vê o mesmo valor, atualizado nos mesmos
momentos, porque há exatamente um produtor (viewModelScope.launch
acima) e uiState é apenas uma janela para seu valor atual. Essa é toda
a essência do StateFlow: ele é conflacionado (novos coletores recebem imediatamente
o valor mais recente, não uma reprodução de todos os anteriores) e nunca completa
por conta própria.
SharedFlow é a versão mais geral: contagem de replay configurável
em vez do "sempre exatamente o valor mais recente" fixo do StateFlow, e nenhuma
exigência de que ele mantenha um valor atual sequer. StateFlow é um
SharedFlow com replay = 1 e um valor inicial.
Transformando um Flow frio em um quente de propósito: stateIn/shareIn
O bug do repositório de antes tem uma correção real, e não é "não use
Flow", é "compartilhe o que é frio":
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 executa a receita fria de observeUser(id) exatamente uma vez, dentro
de viewModelScope, e expõe o resultado como um StateFlow que cada
coletor compartilha. ProfileHeader e ProfileDetails do exemplo
anterior agora coletariam o mesmo user, com exatamente uma
chamada api.fetchUser(id) por trás de ambos.
SharingStarted.WhileSubscribed(5_000) é o detalhe que decide quando
o produtor compartilhado realmente é executado: iniciá-lo quando o primeiro coletor
aparece, mantê-lo vivo 5 segundos além da saída do último coletor (para que uma
rotação rápida de mudança de configuração não o reinicie), depois parar e
desmontá-lo se nada mais estiver ouvindo. Eagerly o inicia imediatamente
e nunca para; Lazily inicia no primeiro coletor, mas nunca para uma vez
iniciado. A mesma conversão de frio para quente de qualquer forma, apenas uma resposta diferente
para "quando a execução compartilhada começa e termina".
Operadores comuns em resumo
Nenhum destes muda a regra de frio-por-padrão acima, eles são apenas
receitas mais elaboradas. Envolver um Flow frio em combine ou flatMapLatest
não o torna quente, o Flow combinado/mapeado ainda executa toda sua
cadeia novamente por coletor, a menos que algo o compartilhe com stateIn/shareIn.
abaixo é exatamente essa questão: o que um Flow faz quando o produtor
é mais rápido que o coletor, já que "esperar para sempre" nem sempre é a resposta
certa.
| Operador | Categoria | O que faz |
|---|---|---|
map / filter | Transformação | Remodela ou descarta emissões uma a uma, igual a Sequence/List |
combine | Combinar múltiplos flows | Recalcula a partir do valor mais recente de cada fonte sempre que qualquer uma delas emite |
zip | Combinar múltiplos flows | Pareia a n-ésima emissão de cada fonte; espera cada lado emitir antes de produzir um par |
merge | Combinar múltiplos flows | Intercala emissões de múltiplas fontes em uma só, na ordem em que chegam |
flatMapLatest | Trocar para um novo flow | Cancela o Flow interno anterior e troca para um novo cada vez que o Flow externo emite |
flatMapConcat | Trocar para um novo flow | Executa flows internos um por vez, em ordem, nunca se sobrepondo |
flatMapMerge | Trocar para um novo flow | Executa flows internos concorrentemente, intercalando suas emissões |
debounce | Limitação de taxa | Descarta emissões até passar um intervalo de silêncio, depois emite apenas a mais recente |
distinctUntilChanged | Limitação de taxa | Descarta uma nova emissão se ela for igual à última realmente emitida |
buffer | Backpressure | Executa o produtor adiante de um coletor lento em um buffer de tamanho fixo, em vez de suspendê-lo imediatamente; onBufferOverflow decide o que acontece quando esse buffer enche |
conflate | Backpressure | Atalho para buffer(capacity = 0, onBufferOverflow = BufferOverflow.DROP_OLDEST): sem buffer real, apenas sempre mantém o valor mais recente e descarta o que o coletor não alcançou |
catch | Tratamento de erros | Captura uma exceção upstream sem cancelar o coletor |
buffer é o controle do qual conflate é uma configuração fixa: buffer(capacity = 1, onBufferOverflow = BufferOverflow.DROP_OLDEST) mantém um valor pendente
e descarta o anterior quando um novo valor chega, que é exatamente o que
conflate() faz com um nome mais curto. Escolha buffer
diretamente quando quiser uma janela maior que um valor, ou
BufferOverflow.DROP_LATEST/SUSPEND em vez de descartar o mais antigo.
combine é o que mais frequentemente esconde um bug de reexecução a frio na prática:
// ❌ combine envolve dois flows frios; ambos ainda executam novamente sua própria receita
// por coletor, então duas telas combinando os mesmos dois flows
// do repositório significam QUATRO buscas subjacentes, não duas
val summary = combine(repo.observeUser(id), repo.observeOrders(id)) { user, orders ->
Summary(user, orders)
}
// ✅ compartilhe o resultado combinado uma vez, para que cada coletor acesse
// a mesma única execução do combine em vez de iniciar a sua própria
val summary = combine(repo.observeUser(id), repo.observeOrders(id)) { user, orders ->
Summary(user, orders)
}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)Erros comuns
catch só vê exceções lançadas acima dele na cadeia
flow {
emit(1)
throw RuntimeException("boom")
}
.catch { e -> emit(-1) } // ✅ captura o throw acima, já que catch está abaixo dele
.map { value ->
if (value == 1) throw RuntimeException("boom downstream")
value
}
.collect { println(it) }
// Mesmo assim crasha: o segundo throw acontece *depois* do catch na cadeia,
// então catch nunca o vê. catch é só mais um elo frio na receita,
// não um try/catch global em torno de toda a coleta.As pessoas recorrem a catch esperando que se comporte como um bloco
try/catch ao redor, capturando qualquer coisa em qualquer lugar do pipeline. Não é assim.
catch é um elo comum na mesma cadeia fria que map/filter, então
ele só captura uma exceção lançada por algo upstream a ele (mais perto
do construtor flow { }), nunca algo lançado por um operador colocado
depois dele. Coloque catch como o último elo antes de collect se quiser que ele
veja tudo acima.
Emitir do CoroutineContext errado causa crash com "Flow invariant is violated"
// ❌ withContext dentro do construtor muda o contexto em que emit() executa,
// o que quebra a garantia de preservação de contexto do Flow
flow {
withContext(Dispatchers.IO) {
emit(api.fetchUser()) // IllegalStateException em tempo de execução
}
}
// ✅ flowOn move o trabalho upstream para IO sem que emit() jamais execute
// em um contexto diferente daquele em que flow { } foi construído
flow {
emit(api.fetchUser())
}.flowOn(Dispatchers.IO)Um construtor flow { } garante que emit() sempre executa no mesmo
CoroutineContext em que o coletor está, para que um coletor possa confiar que
nada que ele coleta se infiltrou em um dispatcher diferente no meio do stream. Chamar
withContext em torno do próprio emit() quebra essa garantia e lança uma exceção.
flowOn é a ferramenta correta: ele move tudo upstream dele para o
dispatcher dado, deixando intacta a promessa de preservação de contexto do emit()
para quem o coletar.
StateFlow não reemite um valor estruturalmente igual ao atual
data class UiState(val items: List<Item>)
val _state = MutableStateFlow(UiState(items = mutableListOf()))
// ❌ mutando a mesma lista no local, depois reatribuindo a mesma
// referência: estruturalmente igual ao valor antigo, então nada emite
_state.value.items as MutableList
(_state.value.items as MutableList).add(newItem)
_state.value = _state.value // no-op, coletores nunca veem newItem
// ✅ um valor genuinamente novo, então equals() vê uma diferença e emite
_state.value = _state.value.copy(items = _state.value.items + newItem)StateFlow é conflacionado: atribuir .value só emite para coletores se
o novo valor não for equals() ao atual. Mutar uma coleção mantida
no local e reatribuir a mesma referência parece uma atualização, mas não é
uma, até onde o StateFlow pode saber, já que nada sobre a referência realmente mudou.
Esse é o mesmo motivo pelo qual data classes imutáveis e copy() são a convenção
em torno do StateFlow, não uma preferência de estilo.
Esquecer awaitClose crasha o callbackFlow imediatamente
existe exatamente para as APIs que um flow { } simples não consegue expressar: algo
que entrega valores por meio de um callback/listener em vez de permitir
emit() diretamente, como um provedor de localização ou o listener de clique de uma View.
Ainda é um Flow frio por baixo, construído da mesma forma do flow { },
apenas com um callback registrado representando as emissões.
// ❌ o bloco retorna logo após registrar o callback, sem
// nenhum ponto de suspensão: callbackFlow trata isso como um bug e lança uma exceção
fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
val callback = object : LocationCallback() {
override fun onLocationResult(result: LocationResult) {
trySend(result.lastLocation)
}
}
client.requestLocationUpdates(callback)
// IllegalStateException: o bloco callbackFlow foi concluído, mas o
// canal nunca foi fechado, então não resta nenhum momento determinístico
// para desregistrar o callback acima
}
// ✅ awaitClose suspende até que o coletor cancele (ou o canal
// seja fechado de outra forma), que é também o único lugar seguro para
// desregistrar o 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) }
}O contrato inteiro do callbackFlow é construído em torno de ter um momento
determinístico para limpar qualquer callback que ele registrou. Se o bloco pudesse
retornar por conta própria, não haveria tal momento, o callback simplesmente escaparia,
registrado para sempre sem nada capaz de desregistrá-lo. Então
callbackFlow impõe o contrato em tempo de execução: o bloco deve terminar em um
ponto de suspensão, quase sempre awaitClose { }, ou ele lança uma exceção em vez de
escapar silenciosamente.
callbackFlow também é frio, o que significa que o callback é reregistrado por coletor
fun locationUpdates(client: LocationClient): Flow<Location> = callbackFlow {
val callback = object : LocationCallback() {
override fun onLocationResult(result: LocationResult) {
trySend(result.lastLocation)
}
}
client.requestLocationUpdates(callback) // registrado novamente por coletor
awaitClose { client.removeLocationUpdates(callback) }
}Envolver um callback em callbackFlow não o exclui do frio-por-padrão,
ainda é construído a partir da mesma receita no formato flow { }. Dois coletores
registram dois listeners de localização separados com o SO, cada um desmontado
independentemente no cancelamento de seu próprio coletor. A correção é a mesma de
acima: compartilhe-o com shareIn uma vez em um scope que sobrevive a qualquer coletor
individual, em vez de deixar cada tela que quer dados de localização chamar
locationUpdates() ela mesma.
Flow não tem .value, StateFlow tem, e recorrer a um quando você queria o outro é um erro de tipo esperando para acontecer
Um Flow<T> simples não pode ser lido de forma síncrona, não há valor atual para
ler já que nada está em execução até que você o colete. StateFlow<T> sempre
tem um. Código que genericamente recebe um parâmetro Flow<T>, mas na verdade
precisa de .value é um sinal de que a função assumiu silenciosamente semântica quente que
nunca foi garantida.
Um Flow é uma receita, não um canal já carregando valores: frio por
padrão, cada collect() executa novamente sua própria cópia independente, e
StateFlow/SharedFlow (ou stateIn/shareIn sobre um Flow frio)
são a opção deliberada de executá-lo uma vez e deixar todos compartilharem o
resultado.



