Job.children property is introduced;

Job.cancelChildren is now an extension (member is deprecated & hidden);
Job.joinChildren extension is introduced.

Author: elizarov

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt

@@ -48,7 +48,7 @@ import kotlin.coroutines.experimental.CoroutineContext
  * _cancelling_ state immediately. A simple implementation of deferred -- [CompletableDeferred],
  * that is not backed by a coroutine, does not have a _cancelling_ state, but becomes _cancelled_
  * on [cancel] immediately. Coroutines, on the other hand, become _cancelled_ only when they finish
- * executing their code and after all their children complete.
+ * executing their code and after all their [children] complete.
  *
  * ```
  *                                                     wait children
@@ -71,7 +71,7 @@ import kotlin.coroutines.experimental.CoroutineContext
  * or the cancellation cause inside the coroutine.
  *
  * A deferred value can have a _parent_ job. A deferred value with a parent is cancelled when its parent is
- * cancelled or completes. Parent waits for all its children to complete in _completing_ or
+ * cancelled or completes. Parent waits for all its [children] to complete in _completing_ or
  * _cancelling_ state. _Completing_ state is purely internal. For an outside observer a _completing_
  * deferred is still active, while internally it is waiting for its children.
  *

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt

@@ -30,14 +30,15 @@ import kotlinx.coroutines.experimental.selects.select
 import java.util.concurrent.Future
 import kotlin.coroutines.experimental.Continuation
 import kotlin.coroutines.experimental.CoroutineContext
+import kotlin.coroutines.experimental.buildSequence
 import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
 
 // --------------- core job interfaces ---------------
 
 /**
  * A background job. Conceptually, a job is a cancellable thing with a simple life-cycle that
  * culminates in its completion. Jobs can be arranged into parent-child hierarchies where cancellation
- * or completion of parent immediately cancels all its children.
+ * or completion of parent immediately cancels all its [children].
  *
  * The most basic instances of [Job] are created with [launch] coroutine builder or with a
  * `Job()` factory function.  Other coroutine builders and primitives like
@@ -60,7 +61,7 @@ import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
  *
  * A job can be _cancelled_ at any time with [cancel] function that forces it to transition to
  * _cancelling_ state immediately. Job that is not backed by a coroutine and does not have
- * children becomes _cancelled_ on [cancel] immediately.
+ * [children] becomes _cancelled_ on [cancel] immediately.
  * Otherwise, job becomes _cancelled_  when it finishes executing its code and
  * when all its children [complete][isCompleted].
  *
@@ -117,15 +118,15 @@ public interface Job : CoroutineContext.Element {
 
     /**
      * Returns `true` when this job is active -- it was already started and has not completed or cancelled yet.
-     * The job that is waiting for its children to complete is still considered to be active if it
+     * The job that is waiting for its [children] to complete is still considered to be active if it
      * was not cancelled.
      */
     public val isActive: Boolean
 
     /**
      * Returns `true` when this job has completed for any reason. A job that was cancelled and has
      * finished its execution is also considered complete. Job becomes complete only after
-     * all its children complete.
+     * all its [children] complete.
      */
     public val isCompleted: Boolean
 
@@ -180,6 +181,25 @@ public interface Job : CoroutineContext.Element {
 
     // ------------ parent-child ------------
 
+    /**
+     * Returns a sequence of this job's children.
+     *
+     * A job becomes a child of this job when it is constructed with this job in its
+     * [CoroutineContext] or using an explicit `parent` parameter.
+     *
+     * A parent-child relation has the following effect:
+     *
+     * * Cancellation of parent with [cancel] or its exceptional completion (failure)
+     *   immediately cancels all its children.
+     * * Parent cannot complete until all its children are complete. Parent waits for all its children to
+     *   complete in _completing_ or _cancelling_ state.
+     * * Uncaught exception in a child, by default, cancels parent. In particular, this applies to
+     *   children created with [launch] coroutine builder. Note, that [async] and other future-like
+     *   coroutine builders do not have uncaught exceptions by definition, since all their exceptions are
+     *   caught and are encapsulated in their result.
+     */
+    public val children: Sequence<Job>
+
     /**
      * Attaches child job so that this job becomes its parent and
      * returns a handle that should be used to detach it.
@@ -205,7 +225,9 @@ public interface Job : CoroutineContext.Element {
     /**
      * Cancels all children jobs of this coroutine with the given [cause]. Unlike [cancel],
      * the state of this job itself is not affected.
+     * @suppress **Deprecated**: Binary compatibility, it is an extension now
      */
+    @Deprecated(message = "Binary compatibility, it is an extension now", level = DeprecationLevel.HIDDEN)
     public fun cancelChildren(cause: Throwable? = null)
 
     // ------------ state waiting ------------
@@ -385,6 +407,8 @@ public class JobCancellationException(
         (message!!.hashCode() * 31 + job.hashCode()) * 31 + (cause?.hashCode() ?: 0)
 }
 
+// -------------------- Job extensions --------------------
+
 /**
  * Unregisters a specified [registration] when this job is complete.
  *
@@ -440,6 +464,25 @@ public suspend fun Job.cancelAndJoin() {
     return join()
 }
 
+/**
+ * Cancels all [children][Job.children] jobs of this coroutine with the given [cause] using [cancel]
+ * for all of them. Unlike [cancel] on this job as a whole, the state of this job itself is not affected.
+ */
+public fun Job.cancelChildren(cause: Throwable? = null) {
+    children.forEach { it.cancel(cause) }
+}
+
+/**
+ * Suspends coroutine until all [children][Job.children] of this job are complete using
+ * [join] for all of them. Unlike [join] on this job as a whole, it does not wait until
+ * this job is complete.
+ */
+public suspend fun Job.joinChildren() {
+    children.forEach { it.join() }
+}
+
+// -------------------- CoroutineContext extensions --------------------
+
 /**
  * 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
@@ -1057,19 +1100,21 @@ public open class JobSupport(active: Boolean) : Job, SelectClause0, SelectClause
         }
     }
 
-    override fun attachChild(child: Job): DisposableHandle =
-        invokeOnCompletion(onCancelling = true, handler = Child(this, child))
-
-    public override fun cancelChildren(cause: Throwable?) {
-        val state = this.state
+    override val children: Sequence<Job> get() = buildSequence<Job> {
+        val state = this@JobSupport.state
         when (state) {
-            is Child -> state.childJob.cancel(cause)
-            is Incomplete -> state.list?.cancelChildrenList(cause)
+            is Child -> yield(state.childJob)
+            is Incomplete -> state.list?.let { list ->
+                list.forEach<Child> { yield(it.childJob) }
+            }
         }
     }
 
-    private fun NodeList.cancelChildrenList(cause: Throwable?) {
-        forEach<Child> { it.childJob.cancel(cause) }
+    override fun attachChild(child: Job): DisposableHandle =
+        invokeOnCompletion(onCancelling = true, handler = Child(this, child))
+
+    public override fun cancelChildren(cause: Throwable?) {
+        this.cancelChildren(cause) // use extension function
     }
 
     /**

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/NonCancellable.kt

@@ -72,9 +72,15 @@ object NonCancellable : AbstractCoroutineContextElement(Job), Job {
     /** Always returns `false`. */
     override fun cancel(cause: Throwable?): Boolean = false
 
+    /** Always returns [emptySequence]. */
+    override val children: Sequence<Job>
+        get() = emptySequence()
+
     /** Always returns [NonDisposableHandle] and does not do anything. */
+    @Suppress("OverridingDeprecatedMember")
     override fun attachChild(child: Job): DisposableHandle = NonDisposableHandle
 
     /** Does not do anything. */
+    @Suppress("OverridingDeprecatedMember")
     override fun cancelChildren(cause: Throwable?) {}
 }

core/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/CoroutinesTest.kt

@@ -359,5 +359,26 @@ class CoroutinesTest : TestBase() {
         parent.cancelAndJoin() // cancel parent, make sure no stack overflow
     }
 
+    @Test
+    fun testCancelAndJoinChildren() = runTest {
+        expect(1)
+        val parent = Job()
+        launch(coroutineContext, CoroutineStart.UNDISPATCHED, parent = parent) {
+            expect(2)
+            try {
+                yield() // to be cancelled
+            } finally {
+                expect(5)
+            }
+            expectUnreached()
+        }
+        expect(3)
+        parent.cancelChildren()
+        expect(4)
+        parent.joinChildren() // will yield to child
+        check(parent.isActive) // make sure it did not cancel parent
+        finish(6)
+    }
+
     private fun throwIOException() { throw IOException() }
 }

coroutines-guide.md

@@ -1425,7 +1425,8 @@ The following example prints the first ten prime numbers,
 running the whole pipeline in the context of the main thread. Since all the coroutines are launched as
 children of the main [runBlocking] coroutine in its [coroutineContext][CoroutineScope.coroutineContext],
 we don't have to keep an explicit list of all the coroutine we have started. 
-We use [cancelChildren] extension function to cancel all the children coroutines. 
+We use [cancelChildren][kotlin.coroutines.experimental.CoroutineContext.cancelChildren] 
+extension function to cancel all the children coroutines. 
 
 ```kotlin
 fun main(args: Array<String>) = runBlocking<Unit> {
@@ -2371,7 +2372,7 @@ Channel was closed
 [newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
 [CoroutineName]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-name/index.html
 [Job()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job.html
-[cancelChildren]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/kotlin.coroutines.experimental.-coroutine-context/cancel-children.html
+[kotlin.coroutines.experimental.CoroutineContext.cancelChildren]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/kotlin.coroutines.experimental.-coroutine-context/cancel-children.html
 [CompletableDeferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-completable-deferred/index.html
 [Deferred.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/on-await.html
 <!--- INDEX kotlinx.coroutines.experimental.sync -->