O que é SharedFlow em Kotlin?

Resposta rápida: SharedFlow é um Flow quente de broadcast da biblioteca kotlinx.coroutines. Vários coletores compartilham as mesmas emissões. Ele não exige um valor atual (diferente do StateFlow) e é o padrão idiomático para eventos one-shot: snackbar, navegação, analytics, alertas de domínio e fan-out em backends Kotlin.

Pense no SharedFlow como um alto-falante no corredor: quem estiver ouvindo agora escuta o aviso. Quem chegou tarde só ouve o que ainda estiver no “replay” configurado — e, se o replay for zero, o aviso já passou. Não é placar permanente; é mensagem.

CaracterísticaSharedFlow
Tipo de fluxoQuente (hot), broadcast
Valor atual obrigatórioNão
ReplayConfigurável (replay)
Buffer extraextraBufferCapacity
Deduplicação por equalsNão (emite mesmo valor repetido)
Caso de uso típicoEventos de UI, fan-out, notificações

Sintaxe básica

import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.asSharedFlow

sealed interface EventoUi {
    data class MostrarSnackbar(val texto: String) : EventoUi
    data class Navegar(val rota: String) : EventoUi
}

class PedidoViewModel {
    private val _eventos = MutableSharedFlow<EventoUi>(
        replay = 0,
        extraBufferCapacity = 1,
    )
    val eventos: SharedFlow<EventoUi> = _eventos.asSharedFlow()

    suspend fun confirmarPedido() {
        // ... regra de negócio ...
        _eventos.emit(EventoUi.MostrarSnackbar("Pedido confirmado"))
        _eventos.emit(EventoUi.Navegar("pedido/sucesso"))
    }
}

A superfície pública expõe apenas SharedFlow (somente leitura). A emissão fica no MutableSharedFlow privado — o mesmo padrão de encapsulamento do StateFlow.

Replay, buffer e overflow

MutableSharedFlow tem três knobs que mudam o comportamento sob carga:

val eventos = MutableSharedFlow<String>(
    replay = 1,                 // novos coletores recebem o último evento
    extraBufferCapacity = 16,   // folga além do replay
    onBufferOverflow = BufferOverflow.DROP_OLDEST,
)
ParâmetroEfeito prático
replayQuantos valores recentes um assinante novo recebe na hora
extraBufferCapacitySlots extras para absorver produtores mais rápidos que consumidores
onBufferOverflowO que fazer quando a capacidade estoura: suspender, dropar o mais antigo ou dropar o mais novo

Capacidade total em memória ≈ replay + extraBufferCapacity. Com replay = 0 e extraBufferCapacity = 0, emit suspende até existir um coletor pronto — útil quando você não quer perder o evento, perigoso se ninguém estiver ouvindo.

import kotlinx.coroutines.channels.BufferOverflow
import kotlinx.coroutines.flow.MutableSharedFlow

val telemetria = MutableSharedFlow<String>(
    replay = 0,
    extraBufferCapacity = 64,
    onBufferOverflow = BufferOverflow.DROP_OLDEST,
)

// tryEmit nunca suspende: retorna false se não couber
val aceito = telemetria.tryEmit("fps=58")
  • Prefira emit (suspend) para eventos de negócio que não podem sumir sem backpressure consciente.
  • Prefira tryEmit para telemetria/alta frequência, aceitando perda sob pressão.
  • DROP_OLDEST mantém o sinal mais recente; DROP_LATEST preserva o histórico já enfileirado; SUSPEND aplica backpressure no produtor.

Coletar o SharedFlow

import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.flow.collect

suspend fun observarEventos(eventos: SharedFlow<EventoUi>) = coroutineScope {
    launch {
        eventos.collect { evento ->
            when (evento) {
                is EventoUi.MostrarSnackbar -> println(evento.texto)
                is EventoUi.Navegar -> println("ir para ${evento.rota}")
            }
        }
    }
}

No Jetpack Compose / Android, colete em um escopo ligado ao ciclo de vida para não processar navegação com a tela morta:

