From 865c229de80fd748e2c983d1f887b99c6e66ce64 Mon Sep 17 00:00:00 2001 From: Roman Elizarov Date: Wed, 4 Nov 2020 00:42:35 +0300 Subject: [PATCH] Additional docs on unbuffered shared flow (#2346) --- kotlinx-coroutines-core/common/src/flow/SharedFlow.kt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt b/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt index feb2749595..a3075b927a 100644 --- a/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt +++ b/kotlinx-coroutines-core/common/src/flow/SharedFlow.kt @@ -68,6 +68,15 @@ import kotlin.native.concurrent.* * the `onBufferOverflow` parameter, which is equal to one of the entries of the [BufferOverflow] enum. When a strategy other * than [SUSPENDED][BufferOverflow.SUSPEND] is configured, emissions to the shared flow never suspend. * + * ### Unbuffered shared flow + * + * A default implementation of a shared flow that is created with `MutableSharedFlow()` constructor function + * without parameters has no replay cache nor additional buffer. + * [emit][MutableSharedFlow.emit] call to such a shared flow suspends until all subscribers receive the emitted value + * and returns immediately if there are no subscribers. + * Thus, [tryEmit][MutableSharedFlow.tryEmit] call succeeds and returns `true` only if + * there are no subscribers (in which case the emitted value is immediately lost). + * * ### SharedFlow vs BroadcastChannel * * Conceptually shared flow is similar to [BroadcastChannel][BroadcastChannel]