SharedFlow: cos'è, SharedFlow vs StateFlow in Android

Cos'è SharedFlow in Kotlin?

SharedFlow è un flusso caldo (hot flow) della libreria kotlinx.coroutines.flow che, a differenza di StateFlow, non è legato a un singolo stato e può emettere un numero arbitrario di eventi a abbonati arbitrari. SharedFlow è il tipo base per StateFlow — StateFlow è infatti implementato tramite SharedFlow con replay = 1.

La caratteristica principale di SharedFlow è che non deve memorizzare l'ultimo valore. Per impostazione predefinita (replay = 0), un nuovo abbonato non riceve nulla finché non viene inviato un nuovo evento. Ciò rende SharedFlow ideale per scenari in cui un evento deve essere elaborato esattamente una volta: navigazione, Snackbar, notifiche di sistema, risultati di scansione di codici QR.

SharedFlow è stato stabilizzato in kotlinx.coroutines 1.4.0 (novembre 2020) insieme a StateFlow. Secondo la documentazione di Kotlin Coroutines (2025), SharedFlow utilizza un blocco a grana fine per la sincronizzazione degli abbonati e fornisce scalabilità lineare fino a oltre 1000 abbonati simultanei senza degrado delle prestazioni, confermato dai test JetBrains.

SharedFlow vs StateFlow: quando usare cosa

La scelta tra SharedFlow e StateFlow dipende dalla semantica dei dati trasferiti: stato (StateFlow) o evento (SharedFlow). Di seguito sono riportati criteri chiari con esempi.

La regola più semplice: se i dati devono essere mostrati alla rotazione dello schermo — è stato (StateFlow). Se alla rotazione dello schermo l'evento non deve ripetersi — è un evento una tantum (SharedFlow). Ad esempio, un toast con un messaggio di errore è SharedFlow: alla rotazione, il toast non deve apparire di nuovo. Un elenco di prodotti è StateFlow: alla rotazione, l'elenco deve rimanere sullo schermo.

In IT Sectr utilizziamo SharedFlow per: comandi di navigazione (transizione schermo, apertura deep link), eventi UI (Snackbar, AlertDialog), notifiche di sistema (aggiornamenti dati in background, risultato pagamento), eventi di analisi (logging, tracciamento).

MutableSharedFlow: emit, tryEmit e bufferizzazione

MutableSharedFlow è la versione mutabile di SharedFlow con i metodi emit() (suspend) e tryEmit() (non-suspend) per l'invio di eventi. emit() si sospende se il buffer è pieno e onBufferOverflow = SUSPEND. tryEmit() restituisce un Boolean indicando se l'evento è stato aggiunto con successo al buffer.

class EventBus {
    private val _events = MutableSharedFlow<UiEvent>(
        replay = 0,
        extraBufferCapacity = 10,
        onBufferOverflow = BufferOverflow.DROP_OLDEST
    )
    val events: SharedFlow<UiEvent> get() = _events

    suspend fun sendEvent(event: UiEvent) {
        _events.emit(event)
    }

    fun trySendEvent(event: UiEvent): Boolean {
        return _events.tryEmit(event)
    }
}

sealed interface UiEvent {
    data class ShowSnackbar(val message: String) : UiEvent
    data class NavigateTo(val route: String) : UiEvent
    data class ShowDialog(val title: String, val message: String) : UiEvent
}

I parametri del costruttore sono criticamente importanti: replay = 0 garantisce che l'evento non si ripeta per un nuovo abbonato; extraBufferCapacity = 10 fornisce un buffer per l'emissione rapida di eventi prima che l'UI si abboni; DROP_OLDEST è la strategia di overflow: gli eventi vecchi vengono scartati, quelli nuovi vengono conservati. Secondo Kotlin Coroutines Performance (JetBrains, 2024), SharedFlow con extraBufferCapacity = 64 elabora oltre 100.000 eventi al secondo senza perdite.

SharedFlow per eventi una tantum: il pattern Event

Pattern Event (o UiEvent) è il metodo consigliato da Google per passare eventi una tantum da ViewModel a View. A differenza dello stato (StateFlow), un evento deve essere elaborato esattamente una volta e, alla rotazione dello schermo, non deve ripetersi. SharedFlow con replay = 0 è ideale per questo compito.

class CheckoutViewModel : ViewModel() {
    private val _uiState = MutableStateFlow<CheckoutState>(CheckoutState.Idle)
    val uiState: StateFlow<CheckoutState> get() = _uiState

    private val _event = MutableSharedFlow<CheckoutEvent>()
    val event: SharedFlow<CheckoutEvent> get() = _event

    fun placeOrder() {
        viewModelScope.launch {
            _uiState.value = CheckoutState.Loading
            try {
                val orderId = orderRepository.createOrder(cart)
                _uiState.value = CheckoutState.Success(orderId)
                _event.emit(CheckoutEvent.NavigateToOrderTracking(orderId))
            } catch (e: Exception) {
                _uiState.value = CheckoutState.Error(e.message)
                _event.emit(CheckoutEvent.ShowErrorSnackbar(e.message ?: "Errore di layout"))
            }
        }
    }
}