@Composable
fun PedidoScreen(viewModel: PedidoViewModel) {
    val context = LocalContext.current

    LaunchedEffect(Unit) {
        viewModel.eventos.collect { evento ->
            when (evento) {
                is EventoUi.MostrarSnackbar -> {
                    // mostrar snackbar
                }
                is EventoUi.Navegar -> {
                    // navegar uma única vez
                }
            }
        }
    }
}

Se a arquitetura da tela ainda está em construção, o guia de MVVM com Kotlin e o tutorial de Flow mostram onde encaixar SharedFlow ao lado do estado.

SharedFlow vs StateFlow vs Flow frio vs Channel

NecessidadeEscolhaMotivo
Estado atual sempre disponível (UI, sessão)StateFlowtem value, exige inicial, deduplica iguais
Eventos one-shot para um ou mais ouvintesSharedFlowbroadcast configurável; não exige estado atual
Pipeline sob demanda (rede, disco, transformação)Flow friocada collect reinicia o trabalho
Comunicação ponto a ponto entre coroutinesChannelfila com capacidade e backpressure explícitos
Broadcast com histórico curtoSharedFlow(replay = N)reenvia os últimos N eventos a novos coletores
class CheckoutViewModel {
    private val _uiState = MutableStateFlow(CheckoutUiState())
    val uiState: StateFlow<CheckoutUiState> = _uiState.asStateFlow()

    private val _eventos = MutableSharedFlow<EventoUi>()
    val eventos: SharedFlow<EventoUi> = _eventos.asSharedFlow()

    suspend fun pagar() {
        _uiState.update { it.copy(carregando = true) }
        // ... gateway ...
        _uiState.update { it.copy(carregando = false, pago = true) }
        _eventos.emit(EventoUi.MostrarSnackbar("Pagamento aprovado"))
    }
}

Regra prática: o que a tela precisa redesenhar → StateFlow. o que deve acontecer uma vez → SharedFlow (ou Channel se for 1:1). Colocar snackbar dentro do StateFlow é a receita clássica de toast duplicado após rotação.

Por que SharedFlow não deduplica?

Diferente do StateFlow, emitir o mesmo conteúdo duas vezes notifica os coletores de novo. Isso é desejável para eventos:

data class Alerta(val texto: String)

val alertas = MutableSharedFlow<Alerta>()

alertas.emit(Alerta("Sem conexão"))
alertas.emit(Alerta("Sem conexão")) // segundo coletor/ouvinte também vê

Se você precisa “estado atual + histórico de mudanças iguais”, não force o SharedFlow: modele um StateFlow para o estado e um SharedFlow separado para o efeito.

Concorrência, escopo e vários coletores

MutableSharedFlow é seguro para emissão concorrente. Cada coletor ativo recebe as emissões (respeitando buffer/replay). Cancelar um coletor não cancela os outros.

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

class AuditoriaService {
    private val escopo = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    private val _eventos = MutableSharedFlow<String>(extraBufferCapacity = 32)
    val eventos: SharedFlow<String> = _eventos.asSharedFlow()

    fun registrar(acao: String) {
        escopo.launch {
            _eventos.emit(acao)
        }
    }
}

Combine com coroutines, launch e dispatchers: o SharedFlow distribui o sinal; a coroutine decide quando emitir.

Operadores e shareIn

Qualquer Flow frio pode virar um SharedFlow compartilhado com shareIn — o espelho de stateIn para streams sem “valor atual” obrigatório:

import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.shareIn

class CotacoesRepository(
    private val escopo: CoroutineScope,
    private val fonte: Flow<Double>,
) {
    val ticks: SharedFlow<Double> = fonte
        .map { preco -> preco }
        .shareIn(
            scope = escopo,
            started = SharingStarted.WhileSubscribed(5_000),
            replay = 1,
        )
}

WhileSubscribed evita manter o upstream ligado quando ninguém escuta. replay = 1 entrega o último tick a quem chegar atrasado, sem transformar o fluxo em StateFlow.

SharedFlow no backend Kotlin

Em serviços JVM o mesmo tipo resolve fan-out: invalidação de cache, progresso de job para vários clientes SSE/WebSocket, alarmes de circuit breaker ou eventos de domínio internos.

