Introduce CloseableCoroutineDispatcher abstract class (#2903)

* Introduce CloseableCoroutineDispatcher abstract class
* Alias it to ExecutorCoroutineDispatcher on JVM as the most appropriate candidate
* Add abstract classes to JVM and Native
* This class will be implemented by new dispatchers for K/N new memory model

Co-authored-by: dkhalanskyjb <52952525+dkhalanskyjb@users.noreply.github.com>

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

@@ -30,6 +30,19 @@ public annotation class DelicateCoroutinesApi
  */
 @MustBeDocumented
 @Retention(value = AnnotationRetention.BINARY)
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.ANNOTATION_CLASS,
+    AnnotationTarget.PROPERTY,
+    AnnotationTarget.FIELD,
+    AnnotationTarget.LOCAL_VARIABLE,
+    AnnotationTarget.VALUE_PARAMETER,
+    AnnotationTarget.CONSTRUCTOR,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY_GETTER,
+    AnnotationTarget.PROPERTY_SETTER,
+    AnnotationTarget.TYPEALIAS
+)
 @RequiresOptIn(level = RequiresOptIn.Level.WARNING)
 public annotation class ExperimentalCoroutinesApi
 

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

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+/**
+ * [CoroutineDispatcher] that provides a method to close it,
+ * causing the rejection of any new tasks and cleanup of all underlying resources
+ * associated with the current dispatcher.
+ * Examples of closeable dispatchers are dispatchers backed by `java.lang.Executor` and
+ * by `kotlin.native.Worker`.
+ *
+ * **The `CloseableCoroutineDispatcher` class 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.
+ */
+@ExperimentalCoroutinesApi
+public expect abstract class CloseableCoroutineDispatcher() : CoroutineDispatcher {
+
+    /**
+     * Initiate the closing sequence of the coroutine dispatcher.
+     * After a successful call to [close], no new tasks will
+     * be accepted to be [dispatched][dispatch], but the previously dispatched tasks will be run.
+     *
+     * Invocations of `close` are idempotent and thread-safe.
+     */
+    public abstract fun close()
+}

kotlinx-coroutines-core/js/src/CloseableCoroutineDispatcher.kt

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+public actual abstract class CloseableCoroutineDispatcher actual constructor() : CoroutineDispatcher() {
+    public actual abstract fun close()
+}

kotlinx-coroutines-core/jvm/src/Executors.kt

@@ -37,6 +37,9 @@ public abstract class ExecutorCoroutineDispatcher: CoroutineDispatcher(), Closea
     public abstract override fun close()
 }
 
+@ExperimentalCoroutinesApi
+public actual typealias CloseableCoroutineDispatcher = ExecutorCoroutineDispatcher
+
 /**
  * Converts an instance of [ExecutorService] to an implementation of [ExecutorCoroutineDispatcher].
  *

kotlinx-coroutines-core/native/src/CloseableCoroutineDispatcher.kt

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+public actual abstract class CloseableCoroutineDispatcher actual constructor() : CoroutineDispatcher() {
+    public actual abstract fun close()
+}