sealed interface CheckoutEvent {
    data class NavigateToOrderTracking(val orderId: String) : CheckoutEvent
    data class ShowErrorSnackbar(val message: String) : CheckoutEvent
}

Nella View (Activity/Fragment): l'abbonamento agli eventi dovrebbe essere fatto in lifecycleScope con repeatOnLifecycle(STATE.STARTED). Ad ogni ingresso in STARTED, l'abbonamento viene ricreato, ma l'evento non si ripete perché SharedFlow con replay=0 lo ha già rilasciato. Ciò garantisce che la navigazione verso la schermata di tracciamento dell'ordine avvenga solo una volta, non ad ogni rotazione.

Parametri di SharedFlow: replay, extraBufferCapacity, onBufferOverflow

Il costruttore di MutableSharedFlow accetta tre parametri che determinano il comportamento del buffer. Una configurazione errata può portare alla perdita di eventi o al blocco di emit().

// Configurazioni per diversi scenari:

// 1. Eventi UI una tantum (navigazione, toast)
val uiEvents = MutableSharedFlow<UiEvent>(
    replay = 0,
    extraBufferCapacity = 5,
    onBufferOverflow = BufferOverflow.DROP_OLDEST
)

// 2. Flusso di replay per sincronizzazione stato (come StateFlow)
val stateLike = MutableSharedFlow<AppState>(
    replay = 1,
    extraBufferCapacity = 0
)

// 3. Emissione eventi ad alta frequenza (analisi, log)
val analytics = MutableSharedFlow<AnalyticsEvent>(
    replay = 0,
    extraBufferCapacity = 100,
    onBufferOverflow = BufferOverflow.DROP_OLDEST
)

Importante: extraBufferCapacity + replay = dimensione totale del buffer. Se emit() viene chiamato più velocemente di quanto l'abbonato elabori gli eventi, il buffer si riempie e onBufferOverflow si attiva. Per gli eventi UI, DROP_OLDEST è una strategia sicura: gli eventi vecchi (navigazioni non più rilevanti) vengono scartati a favore di quelli nuovi. Per le transazioni finanziarie, utilizzare SUSPEND — ciò garantisce che nessun evento venga perso al costo di bloccare il mittente.

Esempi di codice: SharedFlow in Kotlin

Esempio 1: SharedFlow per navigazione con Jetpack Navigation

I comandi di navigazione sono un caso d'uso classico per SharedFlow. Un Fragment si abbona agli eventi ed esegue la navigazione. Alla rotazione dello schermo, il comando non si ripete.

// ViewModel
class AuthViewModel : ViewModel() {
    private val _navEvent = MutableSharedFlow<NavEvent>()
    val navEvent: SharedFlow<NavEvent> get() = _navEvent

    fun onLoginSuccess() {
        viewModelScope.launch {
            _navEvent.emit(NavEvent.NavigateTo(NavRoutes.HOME))
        }
    }

    fun onLogout() {
        viewModelScope.launch {
            _navEvent.emit(NavEvent.NavigateTo(NavRoutes.LOGIN))
        }
    }
}

sealed interface NavEvent {
    data class NavigateTo(val route: String) : NavEvent
    data class NavigateBack(val popUpTo: String? = null) : NavEvent
}

// Nel Fragment:
viewLifecycleOwner.lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.navEvent.collect { navEvent ->
            when (navEvent) {
                is NavEvent.NavigateTo -> findNavController().navigate(navEvent.route)
                is NavEvent.NavigateBack -> findNavController().popBackStack()
            }
        }
    }
}

Esempio 2: SharedFlow con Room e operatori Flow

Uno scenario complesso: SharedFlow per notifiche di eventi in background combinato con StateFlow per l'UI.

class NotificationViewModel : ViewModel() {
    private val _toastMessage = MutableSharedFlow<String>()
    val toastMessage: SharedFlow<String> get() = _toastMessage

    private val _notifications = MutableStateFlow<List<Notification>>(emptyList())
    val notifications: StateFlow<List<Notification>> get() = _notifications

    init {
        viewModelScope.launch {
            notificationChannel
                .consumeAsFlow()
                .collect { notification ->
                    _notifications.value = _notifications.value + notification
                    _toastMessage.emit("Nuova notifica: ${notification.title}")
                }
        }
    }

    fun dismissNotification(id: String) {
        _notifications.value = _notifications.value.filter { it.id != id }
    }

    fun markAllRead() {
        viewModelScope.launch {
            _notifications.value = _notifications.value.map { it.copy(isRead = true) }
            _toastMessage.emit("Tutte le notifiche segnate come lette")
        }
    }
}

In questo esempio: StateFlow memorizza l'elenco delle notifiche (stato — preservato alla rotazione), SharedFlow emette messaggi toast (eventi una tantum — non ripetuti alla rotazione). La combinazione di due tipi di Flow è il pattern raccomandato da Google per ViewModel a partire dal 2022.