Merge pull request #588 from Kotlin/handle-exception-fix

Handle exceptions fix

Author: qwwdfsad

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

@@ -1,4 +1,5 @@
 public abstract class kotlinx/coroutines/experimental/AbstractCoroutine : kotlin/coroutines/experimental/Continuation, kotlinx/coroutines/experimental/CoroutineScope, kotlinx/coroutines/experimental/Job {
+	protected final field parentContext Lkotlin/coroutines/experimental/CoroutineContext;
 	public fun <init> (Lkotlin/coroutines/experimental/CoroutineContext;Z)V
 	public synthetic fun <init> (Lkotlin/coroutines/experimental/CoroutineContext;ZILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun getContext ()Lkotlin/coroutines/experimental/CoroutineContext;
@@ -392,7 +393,7 @@ public abstract interface annotation class kotlinx/coroutines/experimental/Inter
 
 public abstract interface class kotlinx/coroutines/experimental/Job : kotlin/coroutines/experimental/CoroutineContext$Element {
 	public static final field Key Lkotlinx/coroutines/experimental/Job$Key;
-	public abstract fun attachChild (Lkotlinx/coroutines/experimental/Job;)Lkotlinx/coroutines/experimental/DisposableHandle;
+	public abstract fun attachChild (Lkotlinx/coroutines/experimental/ChildJob;)Lkotlinx/coroutines/experimental/ChildHandle;
 	public abstract fun cancel ()Z
 	public abstract fun cancel (Ljava/lang/Throwable;)Z
 	public abstract synthetic fun cancelChildren (Ljava/lang/Throwable;)V
@@ -467,7 +468,7 @@ public final class kotlinx/coroutines/experimental/LazyDeferredKt {
 
 public final class kotlinx/coroutines/experimental/NonCancellable : kotlin/coroutines/experimental/AbstractCoroutineContextElement, kotlinx/coroutines/experimental/Job {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/NonCancellable;
-	public fun attachChild (Lkotlinx/coroutines/experimental/Job;)Lkotlinx/coroutines/experimental/DisposableHandle;
+	public fun attachChild (Lkotlinx/coroutines/experimental/ChildJob;)Lkotlinx/coroutines/experimental/ChildHandle;
 	public fun cancel ()Z
 	public fun cancel (Ljava/lang/Throwable;)Z
 	public synthetic fun cancelChildren (Ljava/lang/Throwable;)V
@@ -487,8 +488,9 @@ public final class kotlinx/coroutines/experimental/NonCancellable : kotlin/corou
 	public fun start ()Z
 }
 
-public final class kotlinx/coroutines/experimental/NonDisposableHandle : kotlinx/coroutines/experimental/DisposableHandle {
+public final class kotlinx/coroutines/experimental/NonDisposableHandle : kotlinx/coroutines/experimental/ChildHandle, kotlinx/coroutines/experimental/DisposableHandle {
 	public static final field INSTANCE Lkotlinx/coroutines/experimental/NonDisposableHandle;
+	public fun childCancelled (Ljava/lang/Throwable;)Z
 	public fun dispose ()V
 	public fun toString ()Ljava/lang/String;
 }

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

@@ -5,6 +5,7 @@
 package kotlinx.coroutines.experimental
 
 import kotlinx.coroutines.experimental.CoroutineStart.*
+import kotlinx.coroutines.experimental.internal.*
 import kotlinx.coroutines.experimental.intrinsics.*
 import kotlin.coroutines.experimental.*
 
@@ -14,12 +15,12 @@ import kotlin.coroutines.experimental.*
  * This class implements completion [Continuation], [Job], and [CoroutineScope] interfaces.
  * It stores the result of continuation in the state of the job.
  * This coroutine waits for children coroutines to finish before completing and
- * is cancelled through an intermediate _cancelling_ state.
+ * fails through an intermediate _failing_ state.
  *
  * The following methods are available for override:
  *
  * * [onStart] is invoked when coroutine is create in not active state and is [started][Job.start].
- * * [onCancellation] is invoked as soon as coroutine is [cancelled][cancel] (becomes _cancelling_)
+ * * [onCancellation] is invoked as soon as coroutine is _failing_, or is cancelled,
  *   or when it completes for any reason.
  * * [onCompleted] is invoked when coroutine completes with a value.
  * * [onCompletedExceptionally] in invoked when coroutines completes with exception.
@@ -33,12 +34,22 @@ import kotlin.coroutines.experimental.*
 @Suppress("EXPOSED_SUPER_CLASS")
 @InternalCoroutinesApi
 public abstract class AbstractCoroutine<in T>(
-    private val parentContext: CoroutineContext,
+    /**
+     * Context of the parent coroutine.
+     */
+    @JvmField
+    protected val parentContext: CoroutineContext,
     active: Boolean = true
 ) : JobSupport(active), Job, Continuation<T>, CoroutineScope {
+    /**
+     * Context of this coroutine that includes this coroutine as a [Job].
+     */
     @Suppress("LeakingThis")
     public final override val context: CoroutineContext = parentContext + this
-    @Deprecated("Replaced with context", replaceWith = ReplaceWith("context"))
+
+    /**
+     * Context of this scope which is the same as the [context] of this coroutine.
+     */
     public override val coroutineContext: CoroutineContext get() = context
 
     override val isActive: Boolean get() = super<JobSupport>.isActive
@@ -66,20 +77,16 @@ public abstract class AbstractCoroutine<in T>(
     }
 
     /**
-     * This function is invoked once when this coroutine is cancelled or is completed,
+     * This function is invoked once when this coroutine is cancelled
      * similarly to [invokeOnCompletion] with `onCancelling` set to `true`.
      *
      * The meaning of [cause] parameter:
      * * Cause is `null` when job has completed normally.
      * * Cause is an instance of [CancellationException] when job was cancelled _normally_.
      *   **It should not be treated as an error**. In particular, it should not be reported to error logs.
-     * * Otherwise, the job had _failed_.
+     * * Otherwise, the job had been cancelled or failed with exception.
      */
-    protected open fun onCancellation(cause: Throwable?) {}
-
-    internal override fun onCancellationInternal(exceptionally: CompletedExceptionally?) {
-        onCancellation(exceptionally?.cause)
-    }
+    protected override fun onCancellation(cause: Throwable?) {}
 
     /**
      * This function is invoked once when job is completed normally with the specified [value].
@@ -89,10 +96,11 @@ public abstract class AbstractCoroutine<in T>(
     /**
      * This function is invoked once when job is completed exceptionally with the specified [exception].
      */
+    // todo: rename to onCancelled
     protected open fun onCompletedExceptionally(exception: Throwable) {}
 
     @Suppress("UNCHECKED_CAST")
-    internal override fun onCompletionInternal(state: Any?, mode: Int) {
+    internal override fun onCompletionInternal(state: Any?, mode: Int, suppressed: Boolean) {
         if (state is CompletedExceptionally)
             onCompletedExceptionally(state.cause)
         else

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

@@ -281,20 +281,11 @@ public suspend fun <T> run(context: CoroutineContext, block: suspend () -> T): T
 // --------------- implementation ---------------
 
 private open class StandaloneCoroutine(
-    private val parentContext: CoroutineContext,
+    parentContext: CoroutineContext,
     active: Boolean
 ) : AbstractCoroutine<Unit>(parentContext, active) {
-    override fun hasOnFinishingHandler(update: Any?) = update is CompletedExceptionally
-
-    override fun handleJobException(exception: Throwable) {
-        handleCoroutineException(parentContext, exception, this)
-    }
-
-    override fun onFinishingInternal(update: Any?) {
-        if (update is CompletedExceptionally && update.cause !is CancellationException) {
-            parentContext[Job]?.cancel(update.cause)
-        }
-    }
+    override val cancelsParent: Boolean get() = true
+    override fun handleJobException(exception: Throwable) = handleExceptionViaHandler(parentContext, exception)
 }
 
 private class LazyStandaloneCoroutine(

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

@@ -7,10 +7,11 @@ package kotlinx.coroutines.experimental
 import kotlinx.coroutines.experimental.selects.*
 
 /**
- * A [Deferred] that can be completed via public functions
- * [complete], [completeExceptionally], and [cancel].
+ * A [Deferred] that can be completed via public functions [complete] or [cancel][Job.cancel].
  *
- * Completion functions return `false` when this deferred value is already complete or completing.
+ * Note, that [complete] functions returns `false` when this deferred value is already complete or completing,
+ * while [cancel][Job.cancel] returns `true` as long the deferred is still _cancelling_ and the corresponding
+ * exception is incorporated into the final [completion exception][getCompletionExceptionOrNull].
  *
  * An instance of completable deferred can be created by `CompletableDeferred()` function in _active_ state.
  *
@@ -32,6 +33,7 @@ public interface CompletableDeferred<T> : Deferred<T> {
      *
      * Repeated invocations of this function have no effect and always produce `false`.
      */
+    @Deprecated(message = "Use cancel", replaceWith = ReplaceWith("cancel(exception)"))
     public fun completeExceptionally(exception: Throwable): Boolean
 }
 
@@ -61,7 +63,7 @@ private class CompletableDeferredImpl<T>(
     parent: Job?
 ) : JobSupport(true), CompletableDeferred<T>, SelectClause1<T> {
     init { initParentJobInternal(parent) }
-    override val onCancelMode: Int get() = ON_CANCEL_MAKE_COMPLETING
+    override val onCancelComplete get() = true
     override fun getCompleted(): T = getCompletedInternal() as T
     override suspend fun await(): T = awaitInternal() as T
     override val onAwait: SelectClause1<T> get() = this

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

@@ -8,35 +8,22 @@ import kotlinx.coroutines.experimental.internal.*
 import kotlin.coroutines.experimental.*
 
 /**
- * Class for an internal state of a job that had completed exceptionally, including cancellation.
+ * Class for an internal state of a job that was cancelled (completed exceptionally).
  *
  * **Note: This class cannot be used outside of internal coroutines framework**.
- * **Note: cannot be internal until we get rid of MutableDelegateContinuation in IO**
+ * **Note: cannot be internal and renamed until we get rid of MutableDelegateContinuation in IO**
  *
  * @param cause the exceptional completion cause. It's either original exceptional cause
  *        or artificial [CancellationException] if no cause was provided
  * @suppress **This is unstable API and it is subject to change.**
  */
+// todo: rename to Cancelled
 open class CompletedExceptionally(
     @JvmField public val cause: Throwable
 ) {
     override fun toString(): String = "$classSimpleName[$cause]"
 }
 
-/**
- * A specific subclass of [CompletedExceptionally] for cancelled jobs.
- *
- * **Note: This class cannot be used outside of internal coroutines framework**.
- *
- * @param job the job that was cancelled.
- * @param cause the exceptional completion cause. If `cause` is null, then a [CancellationException] is created.
- * @suppress **This is unstable API and it is subject to change.**
- */
-internal class Cancelled(
-    job: Job,
-    cause: Throwable?
-) : CompletedExceptionally(cause ?: JobCancellationException("Job was cancelled normally", null, job))
-
 /**
  * A specific subclass of [CompletedExceptionally] for cancelled [AbstractContinuation].
  *

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

@@ -43,3 +43,5 @@ internal expect val CancelHandlerBase.asHandler: CompletionHandler
 // :KLUDGE: We have to invoke a handler in platform-specific way via `invokeIt` extension,
 // because we play type tricks on Kotlin/JS and handler is not necessarily a function there
 internal expect fun CompletionHandler.invokeIt(cause: Throwable?)
+
+internal inline fun <reified T> CompletionHandler.isHandlerOf(): Boolean = this is T

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

@@ -18,38 +18,41 @@ internal expect fun handleCoroutineExceptionImpl(context: CoroutineContext, exce
  *
  * If there is a [Job] in the context and it's not a [caller], then [Job.cancel] is invoked.
  * If invocation returned `true`, method terminates: now [Job] is responsible for handling an exception.
- * Otherwise, If there is [CoroutineExceptionHandler] in the context, it is used.
- * Otherwise all instances of [CoroutineExceptionHandler] found via [ServiceLoader] and [Thread.uncaughtExceptionHandler] are invoked
+ * Otherwise, If there is [CoroutineExceptionHandler] in the context, it is used. If it throws an exception during handling
+ * or is absent, all instances of [CoroutineExceptionHandler] found via [ServiceLoader] and [Thread.uncaughtExceptionHandler] are invoked
  */
 @JvmOverloads // binary compatibility
 @InternalCoroutinesApi
 public fun handleCoroutineException(context: CoroutineContext, exception: Throwable, caller: Job? = null) {
-    // if exception handling fails, make sure the original exception is not lost
+    // Ignore CancellationException (they are normal ways to terminate a coroutine)
+    if (exception is CancellationException) return // nothing to do
+    // Try propagate exception to parent
+    val job = context[Job]
+    if (job !== null && job !== caller && job.cancel(exception)) return // handle by parent
+    // otherwise -- use exception handlers
+    handleExceptionViaHandler(context, exception)
+}
+
+internal fun handleExceptionViaHandler(context: CoroutineContext, exception: Throwable) {
+    // Invoke exception handler from the context if present
     try {
-        // Ignore CancellationException (they are normal ways to terminate a coroutine)
-        if (exception is CancellationException) {
-            return
-        }
-        // If parent is successfully cancelled, we're done, it is now its responsibility to handle the exception
-        val parent = context[Job]
-        // E.g. actor registers itself in the context, in that case we should invoke handler
-        if (parent !== null && parent !== caller && parent.cancel(exception)) {
-            return
-        }
-        // If not, invoke exception handler from the context
         context[CoroutineExceptionHandler]?.let {
             it.handleException(context, exception)
             return
         }
-        // If handler is not present in the context, fallback to the global handler
-        handleCoroutineExceptionImpl(context, exception)
-    } catch (handlerException: Throwable) {
-        // simply rethrow if handler threw the original exception
-        if (handlerException === exception) throw exception
-        // handler itself crashed for some other reason -- that is bad -- keep both
-        throw RuntimeException("Exception while trying to handle coroutine exception", exception).apply {
-            addSuppressedThrowable(handlerException)
-        }
+    } catch (t: Throwable) {
+        handleCoroutineExceptionImpl(context, handlerException(exception, t))
+        return
+    }
+
+    // If handler is not present in the context or exception was thrown, fallback to the global handler
+    handleCoroutineExceptionImpl(context, exception)
+}
+
+internal fun handlerException(originalException: Throwable, thrownException: Throwable): Throwable {
+    if (originalException === thrownException) return originalException
+    return RuntimeException("Exception while trying to handle coroutine exception", thrownException).apply {
+        addSuppressedThrowable(originalException)
     }
 }
 

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

@@ -71,7 +71,7 @@ public interface CoroutineScope {
         get() = coroutineContext[Job]?.isActive ?: true
 
     /**
-     * Returns the context of this scope.
+     * Context of this scope.
      */
     public val coroutineContext: CoroutineContext
 }
@@ -175,7 +175,7 @@ object GlobalScope : CoroutineScope {
  */
 public suspend fun <R> coroutineScope(block: suspend CoroutineScope.() -> R): R {
     // todo: optimize implementation to a single allocated object
-    val owner = ScopeOwnerCoroutine<R>(coroutineContext)
+    val owner = ScopeCoroutine<R>(coroutineContext)
     owner.start(CoroutineStart.UNDISPATCHED, owner, block)
     owner.join()
     if (owner.isCancelled) {