Recomposed
Coroutines

Kotlin Flow: Um Modelo Mental

Oct 25, 2026 · 11 min read

Kotlin Flow: Um Modelo Mental

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 mesmo Flow executa 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 Flow nunca 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, cada subscribe() executa novamente todo o bloco emissor. PublishSubject e BehaviorSubject são as válvulas de escape quentes, um canal em execução que os assinantes acessam em vez de reiniciar.
  • Combine (Swift/SwiftUI): um Publisher simples é frio, reexecutando seu upstream para cada novo assinante, a menos que você insira .share() ou .multicast(). CurrentValueSubject e PassthroughSubject são os primitivos quentes do Combine, e CurrentValueSubject mapeia quase exatamente para StateFlow: 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. Um EventTarget/EventEmitter é quente: ele dispara independentemente de haver algo ouvindo, e ouvintes tardios apenas perdem o que já aconteceu.
  • O antigo LiveData do 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 de LiveData para Flow confunde as pessoas: o modelo mental que elas construíram para LiveData assume semântica quente que um flow { } 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.

OperadorCategoriaO que faz
map / filterTransformaçãoRemodela ou descarta emissões uma a uma, igual a Sequence/List
combineCombinar múltiplos flowsRecalcula a partir do valor mais recente de cada fonte sempre que qualquer uma delas emite
zipCombinar múltiplos flowsPareia a n-ésima emissão de cada fonte; espera cada lado emitir antes de produzir um par
mergeCombinar múltiplos flowsIntercala emissões de múltiplas fontes em uma só, na ordem em que chegam
flatMapLatestTrocar para um novo flowCancela o Flow interno anterior e troca para um novo cada vez que o Flow externo emite
flatMapConcatTrocar para um novo flowExecuta flows internos um por vez, em ordem, nunca se sobrepondo
flatMapMergeTrocar para um novo flowExecuta flows internos concorrentemente, intercalando suas emissões
debounceLimitação de taxaDescarta emissões até passar um intervalo de silêncio, depois emite apenas a mais recente
distinctUntilChangedLimitação de taxaDescarta uma nova emissão se ela for igual à última realmente emitida
bufferBackpressureExecuta 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
conflateBackpressureAtalho 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
catchTratamento de errosCaptura 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.

Keep reading

Related reads

Receba novos posts no seu e-mail