Mark Flow declarations as experimental

Author: qwwdfsad

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

@@ -18,13 +18,15 @@ import kotlinx.coroutines.flow.Flow
 public annotation class ExperimentalCoroutinesApi
 
 /**
- * Marks all [Flow] declarations as a feature preview to indicate that [Flow] is still experimental and has a 'preview' status.
+ * Marks [Flow]-related API as a feature preview.
  *
  * Flow preview has **no** backward compatibility guarantees, including both binary and source compatibility.
  * Its API and semantics can and will be changed in next releases.
  *
  * Feature preview can be used to evaluate its real-world strengths and weaknesses, gather and provide feedback.
  * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to a stable API.
+ *
+ * The best way to speed up preview feature promotion is providing the feedback on the feature.
  */
 @MustBeDocumented
 @Retention(value = AnnotationRetention.BINARY)

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

@@ -44,7 +44,7 @@ import kotlin.jvm.*
  * ```
  * If you want to switch the context of execution of a flow, use the [flowOn] operator.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> flow(@BuilderInference block: suspend FlowCollector<T>.() -> Unit): Flow<T> {
     return object : Flow<T> {
         override suspend fun collect(collector: FlowCollector<T>) {
@@ -57,7 +57,6 @@ public fun <T> flow(@BuilderInference block: suspend FlowCollector<T>.() -> Unit
  * An analogue of the [flow] builder that does not check the context of execution of the resulting flow.
  * Used in our own operators where we trust the context of invocations.
  */
-@FlowPreview
 @PublishedApi
 internal inline fun <T> unsafeFlow(@BuilderInference crossinline block: suspend FlowCollector<T>.() -> Unit): Flow<T> {
     return object : Flow<T> {
@@ -91,7 +90,7 @@ public fun <T> (suspend () -> T).asFlow(): Flow<T> = unsafeFlow {
 /**
  * Creates a flow that produces values from the given iterable.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Iterable<T>.asFlow(): Flow<T> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -101,7 +100,7 @@ public fun <T> Iterable<T>.asFlow(): Flow<T> = unsafeFlow {
 /**
  * Creates a flow that produces values from the given iterable.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Iterator<T>.asFlow(): Flow<T> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -111,7 +110,7 @@ public fun <T> Iterator<T>.asFlow(): Flow<T> = unsafeFlow {
 /**
  * Creates a flow that produces values from the given sequence.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Sequence<T>.asFlow(): Flow<T> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -121,7 +120,7 @@ public fun <T> Sequence<T>.asFlow(): Flow<T> = unsafeFlow {
 /**
  * Creates a flow that produces values from the given array of elements.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> flowOf(vararg elements: T): Flow<T> = unsafeFlow {
     for (element in elements) {
         emit(element)
@@ -131,7 +130,7 @@ public fun <T> flowOf(vararg elements: T): Flow<T> = unsafeFlow {
 /**
  * Creates flow that produces a given [value].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> flowOf(value: T): Flow<T> = unsafeFlow {
     /*
      * Implementation note: this is just an "optimized" overload of flowOf(vararg)
@@ -143,7 +142,7 @@ public fun <T> flowOf(value: T): Flow<T> = unsafeFlow {
 /**
  * Returns an empty flow.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> emptyFlow(): Flow<T> = EmptyFlow
 
 private object EmptyFlow : Flow<Nothing> {
@@ -153,7 +152,7 @@ private object EmptyFlow : Flow<Nothing> {
 /**
  * Creates a flow that produces values from the given array.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Array<T>.asFlow(): Flow<T> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -163,7 +162,7 @@ public fun <T> Array<T>.asFlow(): Flow<T> = unsafeFlow {
 /**
  * Creates flow that produces values from the given array.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun IntArray.asFlow(): Flow<Int> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -173,7 +172,7 @@ public fun IntArray.asFlow(): Flow<Int> = unsafeFlow {
 /**
  * Creates flow that produces values from the given array.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun LongArray.asFlow(): Flow<Long> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -183,7 +182,7 @@ public fun LongArray.asFlow(): Flow<Long> = unsafeFlow {
 /**
  * Creates flow that produces values from the given range.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun IntRange.asFlow(): Flow<Int> = unsafeFlow {
     forEach { value ->
         emit(value)
@@ -193,7 +192,7 @@ public fun IntRange.asFlow(): Flow<Int> = unsafeFlow {
 /**
  * Creates flow that produces values from the given range.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun LongRange.asFlow(): Flow<Long> = flow {
     forEach { value ->
         emit(value)
@@ -262,7 +261,7 @@ public fun <T> flowViaChannel(
  * }
  * ```
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> channelFlow(@BuilderInference block: suspend ProducerScope<T>.() -> Unit): Flow<T> =
     ChannelFlowBuilder(block)
 
