Eagerly create cancellation exception during Job.cancel call to make stacktrace even shorter

Also, fix stacktrace recovery in select clause

Author: qwwdfsad

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

@@ -3,6 +3,7 @@ public abstract class kotlinx/coroutines/AbstractCoroutine : kotlinx/coroutines/
 	public fun <init> (Lkotlin/coroutines/CoroutineContext;Z)V
 	public synthetic fun <init> (Lkotlin/coroutines/CoroutineContext;ZILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	protected fun afterResume (Ljava/lang/Object;)V
+	protected fun cancellationExceptionMessage ()Ljava/lang/String;
 	public final fun getContext ()Lkotlin/coroutines/CoroutineContext;
 	public fun getCoroutineContext ()Lkotlin/coroutines/CoroutineContext;
 	public fun isActive ()Z
@@ -264,6 +265,10 @@ public final class kotlinx/coroutines/DelayKt {
 	public static final fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
+public final class kotlinx/coroutines/DispatchedContinuationKt {
+	public static final fun resumeCancellableWith (Lkotlin/coroutines/Continuation;Ljava/lang/Object;)V
+}
+
 public final class kotlinx/coroutines/Dispatchers {
 	public static final field INSTANCE Lkotlinx/coroutines/Dispatchers;
 	public static final fun getDefault ()Lkotlinx/coroutines/CoroutineDispatcher;
@@ -387,7 +392,8 @@ public class kotlinx/coroutines/JobSupport : kotlinx/coroutines/ChildJob, kotlin
 	public synthetic fun cancel (Ljava/lang/Throwable;)Z
 	public fun cancel (Ljava/util/concurrent/CancellationException;)V
 	public final fun cancelCoroutine (Ljava/lang/Throwable;)Z
-	public fun cancelInternal (Ljava/lang/Throwable;)Z
+	public fun cancelInternal (Ljava/lang/Throwable;)V
+	protected fun cancellationExceptionMessage ()Ljava/lang/String;
 	public fun childCancelled (Ljava/lang/Throwable;)Z
 	public fun fold (Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
 	public fun get (Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
@@ -1049,7 +1055,7 @@ public final class kotlinx/coroutines/selects/SelectBuilderImpl : kotlinx/corout
 	public fun isSelected ()Z
 	public fun onTimeout (JLkotlin/jvm/functions/Function1;)V
 	public fun performAtomicTrySelect (Lkotlinx/coroutines/internal/AtomicDesc;)Ljava/lang/Object;
-	public fun resumeSelectCancellableWithException (Ljava/lang/Throwable;)V
+	public fun resumeSelectWithException (Ljava/lang/Throwable;)V
 	public fun resumeWith (Ljava/lang/Object;)V
 	public fun toString ()Ljava/lang/String;
 	public fun trySelect ()Z
@@ -1073,7 +1079,7 @@ public abstract interface class kotlinx/coroutines/selects/SelectInstance {
 	public abstract fun getCompletion ()Lkotlin/coroutines/Continuation;
 	public abstract fun isSelected ()Z
 	public abstract fun performAtomicTrySelect (Lkotlinx/coroutines/internal/AtomicDesc;)Ljava/lang/Object;
-	public abstract fun resumeSelectCancellableWithException (Ljava/lang/Throwable;)V
+	public abstract fun resumeSelectWithException (Ljava/lang/Throwable;)V
 	public abstract fun trySelect ()Z
 	public abstract fun trySelectOther (Lkotlinx/coroutines/internal/LockFreeLinkedListNode$PrepareOp;)Ljava/lang/Object;
 }

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

@@ -94,6 +94,8 @@ public abstract class AbstractCoroutine<in T>(
      */
     protected open fun onCancelled(cause: Throwable, handled: Boolean) {}
 
+    override fun cancellationExceptionMessage(): String = "$classSimpleName was cancelled"
+
     @Suppress("UNCHECKED_CAST")
     protected final override fun onCompletionInternal(state: Any?) {
         if (state is CompletedExceptionally)

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

@@ -257,9 +257,6 @@ internal open class CancellableContinuationImpl<in T>(
         }
     }
 
-    internal fun resumeWithExceptionMode(exception: Throwable, mode: Int) =
-        resumeImpl(CompletedExceptionally(exception), mode)
-
     public override fun invokeOnCancellation(handler: CompletionHandler) {
         var handleCache: CancelHandler? = null
         _state.loop { state ->

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

@@ -503,7 +503,7 @@ public fun Job.cancelChildren() = cancelChildren(null)
  */
 @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun Job.cancelChildren(cause: Throwable? = null) {
-    children.forEach { (it as? JobSupport)?.cancelInternal(cause) }
+    children.forEach { (it as? JobSupport)?.cancelInternal(cause.orCancellation(this)) }
 }
 
 // -------------------- CoroutineContext extensions --------------------
@@ -586,9 +586,11 @@ public fun Job.cancel(message: String, cause: Throwable? = null): Unit = cancel(
  * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [CoroutineContext.cancel].
  */
 @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
-public fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
-    @Suppress("DEPRECATION")
-    (this[Job] as? JobSupport)?.cancelInternal(cause) ?: false
+public fun CoroutineContext.cancel(cause: Throwable? = null): Boolean {
+    val job = this[Job] as? JobSupport ?: return false
+    job.cancelInternal(cause.orCancellation(job))
+    return true
+}
 
 /**
  * Cancels all children of the [Job] in this context, without touching the state of this job itself
@@ -610,9 +612,12 @@ public fun CoroutineContext.cancelChildren() = cancelChildren(null)
  */
 @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
-    this[Job]?.children?.forEach { (it as? JobSupport)?.cancelInternal(cause) }
+    val job = this[Job] ?: return
+    job.children.forEach { (it as? JobSupport)?.cancelInternal(cause.orCancellation(job)) }
 }
 
+private fun Throwable?.orCancellation(job: Job): Throwable = this ?: JobCancellationException("Job was cancelled", null, job)
+
 /**
  * No-op implementation of [DisposableHandle].
  * @suppress **This an internal API and should not be used from general code.**

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

@@ -244,7 +244,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
         // A case of no exceptions
         if (exceptions.isEmpty()) {
             // materialize cancellation exception if it was not materialized yet
-            if (state.isCancelling) return createJobCancellationException()
+            if (state.isCancelling) return defaultCancellationException()
             return null
         }
         // Take either the first real exception (not a cancellation) or just the first exception
@@ -406,8 +406,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
         }
 
     protected fun Throwable.toCancellationException(message: String? = null): CancellationException =
-        this as? CancellationException ?:
-            JobCancellationException(message ?: "$classSimpleName was cancelled", this, this@JobSupport)
+        this as? CancellationException ?: defaultCancellationException(message, this)
 
     /**
      * Returns the cause that signals the completion of this job -- it returns the original
@@ -597,19 +596,23 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
 
     // external cancel with cause, never invoked implicitly from internal machinery
     public override fun cancel(cause: CancellationException?) {
-        cancelInternal(cause) // must delegate here, because some classes override cancelInternal(x)
+        cancelInternal(cause ?: defaultCancellationException())
     }
 
+    protected open fun cancellationExceptionMessage(): String = "Job was cancelled"
+
     // HIDDEN in Job interface. Invoked only by legacy compiled code.
     // external cancel with (optional) cause, never invoked implicitly from internal machinery
     @Deprecated(level = DeprecationLevel.HIDDEN, message = "Added since 1.2.0 for binary compatibility with versions <= 1.1.x")
-    public override fun cancel(cause: Throwable?): Boolean =
-        cancelInternal(cause)
+    public override fun cancel(cause: Throwable?): Boolean {
+        cancelInternal(cause?.toCancellationException() ?: defaultCancellationException())
+        return true
+    }
 
     // It is overridden in channel-linked implementation
-    // Note: Boolean result is used only in HIDDEN DEPRECATED functions that were public in versions <= 1.1.x
-    public open fun cancelInternal(cause: Throwable?): Boolean =
-        cancelImpl(cause) && handlesException
+    public open fun cancelInternal(cause: Throwable) {
+        cancelImpl(cause)
+    }
 
     // Parent is cancelling child
     public final override fun parentCancelled(parentJob: ParentJob) {
@@ -677,8 +680,9 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
         }
     }
 
-    private fun createJobCancellationException() =
-        JobCancellationException("Job was cancelled", null, this)
+    @Suppress("NOTHING_TO_INLINE") // Save a stack frame
+    internal inline fun defaultCancellationException(message: String? = null, cause: Throwable? = null) =
+        JobCancellationException(message ?: cancellationExceptionMessage(), cause, this)
 
     override fun getChildJobCancellationCause(): CancellationException {
         // determine root cancellation cause of this job (why is it cancelling its children?)
@@ -694,7 +698,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
 
     // cause is Throwable or ParentJob when cancelChild was invoked
     private fun createCauseException(cause: Any?): Throwable = when (cause) {
-        is Throwable? -> cause ?: createJobCancellationException()
+        is Throwable? -> cause ?: defaultCancellationException()
         else -> (cause as ParentJob).getChildJobCancellationCause()
     }
 
@@ -1225,7 +1229,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
                 // already complete -- select result
                 if (select.trySelect()) {
                     if (state is CompletedExceptionally) {
-                        select.resumeSelectCancellableWithException(state.cause)
+                        select.resumeSelectWithException(state.cause)
                     }
                     else {
                         block.startCoroutineUnintercepted(state.unboxState() as T, select.completion)
@@ -1249,7 +1253,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
         val state = this.state
         // Note: await is non-atomic (can be cancelled while dispatched)
         if (state is CompletedExceptionally)
-            select.resumeSelectCancellableWithException(state.cause)
+            select.resumeSelectWithException(state.cause)
         else
             block.startCoroutineCancellable(state.unboxState() as T, select.completion)
     }
@@ -1384,8 +1388,8 @@ private class ResumeAwaitOnCompletion<T>(
         val state = job.state
         assert { state !is Incomplete }
         if (state is CompletedExceptionally) {
-            // Resume with exception in atomic way to preserve exception
-            continuation.resumeWithExceptionMode(state.cause, MODE_ATOMIC_DEFAULT)
+            // Resume with with the corresponding exception to preserve it
+            continuation.resumeWithException(state.cause)
         } else {
             // Resuming with value in a cancellable way (AwaitContinuation is configured for this mode).
             @Suppress("UNCHECKED_CAST")

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

@@ -463,7 +463,7 @@ internal abstract class AbstractSendChannel<E> : SendChannel<E> {
 
         override fun resumeSendClosed(closed: Closed<*>) {
             if (select.trySelect())
-                select.resumeSelectCancellableWithException(closed.sendException)
+                select.resumeSelectWithException(closed.sendException)
         }
 
         override fun toString(): String = "SendSelect@$hexAddress($pollResult)[$channel, $select]"
@@ -550,18 +550,14 @@ internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E
         /*
          * If result is Closed -- go to tail-call slow-path that will allow us to
          * properly recover stacktrace without paying a performance cost on fast path.
+         * We prefer to recover stacktrace using suspending path to have a more precise stacktrace.
          */
-        if (result !== POLL_FAILED && result !is Closed<*>) return receiveResult(result)
+        @Suppress("UNCHECKED_CAST")
+        if (result !== POLL_FAILED && result !is Closed<*>) return result as E
         // slow-path does suspend
         return receiveSuspend(RECEIVE_THROWS_ON_CLOSE)
     }
 
-    @Suppress("UNCHECKED_CAST")
-    private fun receiveResult(result: Any?): E {
-        if (result is Closed<*>) throw recoverStackTrace(result.receiveException)
-        return result as E
-    }
-
     @Suppress("UNCHECKED_CAST")
     private suspend fun <R> receiveSuspend(receiveMode: Int): R = suspendAtomicCancellableCoroutineReusable sc@ { cont ->
         val receive = ReceiveElement<E>(cont as CancellableContinuation<Any?>, receiveMode)
@@ -975,12 +971,12 @@ internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E
         override fun resumeReceiveClosed(closed: Closed<*>) {
             if (!select.trySelect()) return
             when (receiveMode) {
-                RECEIVE_THROWS_ON_CLOSE -> select.resumeSelectCancellableWithException(closed.receiveException)
+                RECEIVE_THROWS_ON_CLOSE -> select.resumeSelectWithException(closed.receiveException)
                 RECEIVE_RESULT -> block.startCoroutine(ValueOrClosed.closed<R>(closed.closeCause), select.completion)
                 RECEIVE_NULL_ON_CLOSE -> if (closed.closeCause == null) {
                     block.startCoroutine(null, select.completion)
                 } else {
-                    select.resumeSelectCancellableWithException(closed.receiveException)
+                    select.resumeSelectWithException(closed.receiveException)
                 }
             }
         }

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

@@ -97,17 +97,18 @@ private open class BroadcastCoroutine<E>(
         get() = this
 
     @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
-    final override fun cancel(cause: Throwable?): Boolean =
-        cancelInternal(cause)
+    final override fun cancel(cause: Throwable?): Boolean {
+        cancelInternal(cause ?: defaultCancellationException())
+        return true
+    }
 
     final override fun cancel(cause: CancellationException?) {
-        cancelInternal(cause)
+        cancelInternal(cause ?: defaultCancellationException())
     }
 
-    override fun cancelInternal(cause: Throwable?): Boolean {
-        _channel.cancel(cause?.toCancellationException()) // cancel the channel
+    override fun cancelInternal(cause: Throwable) {
+        _channel.cancel(cause.toCancellationException()) // cancel the channel
         cancelCoroutine(cause) // cancel the job
-        return true // does not matter - result is used in DEPRECATED functions only
     }
 
     override fun onCompleted(value: Unit) {

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

@@ -16,23 +16,23 @@ internal open class ChannelCoroutine<E>(
     val channel: Channel<E> get() = this
 
     override fun cancel() {
-        cancelInternal(null)
+        cancelInternal(defaultCancellationException())
     }
 
     @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
-    final override fun cancel(cause: Throwable?): Boolean =
-        cancelInternal(cause)
+    final override fun cancel(cause: Throwable?): Boolean {
+        cancelInternal(defaultCancellationException())
+        return true
+    }
 
     final override fun cancel(cause: CancellationException?) {
-        cancelInternal(cause)
+        cancelInternal(cause ?: defaultCancellationException())
     }
 
-    override fun cancelInternal(cause: Throwable?): Boolean {
-        val exception = cause?.toCancellationException()
-            ?: JobCancellationException("$classSimpleName was cancelled", null, this)
+    override fun cancelInternal(cause: Throwable) {
+        val exception = cause.toCancellationException()
         _channel.cancel(exception) // cancel the channel
         cancelCoroutine(exception) // cancel the job
-        return true // does not matter - result is used in DEPRECATED functions only
     }
 
     @Suppress("UNCHECKED_CAST")

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

@@ -275,7 +275,7 @@ public class ConflatedBroadcastChannel<E>() : BroadcastChannel<E> {
     private fun <R> registerSelectSend(select: SelectInstance<R>, element: E, block: suspend (SendChannel<E>) -> R) {
         if (!select.trySelect()) return
         offerInternal(element)?.let {
-            select.resumeSelectCancellableWithException(it.sendException)
+            select.resumeSelectWithException(it.sendException)
             return
         }
         block.startCoroutineUnintercepted(receiver = this, completion = select.completion)

kotlinx-coroutines-core/common/src/internal/DispatchedContinuation.kt

@@ -174,7 +174,9 @@ internal class DispatchedContinuation<in T>(
         }
     }
 
-    @Suppress("NOTHING_TO_INLINE") // we need it inline to save us an entry on the stack
+    // We inline it to save an entry on the stack in cases where it shows (unconfined dispatcher)
+    // It is used only in Continuation<T>.resumeCancellableWith
+    @Suppress("NOTHING_TO_INLINE")
     inline fun resumeCancellableWith(result: Result<T>) {
         val state = result.toState()
         if (dispatcher.isDispatchNeeded(context)) {
@@ -220,8 +222,14 @@ internal class DispatchedContinuation<in T>(
         "DispatchedContinuation[$dispatcher, ${continuation.toDebugString()}]"
 }
 
-@Suppress("NOTHING_TO_INLINE") // we need it inline to save us an entry on the stack
-internal inline fun <T> Continuation<T>.resumeCancellableWith(result: Result<T>) = when (this) {
+/**
+ * It is not inline to save bytecode (it is pretty big and used in many places)
+ * and we leave it public so that its name is not mangled in use stack traces if it shows there.
+ * It may appear in stack traces when coroutines are started/resumed with unconfined dispatcher.
+ * @suppress **This an internal API and should not be used from general code.**
+ */
+@InternalCoroutinesApi
+public fun <T> Continuation<T>.resumeCancellableWith(result: Result<T>) = when (this) {
     is DispatchedContinuation -> resumeCancellableWith(result)
     else -> resumeWith(result)
 }

kotlinx-coroutines-core/common/src/selects/Select.kt

@@ -133,9 +133,10 @@ public interface SelectInstance<in R> {
     public val completion: Continuation<R>
 
     /**
-     * Resumes this instance in a cancellable way ([MODE_CANCELLABLE]).
+     * Resumes this instance in a dispatched way with exception.
+     * This method can be called from any context.
      */
-    public fun resumeSelectCancellableWithException(exception: Throwable)
+    public fun resumeSelectWithException(exception: Throwable)
 
     /**
      * Disposes the specified handle when this instance is selected.
@@ -282,10 +283,10 @@ internal class SelectBuilderImpl<in R>(
         }
     }
 
-    // Resumes in MODE_CANCELLABLE, can be called from an arbitrary context
-    override fun resumeSelectCancellableWithException(exception: Throwable) {
-        doResume({ CompletedExceptionally(exception) }) {
-            uCont.intercepted().resumeCancellableWith(Result.failure(exception))
+    // Resumes in dispatched way so that it can be called from an arbitrary context
+    override fun resumeSelectWithException(exception: Throwable) {
+        doResume({ CompletedExceptionally(recoverStackTrace(exception, uCont)) }) {
+            uCont.intercepted().resumeWith(Result.failure(exception))
         }
     }
 
@@ -317,7 +318,7 @@ internal class SelectBuilderImpl<in R>(
         // Note: may be invoked multiple times, but only the first trySelect succeeds anyway
         override fun invoke(cause: Throwable?) {
             if (trySelect())
-                resumeSelectCancellableWithException(job.getCancellationException())
+                resumeSelectWithException(job.getCancellationException())
         }
         override fun toString(): String = "SelectOnCancelling[${this@SelectBuilderImpl}]"
     }