diff --git a/kotlinx-coroutines-core/common/src/Annotations.kt b/kotlinx-coroutines-core/common/src/Annotations.kt index 724cc8cb87..bacce39408 100644 --- a/kotlinx-coroutines-core/common/src/Annotations.kt +++ b/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 diff --git a/kotlinx-coroutines-core/common/src/CloseableCoroutineDispatcher.kt b/kotlinx-coroutines-core/common/src/CloseableCoroutineDispatcher.kt new file mode 100644 index 0000000000..9c6703291a --- /dev/null +++ b/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() +} diff --git a/kotlinx-coroutines-core/js/src/CloseableCoroutineDispatcher.kt b/kotlinx-coroutines-core/js/src/CloseableCoroutineDispatcher.kt new file mode 100644 index 0000000000..0e239a42f7 --- /dev/null +++ b/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() +} diff --git a/kotlinx-coroutines-core/jvm/src/Executors.kt b/kotlinx-coroutines-core/jvm/src/Executors.kt index 7ea3cc6874..4e98e7bc98 100644 --- a/kotlinx-coroutines-core/jvm/src/Executors.kt +++ b/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]. * diff --git a/kotlinx-coroutines-core/native/src/CloseableCoroutineDispatcher.kt b/kotlinx-coroutines-core/native/src/CloseableCoroutineDispatcher.kt new file mode 100644 index 0000000000..0e239a42f7 --- /dev/null +++ b/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() +}