Deprecate Job.cancel(cause) and ReceiveChannel.cancel(cause), return Unit from cancel without cause

Fixes #713
Fixes #481

Author: qwwdfsad

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-core.txt

@@ -76,6 +76,7 @@ public abstract interface class kotlinx/coroutines/ChildJob : kotlinx/coroutines
 }
 
 public final class kotlinx/coroutines/ChildJob$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/ChildJob;)Z
 	public static fun fold (Lkotlinx/coroutines/ChildJob;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
 	public static fun get (Lkotlinx/coroutines/ChildJob;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
 	public static fun minusKey (Lkotlinx/coroutines/ChildJob;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext;
@@ -89,6 +90,7 @@ public abstract interface class kotlinx/coroutines/CompletableDeferred : kotlinx
 }
 
 public final class kotlinx/coroutines/CompletableDeferred$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/CompletableDeferred;)Z
 	public static fun fold (Lkotlinx/coroutines/CompletableDeferred;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
 	public static fun get (Lkotlinx/coroutines/CompletableDeferred;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
 	public static fun minusKey (Lkotlinx/coroutines/CompletableDeferred;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext;
@@ -197,6 +199,7 @@ public abstract interface class kotlinx/coroutines/Deferred : kotlinx/coroutines
 }
 
 public final class kotlinx/coroutines/Deferred$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/Deferred;)Z
 	public static fun fold (Lkotlinx/coroutines/Deferred;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
 	public static fun get (Lkotlinx/coroutines/Deferred;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
 	public static fun minusKey (Lkotlinx/coroutines/Deferred;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext;
@@ -260,7 +263,8 @@ public abstract interface annotation class kotlinx/coroutines/InternalCoroutines
 public abstract interface class kotlinx/coroutines/Job : kotlin/coroutines/CoroutineContext$Element {
 	public static final field Key Lkotlinx/coroutines/Job$Key;
 	public abstract fun attachChild (Lkotlinx/coroutines/ChildJob;)Lkotlinx/coroutines/ChildHandle;
-	public abstract fun cancel ()Z
+	public abstract fun cancel ()V
+	public abstract synthetic fun cancel ()Z
 	public abstract fun cancel (Ljava/lang/Throwable;)Z
 	public abstract fun getCancellationException ()Ljava/util/concurrent/CancellationException;
 	public abstract fun getChildren ()Lkotlin/sequences/Sequence;
@@ -276,6 +280,7 @@ public abstract interface class kotlinx/coroutines/Job : kotlin/coroutines/Corou
 }
 
 public final class kotlinx/coroutines/Job$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/Job;)Z
 	public static synthetic fun cancel$default (Lkotlinx/coroutines/Job;Ljava/lang/Throwable;ILjava/lang/Object;)Z
 	public static fun fold (Lkotlinx/coroutines/Job;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
 	public static fun get (Lkotlinx/coroutines/Job;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
@@ -292,12 +297,14 @@ public final class kotlinx/coroutines/JobKt {
 	public static final fun DisposableHandle (Lkotlin/jvm/functions/Function0;)Lkotlinx/coroutines/DisposableHandle;
 	public static final fun Job (Lkotlinx/coroutines/Job;)Lkotlinx/coroutines/Job;
 	public static synthetic fun Job$default (Lkotlinx/coroutines/Job;ILjava/lang/Object;)Lkotlinx/coroutines/Job;
-	public static final fun cancel (Lkotlin/coroutines/CoroutineContext;)Z
+	public static final fun cancel (Lkotlin/coroutines/CoroutineContext;)V
+	public static final synthetic fun cancel (Lkotlin/coroutines/CoroutineContext;)Z
 	public static final fun cancel (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;)Z
 	public static synthetic fun cancel$default (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;ILjava/lang/Object;)Z
 	public static final fun cancelAndJoin (Lkotlinx/coroutines/Job;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun cancelChildren (Lkotlin/coroutines/CoroutineContext;)V
 	public static final fun cancelChildren (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;)V
+	public static final fun cancelChildren (Lkotlinx/coroutines/Job;)V
 	public static final fun cancelChildren (Lkotlinx/coroutines/Job;Ljava/lang/Throwable;)V
 	public static synthetic fun cancelChildren$default (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;ILjava/lang/Object;)V
 	public static synthetic fun cancelChildren$default (Lkotlinx/coroutines/Job;Ljava/lang/Throwable;ILjava/lang/Object;)V
@@ -309,7 +316,8 @@ public final class kotlinx/coroutines/JobKt {
 public class kotlinx/coroutines/JobSupport : kotlinx/coroutines/ChildJob, kotlinx/coroutines/Job, kotlinx/coroutines/ParentJob, kotlinx/coroutines/selects/SelectClause0 {
 	public fun <init> (Z)V
 	public final fun attachChild (Lkotlinx/coroutines/ChildJob;)Lkotlinx/coroutines/ChildHandle;
-	public fun cancel ()Z
+	public fun cancel ()V
+	public synthetic fun cancel ()Z
 	public fun cancel (Ljava/lang/Throwable;)Z
 	public fun childCancelled (Ljava/lang/Throwable;)Z
 	public fun fold (Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
@@ -349,7 +357,8 @@ public abstract class kotlinx/coroutines/MainCoroutineDispatcher : kotlinx/corou
 public final class kotlinx/coroutines/NonCancellable : kotlin/coroutines/AbstractCoroutineContextElement, kotlinx/coroutines/Job {
 	public static final field INSTANCE Lkotlinx/coroutines/NonCancellable;
 	public fun attachChild (Lkotlinx/coroutines/ChildJob;)Lkotlinx/coroutines/ChildHandle;
-	public fun cancel ()Z
+	public fun cancel ()V
+	public synthetic fun cancel ()Z
 	public fun cancel (Ljava/lang/Throwable;)Z
 	public fun getCancellationException ()Ljava/util/concurrent/CancellationException;
 	public fun getChildren ()Lkotlin/sequences/Sequence;
@@ -379,6 +388,7 @@ public abstract interface class kotlinx/coroutines/ParentJob : kotlinx/coroutine
 }
 
 public final class kotlinx/coroutines/ParentJob$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/ParentJob;)Z
 	public static fun fold (Lkotlinx/coroutines/ParentJob;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
 	public static fun get (Lkotlinx/coroutines/ParentJob;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
 	public static fun minusKey (Lkotlinx/coroutines/ParentJob;Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext;
@@ -439,6 +449,10 @@ public abstract interface class kotlinx/coroutines/channels/ActorScope : kotlinx
 	public abstract fun getChannel ()Lkotlinx/coroutines/channels/Channel;
 }
 
+public final class kotlinx/coroutines/channels/ActorScope$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/channels/ActorScope;)Z
+}
+
 public abstract interface class kotlinx/coroutines/channels/BroadcastChannel : kotlinx/coroutines/channels/SendChannel {
 	public abstract fun cancel (Ljava/lang/Throwable;)Z
 	public abstract fun openSubscription ()Lkotlinx/coroutines/channels/ReceiveChannel;
@@ -466,6 +480,10 @@ public abstract interface class kotlinx/coroutines/channels/Channel : kotlinx/co
 	public static final field UNLIMITED I
 }
 
+public final class kotlinx/coroutines/channels/Channel$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/channels/Channel;)Z
+}
+
 public final class kotlinx/coroutines/channels/Channel$Factory {
 	public static final field CONFLATED I
 	public static final field RENDEZVOUS I
@@ -637,7 +655,8 @@ public abstract interface class kotlinx/coroutines/channels/ProducerScope : kotl
 }
 
 public abstract interface class kotlinx/coroutines/channels/ReceiveChannel {
-	public abstract fun cancel ()Z
+	public abstract fun cancel ()V
+	public abstract synthetic fun cancel ()Z
 	public abstract fun cancel (Ljava/lang/Throwable;)Z
 	public abstract fun getOnReceive ()Lkotlinx/coroutines/selects/SelectClause1;
 	public abstract fun getOnReceiveOrNull ()Lkotlinx/coroutines/selects/SelectClause1;
@@ -650,6 +669,7 @@ public abstract interface class kotlinx/coroutines/channels/ReceiveChannel {
 }
 
 public final class kotlinx/coroutines/channels/ReceiveChannel$DefaultImpls {
+	public static synthetic fun cancel (Lkotlinx/coroutines/channels/ReceiveChannel;)Z
 	public static synthetic fun cancel$default (Lkotlinx/coroutines/channels/ReceiveChannel;Ljava/lang/Throwable;ILjava/lang/Object;)Z
 }
 

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

@@ -4,7 +4,7 @@
 
 @file:JvmMultifileClass
 @file:JvmName("JobKt")
-@file:Suppress("DEPRECATION_ERROR")
+@file:Suppress("DEPRECATION_ERROR", "RedundantUnitReturnType")
 
 package kotlinx.coroutines
 
@@ -154,29 +154,27 @@ public interface Job : CoroutineContext.Element {
      */
     public fun start(): Boolean
 
+    /**
+     * @suppress
+     */
+    @Suppress("INAPPLICABLE_JVM_NAME")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Left here for binary compatibility")
+    @JvmName("cancel")
+    public fun cancel0(): Boolean = cancel(null)
+
     /**
      * Cancels this job.
-     * The result is `true` if this job was either cancelled as a result of this invocation
-     * or was already being cancelled.
-     * If job is already completed, method returns `false`.
+     * See [Job] documentation for full explanation of cancellation machinery.
      */
-    public fun cancel(): Boolean
+    public fun cancel(): Unit
 
     /**
-     * Cancels this job with an optional cancellation [cause].
-     * The result is `true` if this job was either cancelled as a result of this invocation
-     * or it's being cancelled and given [cause] was successfully received by the job and will be properly handled, `false` otherwise.
-     *
-     * If this method returned `false`, then caller is responsible for handling [cause].
-     * If job is already completed, method returns `false`.
-     *
-     * When cancellation has a clear reason in the code, an instance of [CancellationException] should be created
-     * at the corresponding original cancellation site and passed into this method to aid in debugging by providing
-     * both the context of cancellation and text description of the reason.
-     *
-     * **Note: This is an experimental api.** Cancellation of a job with exception may change its semantics in the future.
+     * @suppress
      */
-    @ExperimentalCoroutinesApi
+    @ObsoleteCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = "Use CompletableDeferred.completeExceptionally(cause) or Job.cancel() instead",
+        replaceWith = ReplaceWith("cancel()")
+    )
     public fun cancel(cause: Throwable? = null): Boolean
 
     // ------------ parent-child ------------
@@ -470,14 +468,22 @@ public suspend fun Job.cancelAndJoin() {
 }
 
 /**
- * Cancels all [children][Job.children] jobs of this coroutine with the given [cause] using [Job.cancel]
- * for all of them. Unlike [Job.cancel] on this job as a whole, the state of this job itself is not affected.
+ * @suppress
  */
-@Suppress("EXTENSION_SHADOWED_BY_MEMBER") // See KT-21598
+@ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "Use cancelChildren() without cause", replaceWith = ReplaceWith("cancelChildren()"))
 public fun Job.cancelChildren(cause: Throwable? = null) {
     children.forEach { it.cancel(cause) }
 }
 
+/**
+ * Cancels all [children][Job.children] jobs of this coroutine using [Job.cancel] for all of them.
+ * Unlike [Job.cancel] on this job as a whole, the state of this job itself is not affected.
+ */
+public fun Job.cancelChildren() {
+    children.forEach { it.cancel() }
+}
+
 // -------------------- CoroutineContext extensions --------------------
 
 /**
@@ -499,22 +505,29 @@ public fun Job.cancelChildren(cause: Throwable? = null) {
 public val CoroutineContext.isActive: Boolean
     get() = this[Job]?.isActive == true
 
+
 /**
- * Cancels [Job] of this context. The result is `true` if the job was
- * cancelled as a result of this invocation or was already being cancelled and
- * `false` if there is no job in the context or if it was already completed. See [Job.cancel] for details.
+ * @suppress
  */
-public fun CoroutineContext.cancel(): Boolean =
-    this[Job]?.cancel() ?: false
+@JvmName("cancel")
+@Deprecated(message = "Binary compatibility", level = DeprecationLevel.HIDDEN)
+public fun CoroutineContext.cancel0(): Boolean {
+    this[Job]?.cancel()
+    return true
+}
 
 /**
- * Cancels [Job] of this context with an optional cancellation [cause]. The result is `true` if the job was
- * cancelled as a result of this invocation and `false` if there is no job in the context or if it was already
- * cancelled or completed. See [Job.cancel] for details.
- *
- * **Note: This is an experimental api.** Cancellation of a job with exception may change its semantics in the future.
+ * Cancels [Job] of this context. See [Job.cancel] for details.
  */
-@ExperimentalCoroutinesApi
+public fun CoroutineContext.cancel(): Unit {
+    this[Job]?.cancel()
+}
+
+/**
+ * @suppress
+ */
+@ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "Use cancel() without cause", replaceWith = ReplaceWith("cancel()"))
 public fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
     this[Job]?.cancel(cause) ?: false
 
@@ -526,14 +539,8 @@ public fun CoroutineContext.cancelChildren() {
     this[Job]?.children?.forEach { it.cancel() }
 }
 
-/**
- * Cancels all children of the [Job] in this context with an optional cancellation [cause],
- * without touching the the state of this job itself.
- * It does not do anything if there is no job in the context or it has no children.
- *
- * **Note: This is an experimental api.** Cancellation of a job with exception may change its semantics in the future.
- */
-@ExperimentalCoroutinesApi
+@ObsoleteCoroutinesApi
+@Deprecated(level = DeprecationLevel.WARNING, message = "Use cancelChildren() without cause", replaceWith = ReplaceWith("cancelChildren()"))
 public fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
     this[Job]?.children?.forEach { it.cancel(cause) }
 }

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

@@ -559,8 +559,9 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
     internal open val onCancelComplete: Boolean get() = false
 
     // external cancel without cause, never invoked implicitly from internal machinery
-    public override fun cancel(): Boolean =
+    public override fun cancel(): Unit {
         cancel(null) // must delegate here, because some classes override cancel(x)
+    }
 
     // external cancel with (optional) cause, never invoked implicitly from internal machinery
     public override fun cancel(cause: Throwable?): Boolean =

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

@@ -88,11 +88,13 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
         NonDisposableHandle
 
     /**
-     * Always returns `false`.
+     * Does nothing.
      * @suppress **This an internal API and should not be used from general code.**
      */
     @InternalCoroutinesApi
-    override fun cancel(): Boolean = false
+    @Suppress("RETURN_TYPE_MISMATCH_ON_OVERRIDE")
+    override fun cancel(): Unit {
+    }
 
     /**
      * Always returns `false`.

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

@@ -657,7 +657,9 @@ internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E
         return if (result === POLL_FAILED) null else receiveOrNullResult(result)
     }
 
-    override fun cancel(): Boolean = cancel(null)
+    override fun cancel(): Unit {
+        cancel(null)
+    }
 
     override fun cancel(cause: Throwable?): Boolean =
         close(cause).also {

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

@@ -7,10 +7,11 @@
 package kotlinx.coroutines.channels
 
 import kotlinx.coroutines.*
-import kotlinx.coroutines.channels.Channel.Factory.RENDEZVOUS
 import kotlinx.coroutines.channels.Channel.Factory.CONFLATED
+import kotlinx.coroutines.channels.Channel.Factory.RENDEZVOUS
 import kotlinx.coroutines.channels.Channel.Factory.UNLIMITED
 import kotlinx.coroutines.selects.*
+import kotlin.jvm.*
 
 /**
  * Sender's interface to [Channel].
@@ -243,33 +244,28 @@ public interface ReceiveChannel<out E> {
     /**
      * Cancels reception of remaining elements from this channel. This function closes the channel
      * and removes all buffered sent elements from it.
-     * This function returns `true` if the channel was not closed previously, or `false` otherwise.
      *
      * Immediately after invocation of this function [isClosedForReceive] and
      * [isClosedForSend][SendChannel.isClosedForSend]
      * on the side of [SendChannel] start returning `true`, so all attempts to send to this channel
      * afterwards will throw [ClosedSendChannelException], while attempts to receive will throw
      * [ClosedReceiveChannelException].
      */
-    public fun cancel(): Boolean
+    public fun cancel(): Unit
 
     /**
-     * Cancels reception of remaining elements from this channel. This function closes the channel with
-     * the specified cause (unless it was already closed) and removes all buffered sent elements from it.
-     * This function returns `true` if the channel was not closed previously, or `false` otherwise.
-     *
-     * Immediately after invocation of this function [isClosedForReceive] and
-     * [isClosedForSend][SendChannel.isClosedForSend]
-     * on the side of [SendChannel] start returning `true`, so all attempts to send to this channel
-     * afterwards will throw [ClosedSendChannelException], while attempts to receive will throw
-     * [ClosedReceiveChannelException] if it was cancelled without a cause.
-     * A channel that was cancelled with non-null [cause] is called a _failed_ channel. Attempts to send or
-     * receive on a failed channel throw the specified [cause] exception.
-     *
-     * **Note: This is an experimental api.** Semantics of _cancelling_ a channel with exception may
-     *         change in the future or this feature may be completely removed.
+     * @suppress
      */
-    @ExperimentalCoroutinesApi
+    @Suppress("INAPPLICABLE_JVM_NAME")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Left here for binary compatibility")
+    @JvmName("cancel")
+    public fun cancel0(): Boolean = cancel(null)
+
+    /**
+     * @suppress
+     */
+    @ObsoleteCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = "Use cancel without cause", replaceWith = ReplaceWith("cancel()"))
     public fun cancel(cause: Throwable? = null): Boolean
 }
 

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

@@ -16,7 +16,11 @@ internal open class ChannelCoroutine<E>(
 
     val channel: Channel<E> get() = this
 
-    override fun cancel() = cancel(null)
+    override fun cancel(): Unit {
+        cancel(null)
+    }
+
+    override fun cancel0(): Boolean = cancel(null)
 
     override fun cancel(cause: Throwable?): Boolean {
         val wasCancelled = _channel.cancel(cause)

common/kotlinx-coroutines-core-common/test/AsyncLazyTest.kt

@@ -150,9 +150,8 @@ class AsyncLazyTest : TestBase() {
         }
         expect(2)
         assertTrue(!d.isActive && !d.isCompleted)
-        assertTrue(d.cancel())
+        d.cancel()
         assertTrue(!d.isActive && d.isCompleted && d.isCancelled)
-        assertTrue(!d.cancel())
         assertTrue(!d.start())
         finish(3)
         assertEquals(d.await(), 42) // await shall throw CancellationException
@@ -178,9 +177,8 @@ class AsyncLazyTest : TestBase() {
         yield() // yield to d
         expect(5)
         assertTrue(d.isActive && !d.isCompleted && !d.isCancelled)
-        assertTrue(d.cancel())
+        d.cancel()
         assertTrue(!d.isActive && d.isCancelled) // cancelling !
-        assertTrue(d.cancel())
         assertTrue(!d.isActive && d.isCancelled) // still cancelling
         finish(6)
         assertEquals(d.await(), 42) // await shall throw CancellationException