kotlinx-coroutines-core / kotlinx.coroutines.flow / MutableStateFlow

MutableStateFlow

interface MutableStateFlow<T> : 
    StateFlow<T>, 
    MutableSharedFlow<T>

(source)

A mutable StateFlow that provides a setter for value. An instance of MutableStateFlow with the given initial value can be created using MutableStateFlow(value) constructor function.

See the StateFlow documentation for details on state flows.

Not stable for inheritance

The MutableStateFlow interface is not stable for inheritance in 3rd party libraries, as new methods might be added to this interface in the future, but is stable for use. Use the MutableStateFlow() constructor function to create an implementation.

Properties

value

abstract var value: T

The current value of this state flow.

Inherited Properties

subscriptionCount

abstract val subscriptionCount: StateFlow<Int>

The number of subscribers (active collectors) to this shared flow.

Functions

compareAndSet

abstract fun compareAndSet(expect: T, update: T): Boolean

Atomically compares the current value with expect and sets it to update if it is equal to expect. The result is true if the value was set to update and false otherwise.

Inherited Functions

emit	`abstract suspend fun emit(value: T): Unit` Emits a value to this shared flow, suspending on buffer overflow if the shared flow was created with the default BufferOverflow.SUSPEND strategy.
resetReplayCache	`abstract fun resetReplayCache(): Unit` Resets the replayCache of this shared flow to an empty state. New subscribers will be receiving only the values that were emitted after this call, while old subscribers will still be receiving previously buffered values. To reset a shared flow to an initial value, emit the value after this call.
tryEmit	`abstract fun tryEmit(value: T): Boolean` Tries to emit a value to this shared flow without suspending. It returns `true` if the value was emitted successfully. When this function returns `false`, it means that the call to a plain emit function will suspend until there is a buffer space available.

Extension Properties

coroutineContext	`val FlowCollector<*>.coroutineContext: CoroutineContext`
isActive	`val FlowCollector<*>.isActive: Boolean`

Extension Functions

