Introduce SubclassOptInRequired to the codebase (#4115)

The initial stage of #3770

Marked:
* Job,
* Deferred and CompletableDeferred,
* SharedFlow, StateFlow,
* CancellableContinuation,
* All of their `public` implementors.

Author: dkhalanskyjb

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

@@ -367,6 +367,9 @@ public final class kotlinx/coroutines/ExecutorsKt {
 public abstract interface annotation class kotlinx/coroutines/ExperimentalCoroutinesApi : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class kotlinx/coroutines/ExperimentalForInheritanceCoroutinesApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class kotlinx/coroutines/FlowPreview : java/lang/annotation/Annotation {
 }
 
@@ -378,6 +381,9 @@ public final class kotlinx/coroutines/GlobalScope : kotlinx/coroutines/Coroutine
 public abstract interface annotation class kotlinx/coroutines/InternalCoroutinesApi : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class kotlinx/coroutines/InternalForInheritanceCoroutinesApi : java/lang/annotation/Annotation {
+}
+
 public final class kotlinx/coroutines/InterruptibleKt {
 	public static final fun runInterruptible (Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function0;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun runInterruptible$default (Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function0;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;

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

@@ -764,12 +764,18 @@ open annotation class kotlinx.coroutines/DelicateCoroutinesApi : kotlin/Annotati
 open annotation class kotlinx.coroutines/ExperimentalCoroutinesApi : kotlin/Annotation { // kotlinx.coroutines/ExperimentalCoroutinesApi|null[0]
     constructor <init>() // kotlinx.coroutines/ExperimentalCoroutinesApi.<init>|<init>(){}[0]
 }
+open annotation class kotlinx.coroutines/ExperimentalForInheritanceCoroutinesApi : kotlin/Annotation { // kotlinx.coroutines/ExperimentalForInheritanceCoroutinesApi|null[0]
+    constructor <init>() // kotlinx.coroutines/ExperimentalForInheritanceCoroutinesApi.<init>|<init>(){}[0]
+}
 open annotation class kotlinx.coroutines/FlowPreview : kotlin/Annotation { // kotlinx.coroutines/FlowPreview|null[0]
     constructor <init>() // kotlinx.coroutines/FlowPreview.<init>|<init>(){}[0]
 }
 open annotation class kotlinx.coroutines/InternalCoroutinesApi : kotlin/Annotation { // kotlinx.coroutines/InternalCoroutinesApi|null[0]
     constructor <init>() // kotlinx.coroutines/InternalCoroutinesApi.<init>|<init>(){}[0]
 }
+open annotation class kotlinx.coroutines/InternalForInheritanceCoroutinesApi : kotlin/Annotation { // kotlinx.coroutines/InternalForInheritanceCoroutinesApi|null[0]
+    constructor <init>() // kotlinx.coroutines/InternalForInheritanceCoroutinesApi.<init>|<init>(){}[0]
+}
 open annotation class kotlinx.coroutines/ObsoleteCoroutinesApi : kotlin/Annotation { // kotlinx.coroutines/ObsoleteCoroutinesApi|null[0]
     constructor <init>() // kotlinx.coroutines/ObsoleteCoroutinesApi.<init>|<init>(){}[0]
 }

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

@@ -30,6 +30,7 @@ import kotlin.coroutines.*
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @InternalCoroutinesApi
 public abstract class AbstractCoroutine<in T>(
     parentContext: CoroutineContext,

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

@@ -90,3 +90,29 @@ public annotation class ObsoleteCoroutinesApi
             "so stable API could be provided instead"
 )
 public annotation class InternalCoroutinesApi
+
+/**
+ * Marks declarations that cannot be safely inherited from.
+ */
+@Target(AnnotationTarget.CLASS)
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING, message =
+    "Inheriting from this kotlinx.coroutines API is unstable. " +
+        "Either new methods may be added in the future, which would break the inheritance, " +
+        "or correctly inheriting from it requires fulfilling contracts that may change in the future."
+)
+public annotation class ExperimentalForInheritanceCoroutinesApi
+
+/**
+ * Marks declarations that cannot be safely inherited from.
+ */
+@Target(AnnotationTarget.CLASS)
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING, message =
+    "This is a kotlinx.coroutines API that is not intended to be inherited from, " +
+        "as the library may handle predefined instances of this in a special manner. " +
+        "This will be an error in a future release. " +
+        "If you need to inherit from this, please describe your use case in " +
+        "https://github.com/Kotlin/kotlinx.coroutines/issues, so that we can provide a stable API for inheritance. "
+)
+public annotation class InternalForInheritanceCoroutinesApi

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

@@ -88,6 +88,7 @@ public fun <T> CoroutineScope.async(
     return coroutine
 }
 
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @Suppress("UNCHECKED_CAST")
 private open class DeferredCoroutine<T>(
     parentContext: CoroutineContext,

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

@@ -41,6 +41,8 @@ import kotlin.coroutines.intrinsics.*
  *    +-----------+
  * ```
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(InternalForInheritanceCoroutinesApi::class)
 public interface CancellableContinuation<in T> : Continuation<T> {
     /**
      * Returns `true` when this continuation is active -- it has not completed or cancelled yet.

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

@@ -25,6 +25,7 @@ internal val RESUME_TOKEN = Symbol("RESUME_TOKEN")
 /**
  * @suppress **This is unstable API and it is subject to change.**
  */
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @PublishedApi
 internal open class CancellableContinuationImpl<in T>(
     final override val delegate: Continuation<T>,

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

@@ -15,10 +15,9 @@ import kotlinx.coroutines.selects.*
  *
  * All functions on this interface are **thread-safe** and can
  * be safely invoked from concurrent coroutines without external synchronization.
- *
- * **The `CompletableDeferred` interface is not stable for inheritance in 3rd party libraries**,
- * as new methods might be added to this interface in the future, but is stable for use.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(markerClass = InternalForInheritanceCoroutinesApi::class)
 public interface CompletableDeferred<T> : Deferred<T> {
     /**
      * Completes this deferred value with a given [value]. The result is `true` if this deferred was
@@ -73,6 +72,7 @@ public fun <T> CompletableDeferred(value: T): CompletableDeferred<T> = Completab
 /**
  * Concrete implementation of [CompletableDeferred].
  */
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @Suppress("UNCHECKED_CAST")
 private class CompletableDeferredImpl<T>(
     parent: Job?

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

@@ -10,6 +10,8 @@ package kotlinx.coroutines
  * **The `CompletableJob` interface is not stable for inheritance in 3rd party libraries**,
  * as new methods might be added to this interface in the future, but is stable for use.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(markerClass = InternalForInheritanceCoroutinesApi::class)
 public interface CompletableJob : Job {
     /**
      * Completes this job. The result is `true` if this job was completed as a result of this invocation and

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

@@ -26,10 +26,9 @@ import kotlinx.coroutines.selects.*
  *
  * All functions on this interface and on all interfaces derived from it are **thread-safe** and can
  * be safely invoked from concurrent coroutines without external synchronization.
- *
- * **`Deferred` interface and all its derived interfaces are not stable for inheritance in 3rd party libraries**,
- * as new methods might be added to this interface in the future, but is stable for use.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(markerClass = InternalForInheritanceCoroutinesApi::class)
 public interface Deferred<out T> : Job {
 
     /**

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

@@ -99,12 +99,9 @@ import kotlin.jvm.*
  *
  * All functions on this interface and on all interfaces derived from it are **thread-safe** and can
  * be safely invoked from concurrent coroutines without external synchronization.
- *
- * ### Not stable for inheritance
- *
- * **`Job` interface and all its derived interfaces are not stable for inheritance in 3rd party libraries**,
- * as new methods might be added to this interface in the future, but is stable for use.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(markerClass = InternalForInheritanceCoroutinesApi::class)
 public interface Job : CoroutineContext.Element {
     /**
      * Key for [Job] instance in the coroutine context.
@@ -404,6 +401,7 @@ public fun interface DisposableHandle {
  */
 @InternalCoroutinesApi
 @Deprecated(level = DeprecationLevel.ERROR, message = "This is internal API and may be removed in the future releases")
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 public interface ChildJob : Job {
     /**
      * Parent is cancelling its child by invoking this method.
@@ -423,6 +421,7 @@ public interface ChildJob : Job {
  */
 @InternalCoroutinesApi
 @Deprecated(level = DeprecationLevel.ERROR, message = "This is internal API and may be removed in the future releases")
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 public interface ParentJob : Job {
     /**
      * Child job is using this method to learn its cancellation cause when the parent cancels it with [ChildJob.parentCancelled].

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

@@ -19,6 +19,7 @@ import kotlin.jvm.*
  * @param active when `true` the job is created in _active_ state, when `false` in _new_ state. See [Job] for details.
  * @suppress **This is unstable API and it is subject to change.**
  */
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @Deprecated(level = DeprecationLevel.ERROR, message = "This is internal API and may be removed in the future releases")
 public open class JobSupport constructor(active: Boolean) : Job, ChildJob, ParentJob {
     final override val key: CoroutineContext.Key<*> get() = Job
@@ -1419,6 +1420,7 @@ private class Empty(override val isActive: Boolean) : Incomplete {
     override fun toString(): String = "Empty{${if (isActive) "Active" else "New" }}"
 }
 
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @PublishedApi // for a custom job in the test module
 internal open class JobImpl(parent: Job?) : JobSupport(true), CompletableJob {
     init { initParentJob(parent) }

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

@@ -21,6 +21,7 @@ import kotlin.coroutines.*
  * when the parent is cancelled, the whole parent-child relation between parent and child is severed.
  * The parent will not wait for the child's completion, nor will be cancelled when the child crashed.
  */
+@OptIn(InternalForInheritanceCoroutinesApi::class)
 @Suppress("DeprecatedCallableAddReplaceWith")
 public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
 

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

@@ -119,6 +119,8 @@ import kotlin.jvm.*
  * might be added to this interface in the future, but is stable for use.
  * Use the `MutableSharedFlow(replay, ...)` constructor function to create an implementation.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(ExperimentalForInheritanceCoroutinesApi::class)
 public interface SharedFlow<out T> : Flow<T> {
     /**
      * A snapshot of the replay cache.
@@ -170,6 +172,8 @@ public interface SharedFlow<out T> : Flow<T> {
  * might be added to this interface in the future, but is stable for use.
  * Use the `MutableSharedFlow(...)` constructor function to create an implementation.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(ExperimentalForInheritanceCoroutinesApi::class)
 public interface MutableSharedFlow<T> : SharedFlow<T>, FlowCollector<T> {
     /**
      * Emits a [value] to this shared flow, suspending on buffer overflow.
@@ -309,6 +313,7 @@ internal class SharedFlowSlot : AbstractSharedFlowSlot<SharedFlowImpl<*>>() {
     }
 }
 
+@OptIn(ExperimentalForInheritanceCoroutinesApi::class)
 internal open class SharedFlowImpl<T>(
     private val replay: Int,
     private val bufferCapacity: Int,

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

@@ -130,6 +130,8 @@ import kotlin.coroutines.*
  * might be added to this interface in the future, but is stable for use.
  * Use the `MutableStateFlow(value)` constructor function to create an implementation.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(ExperimentalForInheritanceCoroutinesApi::class)
 public interface StateFlow<out T> : SharedFlow<T> {
     /**
      * The current value of this state flow.
@@ -151,6 +153,8 @@ public interface StateFlow<out T> : SharedFlow<T> {
  * might be added to this interface in the future, but is stable for use.
  * Use the `MutableStateFlow()` constructor function to create an implementation.
  */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(ExperimentalForInheritanceCoroutinesApi::class)
 public interface MutableStateFlow<T> : StateFlow<T>, MutableSharedFlow<T> {
     /**
      * The current value of this state flow.
@@ -305,6 +309,7 @@ private class StateFlowSlot : AbstractSharedFlowSlot<StateFlowImpl<*>>() {
     }
 }
 
+@OptIn(ExperimentalForInheritanceCoroutinesApi::class)
 private class StateFlowImpl<T>(
     initialState: Any // T | NULL
 ) : AbstractSharedFlow<StateFlowSlot>(), MutableStateFlow<T>, CancellableFlow<T>, FusibleFlow<T> {

kotlinx-coroutines-core/common/src/flow/internal/AbstractSharedFlow.kt

@@ -1,5 +1,6 @@
 package kotlinx.coroutines.flow.internal
 
+import kotlinx.coroutines.*
 import kotlinx.coroutines.channels.*
 import kotlinx.coroutines.flow.*
 import kotlinx.coroutines.internal.*
@@ -113,6 +114,7 @@ internal abstract class AbstractSharedFlow<S : AbstractSharedFlowSlot<*>> : Sync
  *
  * To avoid that (especially in a more complex scenarios), we do not conflate subscription updates.
  */
+@OptIn(ExperimentalForInheritanceCoroutinesApi::class)
 private class SubscriptionCountStateFlow(initialValue: Int) : StateFlow<Int>,
     SharedFlowImpl<Int>(1, Int.MAX_VALUE, BufferOverflow.DROP_OLDEST)
 {

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

@@ -363,6 +363,7 @@ public fun <T> MutableSharedFlow<T>.asSharedFlow(): SharedFlow<T> =
 public fun <T> MutableStateFlow<T>.asStateFlow(): StateFlow<T> =
     ReadonlyStateFlow(this, null)
 
+@OptIn(ExperimentalForInheritanceCoroutinesApi::class)
 private class ReadonlySharedFlow<T>(
     flow: SharedFlow<T>,
     @Suppress("unused")
@@ -372,6 +373,7 @@ private class ReadonlySharedFlow<T>(
         fuseSharedFlow(context, capacity, onBufferOverflow)
 }
 
+@OptIn(ExperimentalForInheritanceCoroutinesApi::class)
 private class ReadonlyStateFlow<T>(
     flow: StateFlow<T>,
     @Suppress("unused")
@@ -397,6 +399,7 @@ private class ReadonlyStateFlow<T>(
 public fun <T> SharedFlow<T>.onSubscription(action: suspend FlowCollector<T>.() -> Unit): SharedFlow<T> =
     SubscribedSharedFlow(this, action)
 
+@OptIn(ExperimentalForInheritanceCoroutinesApi::class)
 private class SubscribedSharedFlow<T>(
     private val sharedFlow: SharedFlow<T>,
     private val action: suspend FlowCollector<T>.() -> Unit

kotlinx-coroutines-core/common/src/sync/Mutex.kt

@@ -243,6 +243,7 @@ internal open class MutexImpl(locked: Boolean) : SemaphoreImpl(1, if (locked) 1
         return this
     }
 
+    @OptIn(InternalForInheritanceCoroutinesApi::class)
     private inner class CancellableContinuationWithOwner(
         @JvmField
         val cont: CancellableContinuationImpl<Unit>,