Clarify thread-safety of SharedFlow methods in docs (#2399)

* Clarify thread-safety of SharedFlow methods in docs

* Override MutableSharedFlow.emit to attach a more appropriate docs than the one inherited from FlowCollector.
* Clarify thread-safety of all the MutableSharedFlow & MutableState "mutating" methods.

The latter is needed, because Flows, in general, are sequential, but shared flows provide all the necessarily synchronization themselves, so, to avoid confusion it makes sense to additionally mention thread-safety of shared flows in all the relevant mutating functions.

Author: elizarov

kotlinx-coroutines-core/api/kotlinx-coroutines-core.api

@@ -1064,6 +1064,7 @@ public final class kotlinx/coroutines/flow/LintKt {
 }
 
 public abstract interface class kotlinx/coroutines/flow/MutableSharedFlow : kotlinx/coroutines/flow/FlowCollector, kotlinx/coroutines/flow/SharedFlow {
+	public abstract fun emit (Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public abstract fun getSubscriptionCount ()Lkotlinx/coroutines/flow/StateFlow;
 	public abstract fun resetReplayCache ()V
 	public abstract fun tryEmit (Ljava/lang/Object;)Z

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

@@ -147,6 +147,17 @@ public interface SharedFlow<out T> : Flow<T> {
  * Use the `MutableSharedFlow(...)` constructor function to create an implementation.
  */
 public interface MutableSharedFlow<T> : SharedFlow<T>, FlowCollector<T> {
+    /**
+     * Emits a [value] to this shared flow, suspending on buffer overflow if the shared flow was created
+     * with the default [BufferOverflow.SUSPEND] strategy.
+     *
+     * See [tryEmit] for a non-suspending variant of this function.
+     *
+     * This method is **thread-safe** and can be safely invoked from concurrent coroutines without
+     * external synchronization.
+     */
+    override suspend fun emit(value: T)
+
     /**
      * 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]
@@ -155,6 +166,9 @@ public interface MutableSharedFlow<T> : SharedFlow<T>, FlowCollector<T> {
      * 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.
      */
     public fun tryEmit(value: T): Boolean
 
@@ -190,6 +204,9 @@ public interface MutableSharedFlow<T> : SharedFlow<T>, FlowCollector<T> {
      * supported, and throws an [UnsupportedOperationException]. To reset a [MutableStateFlow]
      * to an initial value, just update its [value][MutableStateFlow.value].
      *
+     * This method is **thread-safe** and can be safely invoked from concurrent coroutines without
+     * external synchronization.
+     *
      * **Note: This is an experimental api.** This function may be removed or renamed in the future.
      */
     @ExperimentalCoroutinesApi

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

@@ -160,6 +160,9 @@ public interface MutableStateFlow<T> : StateFlow<T>, MutableSharedFlow<T> {
      * The current value of this state flow.
      *
      * Setting a value that is [equal][Any.equals] to the previous one does nothing.
+     *
+     * This property is **thread-safe** and can be safely updated from concurrent coroutines without
+     * external synchronization.
      */
     public override var value: T
 
@@ -170,6 +173,9 @@ public interface MutableStateFlow<T> : StateFlow<T>, MutableSharedFlow<T> {
      * This function use a regular comparison using [Any.equals]. If both [expect] and [update] are equal to the
      * current [value], this function returns `true`, but it does not actually change the reference that is
      * stored in the [value].
+     *
+     * This method is **thread-safe** and can be safely invoked from concurrent coroutines without
+     * external synchronization.
      */
     public fun compareAndSet(expect: T, update: T): Boolean
 }