asSharedFlow	`fun <T> MutableSharedFlow<T>.asSharedFlow(): SharedFlow<T>` Represents this mutable shared flow as a read-only shared flow.
asStateFlow	`fun <T> MutableStateFlow<T>.asStateFlow(): StateFlow<T>` Represents this mutable state flow as a read-only state flow.
broadcastIn	`fun <T> Flow<T>.broadcastIn( scope: CoroutineScope, start: CoroutineStart = CoroutineStart.LAZY ): BroadcastChannel<T>` Creates a broadcast coroutine that collects the given flow.
buffer	`fun <T> Flow<T>.buffer( capacity: Int = BUFFERED, onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND ): Flow<T>` Buffers flow emissions via channel of a specified capacity and runs collector in a separate coroutine. `fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T>`
cache	`fun <T> Flow<T>.cache(): Flow<T>`
cancel	`fun FlowCollector<*>.cancel( cause: CancellationException? = null ): Unit`
catch	`fun <T> Flow<T>.catch( action: suspend FlowCollector<T>.(cause: Throwable) -> Unit ): Flow<T>` Catches exceptions in the flow completion and calls a specified action with the caught exception. This operator is transparent to exceptions that occur in downstream flow and does not catch exceptions that are thrown to cancel the flow. `fun <T> SharedFlow<T>.catch( action: suspend FlowCollector<T>.(cause: Throwable) -> Unit ): Flow<T>`
collect	`suspend fun Flow<*>.collect(): Unit` Terminal flow operator that collects the given flow but ignores all emitted values. If any exception occurs during collect or in the provided flow, this exception is rethrown from this method. `suspend fun <T> Flow<T>.collect( action: suspend (value: T) -> Unit ): Unit` Terminal flow operator that collects the given flow with a provided action. If any exception occurs during collect or in the provided flow, this exception is rethrown from this method.
collectIndexed	`suspend fun <T> Flow<T>.collectIndexed( action: suspend (index: Int, value: T) -> Unit ): Unit` Terminal flow operator that collects the given flow with a provided action that takes the index of an element (zero-based) and the element. If any exception occurs during collect or in the provided flow, this exception is rethrown from this method.
collectLatest	`suspend fun <T> Flow<T>.collectLatest( action: suspend (value: T) -> Unit ): Unit` Terminal flow operator that collects the given flow with a provided action. The crucial difference from collect is that when the original flow emits a new value then the action block for the previous value is cancelled.
combine	`fun <T1, T2, R> Flow<T1>.combine( flow: Flow<T2>, transform: suspend (a: T1, b: T2) -> R ): Flow<R>` Returns a Flow whose values are generated with transform function by combining the most recently emitted values by each flow.
combineLatest	`fun <T1, T2, R> Flow<T1>.combineLatest( other: Flow<T2>, transform: suspend (T1, T2) -> R ): Flow<R>` `fun <T1, T2, T3, R> Flow<T1>.combineLatest( other: Flow<T2>, other2: Flow<T3>, transform: suspend (T1, T2, T3) -> R ): Flow<R>` `fun <T1, T2, T3, T4, R> Flow<T1>.combineLatest( other: Flow<T2>, other2: Flow<T3>, other3: Flow<T4>, transform: suspend (T1, T2, T3, T4) -> R ): Flow<R>` `fun <T1, T2, T3, T4, T5, R> Flow<T1>.combineLatest( other: Flow<T2>, other2: Flow<T3>, other3: Flow<T4>, other4: Flow<T5>, transform: suspend (T1, T2, T3, T4, T5) -> R ): Flow<R>`
combineTransform	`fun <T1, T2, R> Flow<T1>.combineTransform( flow: Flow<T2>, transform: suspend FlowCollector<R>.(a: T1, b: T2) -> Unit ): Flow<R>` Returns a Flow whose values are generated by transform function that process the most recently emitted values by each flow.
count	`suspend fun <T> Flow<T>.count( predicate: suspend (T) -> Boolean ): Int` Returns the number of elements matching the given predicate.
debounce	`fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T>` `fun <T> Flow<T>.debounce(timeoutMillis: (T) -> Long): Flow<T>` Returns a flow that mirrors the original flow, but filters out values that are followed by the newer values within the given timeout. The latest value is always emitted. `fun <T> Flow<T>.debounce(timeout: <ERROR CLASS>): Flow<T>` `fun <T> Flow<T>.debounce( timeout: (T) -> <ERROR CLASS> ): Flow<T>` Returns a flow that mirrors the original flow, but filters out values that are followed by the newer values within the given timeout. The latest value is always emitted.
distinctUntilChanged	`fun <T> Flow<T>.distinctUntilChanged( areEquivalent: (old: T, new: T) -> Boolean ): Flow<T>` Returns flow where all subsequent repetitions of the same value are filtered out, when compared with each other via the provided areEquivalent function.
distinctUntilChangedBy	`fun <T, K> Flow<T>.distinctUntilChangedBy( keySelector: (T) -> K ): Flow<T>` Returns flow where all subsequent repetitions of the same key are filtered out, where key is extracted with keySelector function.
drop	`fun <T> Flow<T>.drop(count: Int): Flow<T>` Returns a flow that ignores first count elements. Throws IllegalArgumentException if count is negative.
dropWhile	`fun <T> Flow<T>.dropWhile( predicate: suspend (T) -> Boolean ): Flow<T>` Returns a flow containing all elements except first elements that satisfy the given predicate.
emitAll	`suspend fun <T> FlowCollector<T>.emitAll( channel: ReceiveChannel<T> ): Unit` Emits all elements from the given channel to this flow collector and cancels (consumes) the channel afterwards. If you need to iterate over the channel without consuming it, a regular `for` loop should be used instead. `suspend fun <T> FlowCollector<T>.emitAll(flow: Flow<T>): Unit` Collects all the values from the given flow and emits them to the collector. It is a shorthand for `flow.collect { value -> emit(value) }`.
filter	`fun <T> Flow<T>.filter( predicate: suspend (T) -> Boolean ): Flow<T>` Returns a flow containing only values of the original flow that matches the given predicate.
filterIsInstance	`fun <R> Flow<*>.filterIsInstance(): Flow<R>` Returns a flow containing only values that are instances of specified type R.
filterNot	`fun <T> Flow<T>.filterNot( predicate: suspend (T) -> Boolean ): Flow<T>` Returns a flow containing only values of the original flow that do not match the given predicate.
filterNotNull	`fun <T : Any> Flow<T?>.filterNotNull(): Flow<T>` Returns a flow containing only values of the original flow that are not null.
first	`suspend fun <T> Flow<T>.first(): T` The terminal operator that returns the first element emitted by the flow and then cancels flow’s collection. Throws NoSuchElementException if the flow was empty. `suspend fun <T> Flow<T>.first( predicate: suspend (T) -> Boolean ): T` The terminal operator that returns the first element emitted by the flow matching the given predicate and then cancels flow’s collection. Throws NoSuchElementException if the flow has not contained elements matching the predicate.
firstOrNull	`suspend fun <T> Flow<T>.firstOrNull(): T?` The terminal operator that returns the first element emitted by the flow and then cancels flow’s collection. Returns `null` if the flow was empty. `suspend fun <T> Flow<T>.firstOrNull( predicate: suspend (T) -> Boolean ): T?` The terminal operator that returns the first element emitted by the flow matching the given predicate and then cancels flow’s collection. Returns `null` if the flow did not contain an element matching the predicate.
flatMapConcat	`fun <T, R> Flow<T>.flatMapConcat( transform: suspend (value: T) -> Flow<R> ): Flow<R>` Transforms elements emitted by the original flow by applying transform, that returns another flow, and then concatenating and flattening these flows.
flatMapLatest	`fun <T, R> Flow<T>.flatMapLatest( transform: suspend (value: T) -> Flow<R> ): Flow<R>` Returns a flow that switches to a new flow produced by transform function every time the original flow emits a value. When the original flow emits a new value, the previous flow produced by `transform` block is cancelled.
flatMapMerge	`fun <T, R> Flow<T>.flatMapMerge( concurrency: Int = DEFAULT_CONCURRENCY, transform: suspend (value: T) -> Flow<R> ): Flow<R>` Transforms elements emitted by the original flow by applying transform, that returns another flow, and then merging and flattening these flows.
flowWith	`fun <T, R> Flow<T>.flowWith( flowContext: CoroutineContext, bufferSize: Int = BUFFERED, builder: Flow<T>.() -> Flow<R> ): Flow<R>` The operator that changes the context where all transformations applied to the given flow within a builder are executed. This operator is context preserving and does not affect the context of the preceding and subsequent operations.
fold	`suspend fun <T, R> Flow<T>.fold( initial: R, operation: suspend (acc: R, value: T) -> R ): R` Accumulates value starting with initial value and applying operation current accumulator value and each element
launchIn	`fun <T> Flow<T>.launchIn(scope: CoroutineScope): Job` Terminal flow operator that launches the collection of the given flow in the scope. It is a shorthand for `scope.launch { flow.collect() }`.
map	`fun <T, R> Flow<T>.map( transform: suspend (value: T) -> R ): Flow<R>` Returns a flow containing the results of applying the given transform function to each value of the original flow.
mapLatest	`fun <T, R> Flow<T>.mapLatest( transform: suspend (value: T) -> R ): Flow<R>` Returns a flow that emits elements from the original flow transformed by transform function. When the original flow emits a new value, computation of the transform block for previous value is cancelled.
mapNotNull	`fun <T, R : Any> Flow<T>.mapNotNull( transform: suspend (value: T) -> R? ): Flow<R>` Returns a flow that contains only non-null results of applying the given transform function to each value of the original flow.
onCompletion	`fun <T> Flow<T>.onCompletion( action: suspend FlowCollector<T>.(cause: Throwable?) -> Unit ): Flow<T>` Returns a flow that invokes the given action after the flow is completed or cancelled, passing the cancellation exception or failure as cause parameter of action.
onEach	`fun <T> Flow<T>.onEach(action: suspend (T) -> Unit): Flow<T>` Returns a flow that invokes the given action before each value of the upstream flow is emitted downstream.
onEmpty	`fun <T> Flow<T>.onEmpty( action: suspend FlowCollector<T>.() -> Unit ): Flow<T>` Invokes the given action when this flow completes without emitting any elements. The receiver of the action is FlowCollector, so `onEmpty` can emit additional elements. For example:
onStart	`fun <T> Flow<T>.onStart( action: suspend FlowCollector<T>.() -> Unit ): Flow<T>` Returns a flow that invokes the given action before this flow starts to be collected.
onSubscription	`fun <T> SharedFlow<T>.onSubscription( action: suspend FlowCollector<T>.() -> Unit ): SharedFlow<T>` Returns a flow that invokes the given action after this shared flow starts to be collected (after the subscription is registered).
produceIn	`fun <T> Flow<T>.produceIn( scope: CoroutineScope ): ReceiveChannel<T>` Creates a produce coroutine that collects the given flow.
publish	`fun <T> Flow<T>.publish(): Flow<T>` `fun <T> Flow<T>.publish(bufferSize: Int): Flow<T>`
reduce	`suspend fun <S, T : S> Flow<T>.reduce( operation: suspend (accumulator: S, value: T) -> S ): S` Accumulates value starting with the first element and applying operation to current accumulator value and each element. Throws NoSuchElementException if flow was empty.
replay	`fun <T> Flow<T>.replay(): Flow<T>` `fun <T> Flow<T>.replay(bufferSize: Int): Flow<T>`
retry	`fun <T> Flow<T>.retry( retries: Int = Int.MAX_VALUE, predicate: (Throwable) -> Boolean = { true } ): Flow<T>`
retryWhen	`fun <T> Flow<T>.retryWhen( predicate: suspend FlowCollector<T>.(cause: Throwable, attempt: Long) -> Boolean ): Flow<T>` Retries collection of the given flow when an exception occurs in the upstream flow and the predicate returns true. The predicate also receives an `attempt` number as parameter, starting from zero on the initial call. This operator is transparent to exceptions that occur in downstream flow and does not retry on exceptions that are thrown to cancel the flow. `fun <T> SharedFlow<T>.retryWhen( predicate: suspend FlowCollector<T>.(cause: Throwable, attempt: Long) -> Boolean ): Flow<T>`
runningReduce	`fun <T> Flow<T>.runningReduce( operation: suspend (accumulator: T, value: T) -> T ): Flow<T>` Reduces the given flow with operation, emitting every intermediate result, including initial value. The first element is taken as initial value for operation accumulator. This operator has a sibling with initial value – scan.
sample	`fun <T> Flow<T>.sample(periodMillis: Long): Flow<T>` Returns a flow that emits only the latest value emitted by the original flow during the given sampling period. `fun <T> Flow<T>.sample(period: <ERROR CLASS>): Flow<T>` Returns a flow that emits only the latest value emitted by the original flow during the given sampling period.
scan	`fun <T, R> Flow<T>.scan( initial: R, operation: suspend (accumulator: R, value: T) -> R ): Flow<R>` Folds the given flow with operation, emitting every intermediate result, including initial value. Note that initial value should be immutable (or should not be mutated) as it is shared between different collectors. For example:
scanReduce	`fun <T> Flow<T>.scanReduce( operation: suspend (accumulator: T, value: T) -> T ): Flow<T>`
shareIn	`fun <T> Flow<T>.shareIn( scope: CoroutineScope, started: SharingStarted, replay: Int = 0 ): SharedFlow<T>` Converts a cold Flow into a hot SharedFlow that is started in the given coroutine scope, sharing emissions from a single running instance of the upstream flow with multiple downstream subscribers, and replaying a specified number of replay values to new subscribers. See the SharedFlow documentation for the general concepts of shared flows.
single	`suspend fun <T> Flow<T>.single(): T` The terminal operator that awaits for one and only one value to be emitted. Throws NoSuchElementException for empty flow and IllegalStateException for flow that contains more than one element.
singleOrNull	`suspend fun <T> Flow<T>.singleOrNull(): T?` The terminal operator that awaits for one and only one value to be emitted. Returns the single value or `null`, if the flow was empty or emitted more than one value.
stateIn	`fun <T> Flow<T>.stateIn( scope: CoroutineScope, started: SharingStarted, initialValue: T ): StateFlow<T>` Converts a cold Flow into a hot StateFlow that is started in the given coroutine scope, sharing the most recently emitted value from a single running instance of the upstream flow with multiple downstream subscribers. See the StateFlow documentation for the general concepts of state flows. `suspend fun <T> Flow<T>.stateIn( scope: CoroutineScope ): StateFlow<T>` Starts the upstream flow in a given scope, suspends until the first value is emitted, and returns a hot StateFlow of future emissions, sharing the most recently emitted value from this running instance of the upstream flow with multiple downstream subscribers. See the StateFlow documentation for the general concepts of state flows.
switchMap	`fun <T, R> Flow<T>.switchMap( transform: suspend (value: T) -> Flow<R> ): Flow<R>`
take	`fun <T> Flow<T>.take(count: Int): Flow<T>` Returns a flow that contains first count elements. When count elements are consumed, the original flow is cancelled. Throws IllegalArgumentException if count is not positive.
takeWhile	`fun <T> Flow<T>.takeWhile( predicate: suspend (T) -> Boolean ): Flow<T>` Returns a flow that contains first elements satisfying the given predicate.
toCollection	`suspend fun <T, C : MutableCollection<in T>> Flow<T>.toCollection( destination: C ): C` Collects given flow into a destination
toList	`suspend fun <T> SharedFlow<T>.toList(): List<T>` `suspend fun <T> Flow<T>.toList( destination: MutableList<T> = ArrayList() ): List<T>` Collects given flow into a destination
toSet	`suspend fun <T> SharedFlow<T>.toSet(): Set<T>` `suspend fun <T> Flow<T>.toSet( destination: MutableSet<T> = LinkedHashSet() ): Set<T>` Collects given flow into a destination
transform	`fun <T, R> Flow<T>.transform( transform: suspend FlowCollector<R>.(value: T) -> Unit ): Flow<R>` Applies transform function to each value of the given flow.
transformLatest	`fun <T, R> Flow<T>.transformLatest( transform: suspend FlowCollector<R>.(value: T) -> Unit ): Flow<R>` Returns a flow that produces element by transform function every time the original flow emits a value. When the original flow emits a new value, the previous `transform` block is cancelled, thus the name `transformLatest`.
transformWhile	`fun <T, R> Flow<T>.transformWhile( transform: suspend FlowCollector<R>.(value: T) -> Boolean ): Flow<R>` Applies transform function to each value of the given flow while this function returns `true`.
withIndex	`fun <T> Flow<T>.withIndex(): Flow<IndexedValue<T>>` Returns a flow that wraps each element into IndexedValue, containing value and its index (starting from zero).
zip	`fun <T1, T2, R> Flow<T1>.zip( other: Flow<T2>, transform: suspend (T1, T2) -> R ): Flow<R>` Zips values from the current flow (`this`) with other flow using provided transform function applied to each pair of values. The resulting flow completes as soon as one of the flows completes and cancel is called on the remaining flow.