Update experimental declarations (#2316)

* Gracefully increase deprecation level on Channel operators instead of removing them, a warning was not strict enough
* Remove hidden onCompletion from -M release
* Promote StateFlow and SharedFlow to stable API
* Lift out experimentality where it is applicable

    * CoroutineDispatcher.invoke
    * ReceiveChannel.consume and ReceiveChannel.consumeEach
    * Flow core operators: onStart, onCompletion, onEmpty
    * CompletableDeferred.completeWith
    * awaitCancellation
    * Add experimentality notes where applicable

benchmarks/src/jmh/kotlin/benchmarks/ChannelSinkBenchmark.kt

@@ -50,4 +50,22 @@ open class ChannelSinkBenchmark {
         for (i in start until (start + count))
             send(i)
     }
+
+    // Migrated from deprecated operators, are good only for stressing channels
+
+    private fun <E> ReceiveChannel<E>.filter(context: CoroutineContext = Dispatchers.Unconfined, predicate: suspend (E) -> Boolean): ReceiveChannel<E> =
+        GlobalScope.produce(context, onCompletion = { cancel() }) {
+            for (e in this@filter) {
+                if (predicate(e)) send(e)
+            }
+        }
+
+    private suspend inline fun <E, R> ReceiveChannel<E>.fold(initial: R, operation: (acc: R, E) -> R): R {
+        var accumulator = initial
+        consumeEach {
+            accumulator = operation(accumulator, it)
+        }
+        return accumulator
+    }
 }
+

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

@@ -992,7 +992,6 @@ public final class kotlinx/coroutines/flow/FlowKt {
 	public static final fun merge (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun merge ([Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun observeOn (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/flow/Flow;
-	public static final synthetic fun onCompletion (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun onCompletion (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun onEach (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun onEmpty (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;

kotlinx-coroutines-core/common/src/Builders.common.kt

@@ -175,7 +175,6 @@ public suspend fun <T> withContext(
  *
  * This inline function calls [withContext].
  */
-@ExperimentalCoroutinesApi
 public suspend inline operator fun <T> CoroutineDispatcher.invoke(
     noinline block: suspend CoroutineScope.() -> T
 ): T = withContext(this, block)

kotlinx-coroutines-core/common/src/CompletableDeferred.kt

@@ -57,7 +57,6 @@ public interface CompletableDeferred<T> : Deferred<T> {
  * This function transitions this deferred in the same ways described by [CompletableDeferred.complete] and
  * [CompletableDeferred.completeExceptionally].
  */
-@ExperimentalCoroutinesApi // since 1.3.2, tentatively until 1.4.0
 public fun <T> CompletableDeferred<T>.completeWith(result: Result<T>): Boolean =
     result.fold({ complete(it) }, { completeExceptionally(it) })
 

kotlinx-coroutines-core/common/src/CoroutineStart.kt

@@ -55,7 +55,7 @@ public enum class CoroutineStart {
      * Cancellability of coroutine at suspension points depends on the particular implementation details of
      * suspending functions as in [DEFAULT].
      */
-    @ExperimentalCoroutinesApi
+    @ExperimentalCoroutinesApi // Since 1.0.0, no ETA on stability
     ATOMIC,
 
     /**
@@ -71,7 +71,7 @@ public enum class CoroutineStart {
      *
      * **Note: This is an experimental api.** Execution semantics of coroutines may change in the future when this mode is used.
      */
-    @ExperimentalCoroutinesApi
+    @ExperimentalCoroutinesApi  // Since 1.0.0, no ETA on stability
     UNDISPATCHED;
 
     /**

kotlinx-coroutines-core/common/src/Debug.common.kt

@@ -27,7 +27,7 @@ internal expect fun assert(value: () -> Boolean)
  * Copy mechanism is used only on JVM, but it might be convenient to implement it in common exceptions,
  * so on JVM their stacktraces will be properly recovered.
  */
-@ExperimentalCoroutinesApi
+@ExperimentalCoroutinesApi // Since 1.2.0, no ETA on stability
 public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable<T> {
 
     /**

kotlinx-coroutines-core/common/src/Delay.kt

@@ -95,7 +95,6 @@ public interface Delay {
  * }
  * ```
  */
-@ExperimentalCoroutinesApi
 public suspend fun awaitCancellation(): Nothing = suspendCancellableCoroutine {}
 
 /**

kotlinx-coroutines-core/common/src/channels/Broadcast.kt

@@ -47,7 +47,7 @@ public fun <E> ReceiveChannel<E>.broadcast(
     val scope = GlobalScope + Dispatchers.Unconfined + CoroutineExceptionHandler { _, _ -> }
     // We can run this coroutine in the context that ignores all exceptions, because of `onCompletion = consume()`
     // which passes all exceptions upstream to the source ReceiveChannel
-    return scope.broadcast(capacity = capacity, start = start, onCompletion = consumes()) {
+    return scope.broadcast(capacity = capacity, start = start, onCompletion = { cancelConsumed(it) }) {
         for (e in this@broadcast) {
             send(e)
         }

kotlinx-coroutines-core/common/src/channels/BufferOverflow.kt

@@ -16,7 +16,6 @@ import kotlinx.coroutines.*
  * * [DROP_LATEST] — drop **the latest** value that is being added to the buffer right now on buffer overflow
  *   (so that buffer contents stay the same), do not suspend.
  */
-@ExperimentalCoroutinesApi
 public enum class BufferOverflow {
     /**
      * Suspend on buffer overflow.