Deprecate BroadcastChannel and the corresponding API (#3647)

Fixes #2680

Author: qwwdfsad

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

@@ -2,6 +2,8 @@
  * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+@file:Suppress("DEPRECATION")
+
 package kotlinx.coroutines.channels
 
 import kotlinx.coroutines.*
@@ -35,13 +37,13 @@ import kotlin.coroutines.intrinsics.*
  * [send][BroadcastChannel.send] and [close][BroadcastChannel.close] operations that interfere with
  * the broadcasting coroutine in hard-to-specify ways.
  *
- * **Note: This API is obsolete since 1.5.0.** It will be deprecated with warning in 1.6.0
- * and with error in 1.7.0. It is replaced with [Flow.shareIn][kotlinx.coroutines.flow.shareIn]
- * operator.
+ * **Note: This API is obsolete since 1.5.0.** It is deprecated with warning in 1.7.0.
+ * It is replaced with [Flow.shareIn][kotlinx.coroutines.flow.shareIn] operator.
  *
  * @param start coroutine start option. The default value is [CoroutineStart.LAZY].
  */
 @ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "BroadcastChannel is deprecated in the favour of SharedFlow and is no longer supported")
 public fun <E> ReceiveChannel<E>.broadcast(
     capacity: Int = 1,
     start: CoroutineStart = CoroutineStart.LAZY
@@ -98,12 +100,11 @@ public fun <E> ReceiveChannel<E>.broadcast(
  *
  * ### Future replacement
  *
- * This API is obsolete since 1.5.0.
+ * This API is obsolete since 1.5.0 and deprecated with warning since 1.7.0.
  * This function has an inappropriate result type of [BroadcastChannel] which provides
  * [send][BroadcastChannel.send] and [close][BroadcastChannel.close] operations that interfere with
- * the broadcasting coroutine in hard-to-specify ways. It will be deprecated with warning in 1.6.0
- * and with error in 1.7.0. It is replaced with [Flow.shareIn][kotlinx.coroutines.flow.shareIn]
- * operator.
+ * the broadcasting coroutine in hard-to-specify ways.
+ * It is replaced with [Flow.shareIn][kotlinx.coroutines.flow.shareIn] operator.
  *
  * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
  * @param capacity capacity of the channel's buffer (1 by default).
@@ -112,6 +113,7 @@ public fun <E> ReceiveChannel<E>.broadcast(
  * @param block the coroutine code.
  */
 @ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "BroadcastChannel is deprecated in the favour of SharedFlow and is no longer supported")
 public fun <E> CoroutineScope.broadcast(
     context: CoroutineContext = EmptyCoroutineContext,
     capacity: Int = 1,

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

@@ -2,7 +2,7 @@
  * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("FunctionName")
+@file:Suppress("FunctionName", "DEPRECATION")
 
 package kotlinx.coroutines.channels
 
@@ -24,10 +24,11 @@ import kotlin.native.concurrent.*
  * See `BroadcastChannel()` factory function for the description of available
  * broadcast channel implementations.
  *
- * **Note: This API is obsolete since 1.5.0.** It will be deprecated with warning in 1.6.0
- * and with error in 1.7.0. It is replaced with [SharedFlow][kotlinx.coroutines.flow.SharedFlow].
+ * **Note: This API is obsolete since 1.5.0 and deprecated for removal since 1.7.0**
+ * It is replaced with [SharedFlow][kotlinx.coroutines.flow.SharedFlow].
  */
 @ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "BroadcastChannel is deprecated in the favour of SharedFlow and is no longer supported")
 public interface BroadcastChannel<E> : SendChannel<E> {
     /**
      * Subscribes to this [BroadcastChannel] and returns a channel to receive elements from it.
@@ -64,11 +65,11 @@ public interface BroadcastChannel<E> : SendChannel<E> {
  * * when `capacity` is [BUFFERED] -- creates `ArrayBroadcastChannel` with a default capacity.
  * * otherwise -- throws [IllegalArgumentException].
  *
- * **Note: This API is obsolete since 1.5.0.** It will be deprecated with warning in 1.6.0
- * and with error in 1.7.0. It is replaced with [StateFlow][kotlinx.coroutines.flow.StateFlow]
- * and [SharedFlow][kotlinx.coroutines.flow.SharedFlow].
+ * **Note: This API is obsolete since 1.5.0 and deprecated for removal since 1.7.0**
+ * It is replaced with [SharedFlow][kotlinx.coroutines.flow.SharedFlow] and [StateFlow][kotlinx.coroutines.flow.StateFlow].
  */
 @ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "BroadcastChannel is deprecated in the favour of SharedFlow and StateFlow, and is no longer supported")
 public fun <E> BroadcastChannel(capacity: Int): BroadcastChannel<E> =
     when (capacity) {
         0 -> throw IllegalArgumentException("Unsupported 0 capacity for BroadcastChannel")
@@ -92,10 +93,11 @@ public fun <E> BroadcastChannel(capacity: Int): BroadcastChannel<E> =
  * In this implementation, [opening][openSubscription] and [closing][ReceiveChannel.cancel] subscription
  * takes linear time in the number of subscribers.
  *
- * **Note: This API is obsolete since 1.5.0.** It will be deprecated with warning in 1.7.0
- * and with error in 1.8.0. It is replaced with [StateFlow][kotlinx.coroutines.flow.StateFlow].
+ * **Note: This API is obsolete since 1.5.0 and deprecated for removal since 1.7.0**
+ * It is replaced with [SharedFlow][kotlinx.coroutines.flow.StateFlow].
  */
 @ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "ConflatedBroadcastChannel is deprecated in the favour of SharedFlow and is no longer supported")
 public class ConflatedBroadcastChannel<E> private constructor(
     private val broadcast: BroadcastChannelImpl<E>
 ) : BroadcastChannel<E> by broadcast {
@@ -408,5 +410,4 @@ internal class BroadcastChannelImpl<E>(
             "SUBSCRIBERS=${subscribers.joinToString(separator = ";", prefix = "<", postfix = ">")}"
 }
 
-@SharedImmutable
-private val NO_ELEMENT = Symbol("NO_ELEMENT")
+private val NO_ELEMENT = Symbol("NO_ELEMENT")

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

@@ -3,7 +3,6 @@
  */
 @file:JvmMultifileClass
 @file:JvmName("ChannelsKt")
-@file:Suppress("DEPRECATION_ERROR")
 @file:OptIn(ExperimentalContracts::class)
 
 package kotlinx.coroutines.channels
@@ -22,10 +21,14 @@ internal const val DEFAULT_CLOSE_MESSAGE = "Channel was closed"
  * Opens subscription to this [BroadcastChannel] and makes sure that the given [block] consumes all elements
  * from it by always invoking [cancel][ReceiveChannel.cancel] after the execution of the block.
  *
- * **Note: This API will become obsolete in future updates with introduction of lazy asynchronous streams.**
- *           See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
+ * **Note: This API is obsolete since 1.5.0 and deprecated for removal since 1.7.0**
+ * It is replaced with [SharedFlow][kotlinx.coroutines.flow.SharedFlow].
+ *
+ * Safe to remove in 1.9.0 as was inline before.
  */
 @ObsoleteCoroutinesApi
+@Suppress("DEPRECATION")
+@Deprecated(level = DeprecationLevel.WARNING, message = "BroadcastChannel is deprecated in the favour of SharedFlow and is no longer supported")
 public inline fun <E, R> BroadcastChannel<E>.consume(block: ReceiveChannel<E>.() -> R): R {
     val channel = openSubscription()
     try {
@@ -51,7 +54,7 @@ public inline fun <E, R> BroadcastChannel<E>.consume(block: ReceiveChannel<E>.()
     ReplaceWith("receiveCatching().getOrNull()"),
     DeprecationLevel.ERROR
 ) // Warning since 1.5.0, ERROR in 1.6.0, HIDDEN in 1.7.0
-@Suppress("EXTENSION_SHADOWED_BY_MEMBER")
+@Suppress("EXTENSION_SHADOWED_BY_MEMBER", "DEPRECATION_ERROR")
 public suspend fun <E : Any> ReceiveChannel<E>.receiveOrNull(): E? {
     return (this as ReceiveChannel<E?>).receiveOrNull()
 }
@@ -63,6 +66,7 @@ public suspend fun <E : Any> ReceiveChannel<E>.receiveOrNull(): E? {
     "Deprecated in the favour of 'onReceiveCatching'",
     level = DeprecationLevel.ERROR
 )  // Warning since 1.5.0, ERROR in 1.6.0, HIDDEN in 1.7.0
+@Suppress("DEPRECATION_ERROR")
 public fun <E : Any> ReceiveChannel<E>.onReceiveOrNull(): SelectClause1<E?> {
     return (this as ReceiveChannel<E?>).onReceiveOrNull
 }
@@ -107,7 +111,6 @@ public suspend inline fun <E> ReceiveChannel<E>.consumeEach(action: (E) -> Unit)
  * The operation is _terminal_.
  * This function [consumes][ReceiveChannel.consume] all elements of the original [ReceiveChannel].
  */
-@OptIn(ExperimentalStdlibApi::class)
 public suspend fun <E> ReceiveChannel<E>.toList(): List<E> = buildList {
     consumeEach {
         add(it)
@@ -117,10 +120,10 @@ public suspend fun <E> ReceiveChannel<E>.toList(): List<E> = buildList {
 /**
  * Subscribes to this [BroadcastChannel] and performs the specified action for each received element.
  *
- * **Note: This API will become obsolete in future updates with introduction of lazy asynchronous streams.**
- *           See [issue #254](https://github.com/Kotlin/kotlinx.coroutines/issues/254).
+ * **Note: This API is obsolete since 1.5.0 and deprecated for removal since 1.7.0**
  */
-@ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "BroadcastChannel is deprecated in the favour of SharedFlow and is no longer supported")
+@Suppress("DEPRECATION")
 public suspend inline fun <E> BroadcastChannel<E>.consumeEach(action: (E) -> Unit): Unit =
     consume {
         for (element in this) action(element)

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

@@ -144,11 +144,12 @@ private class ChannelAsFlow<T>(
  * 2) Flow consumer completes normally when the original channel completes (~is closed) normally.
  * 3) If the flow consumer fails with an exception, subscription is cancelled.
  */
+@Suppress("DEPRECATION")
 @Deprecated(
     level = DeprecationLevel.WARNING,
     message = "'BroadcastChannel' is obsolete and all corresponding operators are deprecated " +
         "in the favour of StateFlow and SharedFlow"
-) // Since 1.5.0, was @FlowPreview, safe to remove in 1.7.0
+) // Since 1.5.0, was @FlowPreview, safe to remove in 1.8.0
 public fun <T> BroadcastChannel<T>.asFlow(): Flow<T> = flow {
     emitAll(openSubscription())
 }