Misleading docs on MutableStateFlow.emit and MutableStateFlow.tryEmit methods

[rmiller-glrealitylabs]

The Problem

The documentation for the MutableStateFlow.emit and MutableStateFlow.tryEmit functions are misleading. For example, the docs for MutableStateFlow.tryEmit appear as

kotlinx.coroutines/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt

Lines 161 to 172 in dda99e2

	/**
	* 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.
	*
	* A shared flow configured with a [BufferOverflow] strategy other than [SUSPEND][BufferOverflow.SUSPEND]
	* (either [DROP_OLDEST][BufferOverflow.DROP_OLDEST] or [DROP_LATEST][BufferOverflow.DROP_LATEST]) never
	* suspends on [emit], and thus `tryEmit` to such a shared flow always returns `true`.
	*
	* This method is **thread-safe** and can be safely invoked from concurrent coroutines without
	* external synchronization.
	*/

but in fact that method never blocks and always returns true, regardless of the BufferOverflow setting.

Why Does the Problem Exist?

In the source code for the actual definition of MutableStateFlow

kotlinx.coroutines/kotlinx-coroutines-core/common/src/flow/StateFlow.kt

Lines 319 to 326 in dda99e2

	override fun tryEmit(value: T): Boolean {
	this.value = value
	return true
	}
	override suspend fun emit(value: T) {
	this.value = value
	}

the tryEmit and emit methods are overridden so that (as far as I can tell) they never suspend.

However, when the MutableStateFlow interface is defined, it inherits from the StateFlow and MutableSharedFlow interfaces:

kotlinx.coroutines/kotlinx-coroutines-core/common/src/flow/StateFlow.kt

Line 158 in dda99e2

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

The tryEmit and emit functions inherit the documentation from MutableSharedFlow despite having their behavior changed in the actual implementation of MutableStateFlow

A Possible Solution:

Add the overridden functions to the MutableSharedState interface with accurate documentation.

[qwwdfsad]

Fixed with #2560

[trevorhackman]

This still seems a bit confusing. Does this mean there's no reason to ever use emit with a StateFlow, you can always use tryEmit and get the same functionality with less restrictions?

[Burtan]

Is there any reason technical restriction that emit does not suspend until all collectors finished? Always using a SharedFlow when you want this functionality is a little cumbersome.