@@ -310,6 +309,7 @@ public fun <T> channelFlow(@BuilderInference block: suspend ProducerScope<T>.()
  * ```
  */
 @Suppress("NOTHING_TO_INLINE")
+@ExperimentalCoroutinesApi
 public inline fun <T> callbackFlow(@BuilderInference noinline block: suspend ProducerScope<T>.() -> Unit): Flow<T> =
     channelFlow(block)
 

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

@@ -109,7 +109,7 @@ import kotlinx.coroutines.*
  * Flow is [Reactive Streams](http://www.reactive-streams.org/) compliant, you can safely interop it with
  * reactive streams using [Flow.asPublisher] and [Publisher.asFlow] from kotlinx-coroutines-reactive module.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public interface Flow<out T> {
 
     /**

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

@@ -13,7 +13,7 @@ import kotlinx.coroutines.*
  * This interface should usually not be implemented directly, but rather used as a receiver in a [flow] builder when implementing a custom operator.
  * Implementations of this interface are not thread-safe.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public interface FlowCollector<in T> {
 
     /**

kotlinx-coroutines-core/common/src/flow/operators/Context.kt

@@ -104,7 +104,7 @@ import kotlin.jvm.*
  * [RENDEZVOUS][Channel.RENDEZVOUS], [UNLIMITED][Channel.UNLIMITED] or a non-negative value indicating
  * an explicitly requested size.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T> {
     require(capacity >= 0 || capacity == BUFFERED || capacity == CONFLATED) {
         "Buffer size should be non-negative, BUFFERED, or CONFLATED, but was $capacity"
@@ -147,7 +147,7 @@ public fun <T> Flow<T>.buffer(capacity: Int = BUFFERED): Flow<T> {
  * always fused so that only one properly configured channel is used for execution.
  * **Conflation takes precedence over `buffer()` calls with any other capacity.**
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.conflate(): Flow<T> = buffer(CONFLATED)
 
 /**
@@ -194,7 +194,7 @@ public fun <T> Flow<T>.conflate(): Flow<T> = buffer(CONFLATED)
  *
  * @throws [IllegalArgumentException] if provided context contains [Job] instance.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.flowOn(context: CoroutineContext): Flow<T> {
     checkFlowContext(context)
     return when {

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

@@ -17,7 +17,7 @@ import kotlinx.coroutines.flow.unsafeFlow as flow
 /**
  * Delays the emission of values from this flow for the given [timeMillis].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.delayFlow(timeMillis: Long): Flow<T> = flow {
     delay(timeMillis)
     collect(this@flow)
@@ -26,7 +26,7 @@ public fun <T> Flow<T>.delayFlow(timeMillis: Long): Flow<T> = flow {
 /**
  * Delays each element emitted by the given flow for the given [timeMillis].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.delayEach(timeMillis: Long): Flow<T> = flow {
     collect { value ->
         delay(timeMillis)
@@ -58,6 +58,7 @@ public fun <T> Flow<T>.delayEach(timeMillis: Long): Flow<T> = flow {
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeoutMillis] milliseconds.
  */
+@FlowPreview
 public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
     require(timeoutMillis > 0) { "Debounce timeout should be positive" }
     return scopedFlow { downstream ->
@@ -109,6 +110,7 @@ public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
  * 
  * Note that the latest element is not emitted if it does not fit into the sampling window.
  */
+@FlowPreview
 public fun <T> Flow<T>.sample(periodMillis: Long): Flow<T> {
     require(periodMillis > 0) { "Sample period should be positive" }
     return scopedFlow { downstream ->

kotlinx-coroutines-core/common/src/flow/operators/Distinct.kt

@@ -15,7 +15,7 @@ import kotlinx.coroutines.flow.unsafeFlow as flow
 /**
  * Returns flow where all subsequent repetitions of the same value are filtered out.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.distinctUntilChanged(): Flow<T> = distinctUntilChangedBy { it }
 
 /**

kotlinx-coroutines-core/common/src/flow/operators/Limit.kt

@@ -17,7 +17,7 @@ import kotlinx.coroutines.flow.unsafeFlow as flow
  * Returns a flow that ignores first [count] elements.
  * Throws [IllegalArgumentException] if [count] is negative.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.drop(count: Int): Flow<T> {
     require(count >= 0) { "Drop count should be non-negative, but had $count" }
     return flow {
@@ -31,7 +31,7 @@ public fun <T> Flow<T>.drop(count: Int): Flow<T> {
 /**
  * Returns a flow containing all elements except first elements that satisfy the given predicate.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.dropWhile(predicate: suspend (T) -> Boolean): Flow<T> = flow {
     var matched = false
     collect { value ->
@@ -49,7 +49,7 @@ public fun <T> Flow<T>.dropWhile(predicate: suspend (T) -> Boolean): Flow<T> = f
  * When [count] elements are consumed, the original flow is cancelled.
  * Throws [IllegalArgumentException] if [count] is not positive.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.take(count: Int): Flow<T> {
     require(count > 0) { "Requested element count $count should be positive" }
     return flow {
@@ -70,7 +70,7 @@ public fun <T> Flow<T>.take(count: Int): Flow<T> {
 /**
  * Returns a flow that contains first elements satisfying the given [predicate].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.takeWhile(predicate: suspend (T) -> Boolean): Flow<T> = flow {
     try {
         collect { value ->

kotlinx-coroutines-core/common/src/flow/operators/Merge.kt

@@ -124,7 +124,7 @@ public fun <T> Flow<Flow<T>>.flattenMerge(concurrency: Int = DEFAULT_CONCURRENCY
  * ```
  * produces `aa bb b_last`
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T, R> Flow<T>.switchMap(transform: suspend (value: T) -> Flow<R>): Flow<R> = scopedFlow { downstream ->
     var previousFlow: Job? = null
     collect { value ->

kotlinx-coroutines-core/common/src/flow/operators/Transform.kt

@@ -27,7 +27,7 @@ import kotlinx.coroutines.flow.unsafeFlow as flow
  * }
  * ```
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public inline fun <T, R> Flow<T>.transform(@BuilderInference crossinline transform: suspend FlowCollector<R>.(value: T) -> Unit): Flow<R> {
     return flow {
         collect { value ->
@@ -40,7 +40,7 @@ public inline fun <T, R> Flow<T>.transform(@BuilderInference crossinline transfo
 /**
  * Returns a flow containing only values of the original flow that matches the given [predicate].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public inline fun <T> Flow<T>.filter(crossinline predicate: suspend (T) -> Boolean): Flow<T> = flow {
     collect { value ->
         if (predicate(value)) return@collect emit(value)
@@ -50,7 +50,7 @@ public inline fun <T> Flow<T>.filter(crossinline predicate: suspend (T) -> Boole
 /**
  * Returns a flow containing only values of the original flow that do not match the given [predicate].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public inline fun <T> Flow<T>.filterNot(crossinline predicate: suspend (T) -> Boolean): Flow<T> = flow {
     collect { value ->
         if (!predicate(value)) return@collect emit(value)
@@ -60,30 +60,30 @@ public inline fun <T> Flow<T>.filterNot(crossinline predicate: suspend (T) -> Bo
 /**
  * Returns a flow containing only values that are instances of specified type [R].
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 @Suppress("UNCHECKED_CAST")
 public inline fun <reified R> Flow<*>.filterIsInstance(): Flow<R> = filter { it is R } as Flow<R>
 
 /**
  * Returns a flow containing only values of the original flow that are not null.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T: Any> Flow<T?>.filterNotNull(): Flow<T> = flow<T> {
     collect { value -> if (value != null) return@collect  emit(value) }
 }
 
 /**
  * Returns a flow containing the results of applying the given [transform] function to each value of the original flow.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public inline fun <T, R> Flow<T>.map(crossinline transform: suspend (value: T) -> R): Flow<R> = transform { value ->
    return@transform emit(transform(value))
 }
 
 /**
  * Returns a flow that contains only non-null results of applying the given [transform] function to each value of the original flow.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public inline fun <T, R: Any> Flow<T>.mapNotNull(crossinline transform: suspend (value: T) -> R?): Flow<R> = transform { value ->
     val transformed = transform(value) ?: return@transform
     return@transform emit(transformed)
@@ -92,7 +92,7 @@ public inline fun <T, R: Any> Flow<T>.mapNotNull(crossinline transform: suspend
 /**
  * Returns a flow which performs the given [action] on each value of the original flow.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.onEach(action: suspend (T) -> Unit): Flow<T> = flow {
     collect { value ->
         action(value)
@@ -109,7 +109,7 @@ public fun <T> Flow<T>.onEach(action: suspend (T) -> Unit): Flow<T> = flow {
  * ```
  * will produce `[], [1], [1, 2], [1, 2, 3]]`.
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T, R> Flow<T>.scan(initial: R, @BuilderInference operation: suspend (accumulator: R, value: T) -> R): Flow<R> = flow {
     var accumulator: R = initial
     emit(accumulator)
@@ -130,7 +130,7 @@ public fun <T, R> Flow<T>.scan(initial: R, @BuilderInference operation: suspend
  * ```
  * will produce `[1, 3, 6, 10]`
  */
-@FlowPreview
+@ExperimentalCoroutinesApi
 public fun <T> Flow<T>.scanReduce(operation: suspend (accumulator: T, value: T) -> T): Flow<T> = flow {
     var accumulator: Any? = NULL
     collect { value ->