Introduce SupervisorJob & supervisorScope

This change also fixes propagation of cancellation for Job() constructor.
When both Job() and SupervisorJob() are cancelled with exception (fail),
they cancel their parent, too. So we have similar behavior between:
* Job() and coroutineScope { ... }
* SupervisorJob() and supervisorScope { ... }

Fixes #576

Author: elizarov

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

@@ -478,6 +478,12 @@ public final class kotlinx/coroutines/experimental/ScheduledKt {
 	public static synthetic fun withTimeoutOrNull$default (JLjava/util/concurrent/TimeUnit;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/experimental/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 }
 
+public final class kotlinx/coroutines/experimental/SupervisorKt {
+	public static final fun SupervisorJob (Lkotlinx/coroutines/experimental/Job;)Lkotlinx/coroutines/experimental/Job;
+	public static synthetic fun SupervisorJob$default (Lkotlinx/coroutines/experimental/Job;ILjava/lang/Object;)Lkotlinx/coroutines/experimental/Job;
+	public static final fun supervisorScope (Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
+}
+
 public abstract interface class kotlinx/coroutines/experimental/ThreadContextElement : kotlin/coroutines/experimental/CoroutineContext$Element {
 	public abstract fun restoreThreadContext (Lkotlin/coroutines/experimental/CoroutineContext;Ljava/lang/Object;)V
 	public abstract fun updateThreadContext (Lkotlin/coroutines/experimental/CoroutineContext;)Ljava/lang/Object;

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

@@ -68,17 +68,18 @@ public inline fun CoroutineExceptionHandler(crossinline handler: (CoroutineConte
     }
 
 /**
- * An optional element on the coroutine context to handle uncaught exceptions.
+ * An optional element in the coroutine context to handle uncaught exceptions.
+ *
+ * Normally, uncaught exceptions can only result from coroutines created using [launch][CoroutineScope.launch] builder.
+ * A coroutine that was created using [async][CoroutineScope.async] always catches all its exceptions and represents them
+ * in the resulting [Deferred] object.
  *
  * By default, when no handler is installed, uncaught exception are handled in the following way:
  * * If exception is [CancellationException] then it is ignored
- *   (because that is the supposed mechanism to cancel the running coroutine)
- * * Otherwise:
- *     * if there is a [Job] in the context, then [Job.cancel] is invoked;
- *     * all instances of [CoroutineExceptionHandler] found via [ServiceLoader] are invoked;
- *     * and current thread's [Thread.uncaughtExceptionHandler] is invoked.
- *
- * See [handleCoroutineException].
+ *   (because that is the supposed mechanism to cancel the running coroutine);
+ * * Otherwise, if there is a [Job] in the context, then [Job.cancel] is invoked;
+ * * Otherwise, all instances of [CoroutineExceptionHandler] found via [ServiceLoader] are invoked,
+ *   and current thread's [Thread.uncaughtExceptionHandler] is invoked.
  */
 public interface CoroutineExceptionHandler : CoroutineContext.Element {
     /**

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

@@ -146,7 +146,9 @@ object GlobalScope : CoroutineScope {
  * The provided scope inherits its [coroutineContext][CoroutineScope.coroutineContext] from the outer scope, but overrides
  * context's [Job].
  *
- * This methods returns as soon as given block and all launched from within the scope children coroutines are completed.
+ * This function is designed for a _parallel decomposition_ of work. When any child coroutine in this scope fails,
+ * this scope fails and all the rest of the children are cancelled (for a different behavior see [supervisorScope]).
+ * This function returns as soon as given block and all its children coroutines are completed.
  * Example of the scope usages looks like this:
  *
  * ```
@@ -169,7 +171,7 @@ object GlobalScope : CoroutineScope {
  * 2) If `doSomeWork` throws an exception, then `async` task is cancelled and `loadDataForUI` rethrows that exception.
  * 3) If outer scope of `loadDataForUI` is cancelled, both started `async` and `withContext` are cancelled.
  *
- * Method may throw [JobCancellationException] if the current job was cancelled externally
+ * Method may throw [CancellationException] if the current job was cancelled externally
  * or may throw the corresponding unhandled [Throwable] if there is any unhandled exception in this scope
  * (for example, from a crashed coroutine that was started with [launch][CoroutineScope.launch] in this scope).
  */

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

@@ -19,7 +19,9 @@ import kotlin.coroutines.experimental.*
  * of parent lead to an immediate cancellation of all its [children] and vice versa.
  *
  * The most basic instances of [Job] are created with [launch][CoroutineScope.launch] coroutine builder or with a
- * `Job()` factory function.
+ * `Job()` factory function. By default, a failure of a any of the job's children leads to an immediately failure
+ * of its parent and cancellation of the rest of its children. This behavior can be customized using [SupervisorJob].
+ *
  * Conceptually, an execution of the job does not produce a result value. Jobs are launched solely for their
  * side-effects. See [Deferred] interface for a job that produces a result.
  *
@@ -346,8 +348,16 @@ public interface Job : CoroutineContext.Element {
 }
 
 /**
- * Creates a new job object in an _active_ state.
- * It is optionally a child of a [parent] job.
+ * Creates a new job object in an active state.
+ * A failure of any child of this job immediately causes this job to fail, too, and cancels the rest of its children.
+ *
+ * To handle children failure independently of each other use [SupervisorJob].
+ *
+ * If [parent] job is specified, then this job becomes a child job of its parent and
+ * is cancelled when its parent fails or is cancelled. All this job's children are cancelled in this case, too.
+ * The invocation of [cancel][Job.cancel] with exception (other than [CancellationException]) on this job also cancels parent.
+ *
+ * @param parent an optional parent job.
  */
 @Suppress("FunctionName")
 public fun Job(parent: Job? = null): Job = JobImpl(parent)

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

@@ -603,13 +603,19 @@ internal open class JobSupport constructor(active: Boolean) : Job, ChildJob, Sel
     public override fun cancel(cause: Throwable?): Boolean =
         cancelImpl(cause) && handlesException
 
-    // parent is reporting failure to a child child
+    /**
+     * Parent is reporting failure to a child child
+     * @suppress **This is internal API and it is subject to change.**
+     */
     public final override fun parentCancelled(parentJob: Job) {
         cancelImpl(parentJob)
     }
 
-    // child was cancelled with cause
-    internal fun childCancelled(cause: Throwable): Boolean =
+    /**
+     * Child was cancelled with cause.
+     * @suppress **This is internal API and it is subject to change.**
+     */
+    public open fun childCancelled(cause: Throwable): Boolean =
         cancelImpl(cause) && handlesException
 
     // cause is Throwable or Job when cancelChild was invoked
@@ -693,7 +699,7 @@ internal open class JobSupport constructor(active: Boolean) : Job, ChildJob, Sel
 
     // Performs promotion of incomplete coroutine state to NodeList for the purpose of
     // converting coroutine state to Failing, returns null when need to retry
-    private fun getOrPromoteFailingList(state: Incomplete): NodeList? = state.list ?: 
+    private fun getOrPromoteFailingList(state: Incomplete): NodeList? = state.list ?:
         when (state) {
             is Empty -> NodeList() // we can allocate new empty list that'll get integrated into Failing state
             is JobNode<*> -> {
@@ -1161,6 +1167,7 @@ private class Empty(override val isActive: Boolean) : Incomplete {
 
 internal class JobImpl(parent: Job? = null) : JobSupport(true) {
     init { initParentJobInternal(parent) }
+    override val cancelsParent: Boolean get() = true
     override val onCancelComplete get() = true
     override val handlesException: Boolean get() = false
 }

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

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines.experimental
+
+import kotlin.coroutines.experimental.*
+
+/**
+ * Creates a new _supervisor_ job object in an active state.
+ * Children of a supervisor job can fail independently of each other.
+ * 
+ * A failure or cancellation of a child does not cause the supervisor job to fail and does not affect its other children,
+ * so a supervisor can implement a custom policy for handling failures of its children:
+ *
+ * * A failure of a child job that was created using [launch][CoroutineScope.launch] can be handled via [CoroutineExceptionHandler] in the context.
+ * * A failure of a child job that was created using [async][CoroutineScope.async] can be handled via [Deferred.await] on the resulting deferred value.
+ *
+ * If [parent] job is specified, then this supervisor job becomes a child job of its parent and is cancelled when its
+ * parent fails or is cancelled. All this supervisor's children are cancelled in this case, too. The invocation of
+ * of [cancel][Job.cancel] with exception (other than [CancellationException]) on this supervisor job also cancels parent.
+ *
+ * @param parent an optional parent job.
+ */
+@Suppress("FunctionName")
+public fun SupervisorJob(parent: Job? = null) : Job = SupervisorJobImpl(parent)
+
+/**
+ * Creates new [CoroutineScope] with [SupervisorJob] and calls the specified suspend block with this scope.
+ * The provided scope inherits its [coroutineContext][CoroutineScope.coroutineContext] from the outer scope, but overrides
+ * context's [Job] with [SupervisorJob].
+ *
+ * A failure of a child does not cause this scope to fail and does not affect its other children,
+ * so a custom policy for handling failures of its children can be implemented. See [SupervisorJob] for details.
+ */
+public suspend fun <R> supervisorScope(block: suspend CoroutineScope.() -> R): R {
+    // todo: optimize implementation to a single allocated object
+    // todo: fix copy-and-paste with coroutineScope
+    val owner = SupervisorCoroutine<R>(coroutineContext)
+    owner.start(CoroutineStart.UNDISPATCHED, owner, block)
+    owner.join()
+    if (owner.isCancelled) {
+        throw owner.getCancellationException().let { it.cause ?: it }
+    }
+    val state = owner.state
+    if (state is CompletedExceptionally) {
+        throw state.cause
+    }
+    @Suppress("UNCHECKED_CAST")
+    return state as R
+
+}
+
+private class SupervisorJobImpl(parent: Job?) : JobSupport(true) {
+    init { initParentJobInternal(parent) }
+    override val cancelsParent: Boolean get() = true
+    override val onCancelComplete get() = true
+    override val handlesException: Boolean get() = false
+    override fun childCancelled(cause: Throwable): Boolean = false
+}
+
+private class SupervisorCoroutine<R>(
+    parentContext: CoroutineContext
+) : AbstractCoroutine<R>(parentContext, true) {
+    override val cancelsParent: Boolean get() = true
+    override fun childCancelled(cause: Throwable): Boolean = false
+}

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

@@ -188,4 +188,24 @@ class JobTest : TestBase() {
         deferred.join()
         finish(3)
     }
+
+    @Test
+    fun testJobWithParentCancelNormally() {
+        val parent = Job()
+        val job = Job(parent)
+        job.cancel()
+        assertTrue(job.isCancelled)
+        assertFalse(parent.isCancelled)
+    }
+
+    @Test
+    fun testJobWithParentCancelException() {
+        val parent = Job()
+        val job = Job(parent)
+        job.cancel(TestException())
+        assertTrue(job.isCancelled)
+        assertTrue(parent.isCancelled)
+    }
+
+    private class TestException : Exception()
 }

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

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+@file:Suppress("NAMED_ARGUMENTS_NOT_ALLOWED") // KT-21913
+
+package kotlinx.coroutines.experimental
+
+import kotlin.test.*
+
+class SupervisorTest : TestBase() {
+    @Test
+    fun testSupervisorJob() = runTest(
+        unhandled = listOf(
+            { it -> it is TestException2 },
+            { it -> it is TestException1 }
+        )
+    ) {
+        expect(1)
+        val supervisor = SupervisorJob()
+        val job1 = launch(supervisor + CoroutineName("job1")) {
+            expect(2)
+            yield() // to second child
+            expect(4)
+            throw TestException1()
+        }
+        val job2 = launch(supervisor + CoroutineName("job2")) {
+            expect(3)
+            throw TestException2()
+        }
+        joinAll(job1, job2)
+        finish(5)
+        assertTrue(job1.isCancelled)
+        assertTrue(job2.isCancelled)
+    }
+
+    @Test
+    fun testSupervisorScope() = runTest(
+        unhandled = listOf(
+            { it -> it is TestException1 },
+            { it -> it is TestException2 }
+        )
+    ) {
+        val result = supervisorScope {
+            launch {
+                throw TestException1()
+            }
+            launch {
+                throw TestException2()
+            }
+            "OK"
+        }
+        assertEquals("OK", result)
+    }
+
+    @Test
+    fun testSupervisorWithParentCancelNormally() {
+        val parent = Job()
+        val supervisor = SupervisorJob(parent)
+        supervisor.cancel()
+        assertTrue(supervisor.isCancelled)
+        assertFalse(parent.isCancelled)
+    }
+
+    @Test
+    fun testSupervisorWithParentCancelException() {
+        val parent = Job()
+        val supervisor = SupervisorJob(parent)
+        supervisor.cancel(TestException1())
+        assertTrue(supervisor.isCancelled)
+        assertTrue(parent.isCancelled)
+    }
+
+    private class TestException1 : Exception()
+    private class TestException2 : Exception()
+}

core/kotlinx-coroutines-core/test/exceptions/JobBasicCancellationTest.kt

@@ -121,12 +121,10 @@ class JobBasicCancellationTest : TestBase() {
             expect(1)
             val child = Job(coroutineContext[Job])
             expect(2)
-            assertFalse(child.cancel(IOException()))
+            assertFalse(child.cancel())
             child.join()
-            assertTrue(child.getCancellationException().cause is IOException)
             expect(3)
         }
-
         parent.join()
         finish(4)
     }