Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Shared overflow doc #2560

Merged
merged 2 commits into from
Apr 20, 2021
Merged

Shared overflow doc #2560

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
163dce7
Clarify docs about restriction on MutableSharedFlow function's onBuff…
zach-klippenstein Jan 27, 2021
5bf738d
Clarify docs about MutableSharedFlow function without subscribers but…
elizarov Mar 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 13 additions & 3 deletions kotlinx-coroutines-core/common/src/flow/SharedFlow.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,13 @@ 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.
*
* **Buffer overflow condition can happen only when there is at least one subscriber that is not ready to accept
* the new value.** In the absence of subscribers only the most recent `replay` values are stored and the buffer
* overflow behavior is never triggered and has no effect. In particular, in the absence of subscribers emitter never
* suspends despite [BufferOverflow.SUSPEND] option and [BufferOverflow.DROP_LATEST] option does not have effect either.
* Essentially, the behavior in the absence of subscribers is always similar to [BufferOverflow.DROP_OLDEST],
* but the buffer is just of `replay` size (without any `extraBufferCapacity`).
*
* ### Unbuffered shared flow
*
* A default implementation of a shared flow that is created with `MutableSharedFlow()` constructor function
Expand Down Expand Up @@ -221,9 +228,12 @@ public interface MutableSharedFlow<T> : SharedFlow<T>, FlowCollector<T> {
* @param replay the number of values replayed to new subscribers (cannot be negative, defaults to zero).
* @param extraBufferCapacity the number of values buffered in addition to `replay`.
* [emit][MutableSharedFlow.emit] does not suspend while there is a buffer space remaining (optional, cannot be negative, defaults to zero).
* @param onBufferOverflow configures an action on buffer overflow (optional, defaults to
* [suspending][BufferOverflow.SUSPEND] attempts to [emit][MutableSharedFlow.emit] a value,
* supported only when `replay > 0` or `extraBufferCapacity > 0`).
* @param onBufferOverflow configures an [emit][MutableSharedFlow.emit] action on buffer overflow. Optional, defaults to
* [suspending][BufferOverflow.SUSPEND] attempts to emit a value.
* Values other than [BufferOverflow.SUSPEND] are supported only when `replay > 0` or `extraBufferCapacity > 0`.
* **Buffer overflow can happen only when there is at least one subscriber that is not ready to accept
* the new value.** In the absence of subscribers only the most recent [replay] values are stored and
* the buffer overflow behavior is never triggered and has no effect.
*/
@Suppress("FunctionName", "UNCHECKED_CAST")
public fun <T> MutableSharedFlow(
Expand Down