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ística | SharedFlow |
|---|---|
| Tipo de fluxo | Quente (hot), broadcast |
| Valor atual obrigatório | Não |
| Replay | Configurável (replay) |
| Buffer extra | extraBufferCapacity |
Deduplicação por equals | Não (emite mesmo valor repetido) |
| Caso de uso típico | Eventos 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âmetro | Efeito prático |
|---|---|
replay | Quantos valores recentes um assinante novo recebe na hora |
extraBufferCapacity | Slots extras para absorver produtores mais rápidos que consumidores |
onBufferOverflow | O 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
tryEmitpara telemetria/alta frequência, aceitando perda sob pressão. DROP_OLDESTmantém o sinal mais recente;DROP_LATESTpreserva o histórico já enfileirado;SUSPENDaplica 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
| Necessidade | Escolha | Motivo |
|---|---|---|
| Estado atual sempre disponível (UI, sessão) | StateFlow | tem value, exige inicial, deduplica iguais |
| Eventos one-shot para um ou mais ouvintes | SharedFlow | broadcast configurável; não exige estado atual |
| Pipeline sob demanda (rede, disco, transformação) | Flow frio | cada collect reinicia o trabalho |
| Comunicação ponto a ponto entre coroutines | Channel | fila com capacidade e backpressure explícitos |
| Broadcast com histórico curto | SharedFlow(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
MutableSharedFlowpublicamente. Outras camadas passam a emitir eventos arbitrários. PubliqueSharedFlowviaasSharedFlow(). replay > 0em eventos de navegação. Um coletor atrasado pode “navegar de novo” para uma rota antiga. Para one-shot de UI, comece comreplay = 0.- Capacidade zero sem coletor.
emitsuspende para sempre se ninguém coleta e não há buffer — deadlock silencioso em testes e eminit {}de ViewModel. - Assumir que
tryEmitsempre funciona. Com buffer cheio e overflowSUSPEND/sem folga, retornafalse. Trate o retorno ou useemit. - 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
collectsolto 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 owhenexaustivo evitamelseesquecidos. - Escolha
replayconscientemente:0para one-shot de UI;1quando o último sinal ainda importa (status, último tick). - Dimensionne
extraBufferCapacitypelo pior burst esperado, não por “número mágico”. - Em testes, use Turbine ou
runTestcom 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
- StateFlow em Kotlin — o par natural para estado atual observável
- Flow em Kotlin — streams frios, operators e builders
- Channel em Kotlin — filas ponto a ponto entre coroutines
- Guia completo de Kotlin Flow — shareIn, stateIn e padrões de produção
- Tutorial de Flow — prática guiada com exemplos progressivos
- Arquitetura MVVM com Kotlin — onde encaixar estado e eventos
- Testando Flow e StateFlow com Turbine — testes determinísticos de coleta
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