class HubProgresso {
    private val _progresso = MutableSharedFlow<Int>(
        replay = 1,
        extraBufferCapacity = 8,
    )
    val progresso: SharedFlow<Int> = _progresso.asSharedFlow()

    suspend fun publicar(percentual: Int) {
        require(percentual in 0..100)
        _progresso.emit(percentual)
    }
}

Novos assinantes com replay = 1 já sabem o percentual mais recente; quem já estava conectado continua recebendo atualizações. Para a stack completa de APIs e mensageria, veja o guia de Kotlin para backend.

Erros comuns

  • Usar SharedFlow no lugar de estado de tela. Sem value, a UI não tem um snapshot estável para redesenhar após rotação. Estado → StateFlow; efeito → SharedFlow.
  • Expor MutableSharedFlow publicamente. Outras camadas passam a emitir eventos arbitrários. Publique SharedFlow via asSharedFlow().
  • replay > 0 em eventos de navegação. Um coletor atrasado pode “navegar de novo” para uma rota antiga. Para one-shot de UI, comece com replay = 0.
  • Capacidade zero sem coletor. emit suspende para sempre se ninguém coleta e não há buffer — deadlock silencioso em testes e em init {} de ViewModel.
  • Assumir que tryEmit sempre funciona. Com buffer cheio e overflow SUSPEND/sem folga, retorna false. Trate o retorno ou use emit.
  • Esperar deduplicação automática. Valores iguais são reemitidos. Se isso for problema, filtre no coletor ou modele IDs únicos.
  • Coletar sem Lifecycle no Android. Um collect solto pode processar snackbar/navegação com a Activity destruída. Amarre ao escopo da UI.

Boas práticas

  • Separe estado (StateFlow) de efeito (SharedFlow) no mesmo ViewModel/serviço.
  • Modele eventos como sealed interface/sealed class — o glossário de sealed class e o when exaustivo evitam else esquecidos.
  • Escolha replay conscientemente: 0 para one-shot de UI; 1 quando o último sinal ainda importa (status, último tick).
  • Dimensionne extraBufferCapacity pelo pior burst esperado, não por “número mágico”.
  • Em testes, use Turbine ou runTest com coleta controlada — o post Testando Flow, StateFlow e Turbine cobre o setup; o mesmo padrão vale para SharedFlow.
  • Documente a política de overflow: perda silenciosa em telemetria é aceitável; em pagamento, quase nunca.

Perguntas frequentes

SharedFlow substitui Channel? Não totalmente. Channel brilha em filas 1:1 com backpressure de produtor/consumidor. SharedFlow brilha em broadcast. Dá para adaptar um ao outro, mas a API certa comunica a intenção.

Preciso de distinctUntilChanged? Só se a sua regra de negócio pedir. SharedFlow não filtra iguais. Depois de um map/filter, você continua com um Flow intermediário até fechar de novo com shareIn se quiser compartilhar.

Qual a diferença para Channel.BUFFERED? Channel entrega cada elemento a um recebedor (a menos que você faça fan-out manual). SharedFlow entrega a todos os coletores ativos.

Posso ter SharedFlow de Unit? Sim (MutableSharedFlow<Unit>()), mas um sealed interface com tipos nomeados documenta melhor a intenção e escala quando o evento ganha payload.

SharedFlow tem value? Não. Se você se pega querendo ler “o evento atual”, provavelmente precisa de StateFlow — ou de replayCache apenas para inspecionar o histórico de replay em depuracao, não como API de UI.

Próximos passos

Termos relacionados

  • StateFlow — fluxo quente com valor atual para estado de UI e sessão
  • Flow — streams assíncronos frios dos quais SharedFlow compartilha a API de coleta
  • Channel — comunicação ponto a ponto com capacidade explícita
  • Coroutine — unidade de concorrência que emite e coleta eventos
  • Emit — operação de emitir valores em builders e fluxos mutáveis
  • ViewModel — dono típico do MutableSharedFlow na camada de apresentação
  • Sealed Class — hierarquia restrita ideal para modelar eventos de UI