Introduced ChildHandle for attachChild

* ChildHandle.childFailed controls notification from child to parent
  (no need to lookup parent job in the context)
* JobSupport.failsParent boolean property controls whether a job
  fails its parent on failure.

Author: elizarov

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

@@ -90,6 +90,10 @@ public final class kotlinx/coroutines/experimental/CancelledContinuation : kotli
 	public fun <init> (Lkotlin/coroutines/experimental/Continuation;Ljava/lang/Throwable;)V
 }
 
+public abstract interface class kotlinx/coroutines/experimental/ChildHandle : kotlinx/coroutines/experimental/DisposableHandle {
+	public abstract fun childFailed (Ljava/lang/Throwable;)Z
+}
+
 public abstract class kotlinx/coroutines/experimental/CloseableCoroutineDispatcher : kotlinx/coroutines/experimental/CoroutineDispatcher, java/io/Closeable {
 	public fun <init> ()V
 }
@@ -368,11 +372,10 @@ public final class kotlinx/coroutines/experimental/GlobalScope : kotlinx/corouti
 
 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/Job;)Lkotlinx/coroutines/experimental/ChildHandle;
 	public abstract fun cancel (Ljava/lang/Throwable;)Z
 	public abstract fun cancelChild (Lkotlinx/coroutines/experimental/Job;)V
 	public abstract synthetic fun cancelChildren (Ljava/lang/Throwable;)V
-	public abstract fun childFailed (Ljava/lang/Throwable;)Z
 	public abstract fun getCancellationException ()Ljava/util/concurrent/CancellationException;
 	public abstract fun getChildren ()Lkotlin/sequences/Sequence;
 	public abstract fun getCompletionException ()Ljava/lang/Throwable;
@@ -442,11 +445,10 @@ 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/Job;)Lkotlinx/coroutines/experimental/ChildHandle;
 	public fun cancel (Ljava/lang/Throwable;)Z
 	public fun cancelChild (Lkotlinx/coroutines/experimental/Job;)V
 	public synthetic fun cancelChildren (Ljava/lang/Throwable;)V
-	public fun childFailed (Ljava/lang/Throwable;)Z
 	public fun getCancellationException ()Ljava/util/concurrent/CancellationException;
 	public fun getChildren ()Lkotlin/sequences/Sequence;
 	public fun getCompletionException ()Ljava/lang/Throwable;
@@ -464,8 +466,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 childFailed (Ljava/lang/Throwable;)Z
 	public fun dispose ()V
 	public fun toString ()Ljava/lang/String;
 }

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

@@ -123,13 +123,6 @@ public abstract class AbstractCoroutine<in T>(
         makeCompletingOnce(CompletedExceptionally(exception), defaultResumeMode)
     }
 
-    // todo: make it for all kinds of coroutines, now only launch & actor override and handleExceptionViaJob
-    internal fun failParentImpl(exception: Throwable): Boolean {
-        if (exception is CancellationException) return true
-        val parentJob = parentContext[Job]
-        return parentJob !== null && parentJob.childFailed(exception)
-    }
-
     internal final override fun handleOnCompletionException(exception: Throwable) {
         handleCoroutineException(parentContext, exception, this)
     }

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

@@ -210,7 +210,7 @@ private open class StandaloneCoroutine(
     parentContext: CoroutineContext,
     active: Boolean
 ) : AbstractCoroutine<Unit>(parentContext, active) {
-    override fun failParent(exception: Throwable) = failParentImpl(exception)
+    override val failsParent: Boolean get() = true
     override fun handleJobException(exception: Throwable) = handleExceptionViaHandler(parentContext, exception)
 }
 

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

@@ -181,16 +181,6 @@ public interface Job : CoroutineContext.Element {
 
     // ------------ parent-child ------------
 
-    /**
-     * Child is reporting failure to the parent by invoking this method.
-     * This method is invoked by the child twice. The first time child report its root cause as soon as possible,
-     * so that all its siblings and the parent can start finishing their work asap on failure. The second time
-     * child invokes this method when it had aggregated and determined its final termination cause.
-     *
-     * @suppress **This is unstable API and it is subject to change.**
-     */
-    public fun childFailed(cause: Throwable): Boolean
-
     /**
      * Cancels child job. This method is invoked by [parentJob] to cancel this child job.
      * Child finds the cancellation cause using [getCancellationException] of the [parentJob].
@@ -240,7 +230,7 @@ public interface Job : CoroutineContext.Element {
      * @suppress **This is unstable API and it is subject to change.**
      *           This is an internal API. This method is too error prone for public API.
      */
-    public fun attachChild(child: Job): DisposableHandle
+    public fun attachChild(child: Job): ChildHandle
 
     /**
      * Cancels all children jobs of this coroutine with the given [cause]. Unlike [cancel],
@@ -396,6 +386,21 @@ public interface DisposableHandle {
     public fun dispose()
 }
 
+/**
+ * @suppress **This is unstable API and it is subject to change.**
+ */
+public interface ChildHandle : DisposableHandle {
+    /**
+     * Child is reporting failure to the parent by invoking this method.
+     * This method is invoked by the child twice. The first time child report its root cause as soon as possible,
+     * so that all its siblings and the parent can start finishing their work asap on failure. The second time
+     * child invokes this method when it had aggregated and determined its final termination cause.
+     *
+     * @suppress **This is unstable API and it is subject to change.**
+     */
+    public fun childFailed(cause: Throwable): Boolean
+}
+
 // -------------------- Job extensions --------------------
 
 /**
@@ -508,10 +513,22 @@ public suspend fun Job.join() = this.join()
 /**
  * No-op implementation of [DisposableHandle].
  */
-public object NonDisposableHandle : DisposableHandle {
-    /** Does not do anything. */
+public object NonDisposableHandle : DisposableHandle, ChildHandle {
+    /**
+     * Does not do anything.
+     * @suppress
+     */
     override fun dispose() {}
 
-    /** Returns "NonDisposableHandle" string. */
+    /**
+     * Returns `false`.
+     * @suppress
+     */
+    override fun childFailed(cause: Throwable): Boolean = false
+
+    /**
+     * Returns "NonDisposableHandle" string.
+     * @suppress
+     */
     override fun toString(): String = "NonDisposableHandle"
 }

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

@@ -125,7 +125,7 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
     private val _state = atomic<Any?>(if (active) EMPTY_ACTIVE else EMPTY_NEW)
 
     @Volatile
-    private var parentHandle: DisposableHandle? = null
+    private var parentHandle: ChildHandle? = null
 
     // ------------ initialization ------------
 
@@ -222,7 +222,9 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
         }
         // Now handle exception
         if (finalException != null) {
-            if (!failParent(finalException)) handleJobException(finalException)
+            if (!failParent(finalException)) {
+                handleJobException(finalException)
+            }
         }
         // Then CAS to completed state -> it must succeed
         require(_state.compareAndSet(state, finalState)) { "Unexpected state: ${_state.value}, expected: $state, update: $finalState" }
@@ -614,7 +616,7 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
         fail(cause, cancel = true) && handlesException
 
     // child is reporting failure to the parent
-    public override fun childFailed(cause: Throwable) =
+    internal fun childFailed(cause: Throwable) =
         fail(cause, cancel = false) && handlesException
 
     // parent is cancelling child
@@ -869,14 +871,14 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
     }
 
     @Suppress("OverridingDeprecatedMember")
-    public final override fun attachChild(child: Job): DisposableHandle {
+    public final override fun attachChild(child: Job): ChildHandle {
         /*
          * Note: This function attaches a special ChildNode object. This node object
          * is handled in a special way on completion on the coroutine (we wait for all of them) and
          * is handled specially by invokeOnCompletion itself -- it adds this node to the list even
          * if the job is already failing.
          */
-        return invokeOnCompletion(onFailing = true, handler = ChildJob(this, child).asHandler)
+        return invokeOnCompletion(onFailing = true, handler = ChildJob(this, child).asHandler) as ChildHandle
     }
 
     @Suppress("OverridingDeprecatedMember")
@@ -901,8 +903,12 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
      */
     internal open fun onFailing(cause: Throwable?) {}
 
-    // todo: make it for all kinds of coroutines, now only launch & actor override and handleExceptionViaJob
-    internal open fun failParent(exception: Throwable): Boolean = false
+    /**
+     * When this function returns `true` the parent fails on the failure of this job.
+     *
+     * @suppress **This is unstable API and it is subject to change.*
+     */
+    protected open val failsParent: Boolean get() = false
 
     /**
      * Returns `true` for jobs that handle their exceptions via [handleJobException] or integrate them
@@ -921,6 +927,12 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
      */
     protected open fun handleJobException(exception: Throwable) {}
 
+    private fun failParent(cause: Throwable): Boolean {
+        if (cause is CancellationException) return true
+        if (!failsParent) return false
+        return parentHandle?.childFailed(cause) == true
+    }
+
     /**
      * Override for post-completion actions that need to do something with the state.
      * @param state the final state.
@@ -1280,8 +1292,9 @@ private class InvokeOnFailing(
 internal class ChildJob(
     parent: JobSupport,
     @JvmField val childJob: Job
-) : JobFailingNode<JobSupport>(parent) {
+) : JobFailingNode<JobSupport>(parent), ChildHandle {
     override fun invoke(cause: Throwable?) = childJob.cancelChild(job)
+    override fun childFailed(cause: Throwable): Boolean = job.childFailed(cause)
     override fun toString(): String = "ChildJob[$childJob]"
 }
 

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

@@ -68,9 +68,6 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
     /** Always returns `false`. */
     override fun cancel(cause: Throwable?): Boolean = false // never handles exceptions
 
-    /** @suppress */
-    override fun childFailed(cause: Throwable): Boolean = false // never handles exceptions
-
     /** @suppress */
     override fun cancelChild(parentJob: Job): Unit = error("Cannot be invoked, does not have a parent")
 
@@ -80,7 +77,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
 
     /** Always returns [NonDisposableHandle] and does not do anything. */
     @Suppress("OverridingDeprecatedMember")
-    override fun attachChild(child: Job): DisposableHandle = NonDisposableHandle
+    override fun attachChild(child: Job): ChildHandle = NonDisposableHandle
 
     /** Does not do anything. */
     @Suppress("OverridingDeprecatedMember")

core/kotlinx-coroutines-core/src/channels/Actor.kt

@@ -197,7 +197,7 @@ private open class ActorCoroutine<E>(
         _channel.cancel(cause)
     }
 
-    override fun failParent(exception: Throwable) = failParentImpl(exception)
+    override val failsParent: Boolean get() = true
     override fun handleJobException(exception: Throwable) = handleExceptionViaHandler(parentContext, exception)
 }