defer coroutine builder is renamed to async.

`lazyDefer` is deprecated, `async` has an optional `start` parameter instead.
`LazyDeferred` interface is deprecated, lazy start functionality is integrated into `Job` interface.
`launch` has an optional `start` parameter for lazily started coroutines.
`Job.start` and `Job.isCompleted` are introduced.
`Job.join` is now a member function.
Internal `JobSupport` state machine is enhanced to support _new_ (not-started-yet) state.
So, lazy coroutines do not need a separate state variable to track their started/not-started (new/active) status.
Example on async-style functions is added to coroutines guide.

Author: elizarov

coroutines-guide.md

@@ -40,8 +40,9 @@ This is a short guide on core features of `kotlinx.coroutines` with a series of
   * [Timeout](#timeout)
 * [Composing suspending functions](#composing-suspending-functions)
   * [Sequential by default](#sequential-by-default)
-  * [Concurrent using deferred value](#concurrent-using-deferred-value)
-  * [Lazily deferred value](#lazily-deferred-value)
+  * [Concurrent using async](#concurrent-using-async)
+  * [Lazily started async](#lazily-started-async)
+  * [Async-style functions](#async-style-functions)
 * [Coroutine context and dispatchers](#coroutine-context-and-dispatchers)
   * [Dispatchers and threads](#dispatchers-and-threads)
   * [Unconfined vs confined dispatcher](#unconfined-vs-confined-dispatcher)
@@ -511,7 +512,7 @@ In practise we do this if we use the results of the first function to make a dec
 to invoke the second one or to decide on how to invoke it.
 
 We just use a normal sequential invocation, because the code in the coroutine, just like in the regular 
-code, is _sequential_ by default. The following example demonstrates that by measuring the total 
+code, is _sequential_ by default. The following example demonstrates it by measuring the total 
 time it takes to execute both suspending functions:
 
 ```kotlin
@@ -534,22 +535,22 @@ The answer is 42
 Completed in 2017 ms
 ```
 
-### Concurrent using deferred value
+### Concurrent using async
 
 What if there are no dependencies between invocation of `doSomethingUsefulOne` and `doSomethingUsefulTwo` and
-we want to get the answer faster, by doing both _concurrently_? This is where `defer` comes to helps. 
+we want to get the answer faster, by doing both _concurrently_? This is where `async` comes to help. 
 
-Conceptually, `defer` is just like `launch`. It starts a separate coroutine which is a light-weight thread 
+Conceptually, `async` is just like `launch`. It starts a separate coroutine which is a light-weight thread 
 that works concurrently with all the other coroutines. The difference is that `launch` returns a `Job` and 
-does not carry any resulting value, while `defer` returns a `Deferred` -- a kind of light-weight non-blocking future
-that represent a promise to provide result later. You can use `.await()` on a deferred value to get its eventual result,
+does not carry any resulting value, while `async` returns a `Deferred` -- a light-weight non-blocking future
+that represents a promise to provide a result later. You can use `.await()` on a deferred value to get its eventual result,
 but `Deferred` is also a `Job`, so you can cancel it if needed.
 
 ```kotlin
 fun main(args: Array<String>) = runBlocking<Unit> {
     val time = measureTimeMillis {
-        val one = defer(CommonPool) { doSomethingUsefulOne() }
-        val two = defer(CommonPool) { doSomethingUsefulTwo() }
+        val one = async(CommonPool) { doSomethingUsefulOne() }
+        val two = async(CommonPool) { doSomethingUsefulTwo() }
         println("The answer is ${one.await() + two.await()}")
     }
     println("Completed in $time ms")
@@ -568,17 +569,17 @@ Completed in 1017 ms
 This is twice as fast, because we have concurrent execution of two coroutines. 
 Note, that concurrency with coroutines is always explicit.
 
-### Lazily deferred value
+### Lazily started async
 
-There is a lazy alternative to `defer` that is called `lazyDefer`. It is just like `defer`, but it 
-starts coroutine only when its result is needed by some `await` or if a special `start` function 
-is invoked. Run the following example:
+There is a laziness option to `async` with `start = false` parameter. 
+It starts coroutine only when its result is needed by some `await` or if a `start` function 
+is invoked. Run the following example that differs from the previous one only by this option:
 
 ```kotlin
 fun main(args: Array<String>) = runBlocking<Unit> {
     val time = measureTimeMillis {
-        val one = lazyDefer(CommonPool) { doSomethingUsefulOne() }
-        val two = lazyDefer(CommonPool) { doSomethingUsefulTwo() }
+        val one = async(CommonPool, start = false) { doSomethingUsefulOne() }
+        val two = async(CommonPool, start = false) { doSomethingUsefulTwo() }
         println("The answer is ${one.await() + two.await()}")
     }
     println("Completed in $time ms")
@@ -594,13 +595,57 @@ The answer is 42
 Completed in 2017 ms
 ```
 
-So, we are back to two sequential execution, because we _first_ await for the `one` deferred, _and then_ await
-for the second one. It is not the intended use-case for `lazyDefer`. It is designed as a replacement for
-the standard `lazy` function in cases when computation of the value involve suspending functions.
+So, we are back to sequential execution, because we _first_ start and await for `one`, _and then_ start and await
+for `two`. It is not the intended use-case for laziness. It is designed as a replacement for
+the standard `lazy` function in cases when computation of the value involves suspending functions.
+
+### Async-style functions
+
+We can define async-style functions that invoke `doSomethingUsefulOne` and `doSomethingUsefulTwo`
+_asynchronously_ using `async` coroutine builder. It is a good style to name such functions with 
+either "async" prefix of "Async" suffix to highlight the fact that they only start asynchronous 
+computation and one needs to use the resulting deferred value to get the result.
+
+```kotlin
+// The result type of asyncSomethingUsefulOne is Deferred<Int>
+fun asyncSomethingUsefulOne() = async(CommonPool) {
+    doSomethingUsefulOne()
+}
+
+// The result type of asyncSomethingUsefulTwo is Deferred<Int>
+fun asyncSomethingUsefulTwo() = async(CommonPool)  {
+    doSomethingUsefulTwo()
+}
+```
+
+Note, that these `asyncXXX` function are **not** _suspending_ functions. They can be used from anywhere.
+However, their use always implies asynchronous (here meaning _concurrent_) execution of their action
+with the invoking code.
+ 
+The following example shows their use outside of coroutine:  
+ 
+```kotlin
+// note, that we don't have `runBlocking` to the right of `main` in this example
+fun main(args: Array<String>) {
+    val time = measureTimeMillis {
+        // we can initiate async actions outside of a coroutine
+        val one = asyncSomethingUsefulOne()
+        val two = asyncSomethingUsefulTwo()
+        // but waiting for a result must involve either suspending or blocking.
+        // here we use `runBlocking { ... }` to block the main thread while waiting for the result
+        runBlocking {
+            println("The answer is ${one.await() + two.await()}")
+        }
+    }
+    println("Completed in $time ms")
+}
+```
+
+> You can get full code [here](kotlinx-coroutines-core/src/test/kotlin/guide/example-compose-04.kt)
 
 ## Coroutine context and dispatchers
 
-We've already seen `launch(CommonPool) {...}`, `defer(CommonPool) {...}`, `run(NonCancellable) {...}`, etc.
+We've already seen `launch(CommonPool) {...}`, `async(CommonPool) {...}`, `run(NonCancellable) {...}`, etc.
 In these code snippets `CommonPool` and `NonCancellable` are _coroutine contexts_. 
 This section covers other available choices.
 
@@ -701,11 +746,11 @@ Run the following code with `-Dkotlinx.coroutines.debug` JVM option:
 fun log(msg: String) = println("[${Thread.currentThread().name}] $msg")
 
 fun main(args: Array<String>) = runBlocking<Unit> {
-    val a = defer(context) {
+    val a = async(context) {
         log("I'm computing a piece of the answer")
         6
     }
-    val b = defer(context) {
+    val b = async(context) {
         log("I'm computing another piece of the answer")
         7
     }
@@ -879,12 +924,12 @@ fun log(msg: String) = println("[${Thread.currentThread().name}] $msg")
 fun main(args: Array<String>) = runBlocking(CoroutineName("main")) {
     log("Started main coroutine")
     // run two background value computations
-    val v1 = defer(CommonPool + CoroutineName("v1coroutine")) {
+    val v1 = async(CommonPool + CoroutineName("v1coroutine")) {
         log("Computing v1")
         delay(500)
         252
     }
-    val v2 = defer(CommonPool + CoroutineName("v2coroutine")) {
+    val v2 = async(CommonPool + CoroutineName("v2coroutine")) {
         log("Computing v2")
         delay(1000)
         6

kotlinx-coroutines-core/README.md

@@ -9,7 +9,7 @@ General-purpose coroutine builders and contexts.
 * `launch(context) {...}` to start a coroutine in the given context and get reference to its `Job`.
 * `run(context) {...}` to switch to a different context inside a coroutine.
 * `runBlocking {...}` to use asynchronous Kotlin APIs from a thread-blocking code.  
-* `defer(context) {...}` and `lazyDefer(context) {...}` to get a deferred result of coroutine execution in a 
+* `async(context) {...}` to get a deferred result of coroutine execution in a 
    non-blocking way via a light-weight future interface called `Deferred`.
 * `delay(...)` for a non-blocking sleep in coroutines and 
   `yield()` to release a thread in single-threaded dispatchers.

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

@@ -23,24 +23,32 @@ import kotlin.coroutines.experimental.*
 
 /**
  * Launches new coroutine without blocking current thread and returns a reference to the coroutine as a [Job].
- * The running coroutine is cancelled when the resulting job is [cancelled][Job.cancel].
+ * The coroutine is cancelled when the resulting job is [cancelled][Job.cancel].
  *
  * The [context] for the new coroutine must be explicitly specified.
  * See [CoroutineDispatcher] for the standard [context] implementations that are provided by `kotlinx.coroutines`.
  * The [context][CoroutineScope.context] of the parent coroutine from its [scope][CoroutineScope] may be used,
  * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
  *
+ * An optional [start] parameter can be set to `false` to start coroutine _lazily_. When `start = false`,
+ * the coroutine [Job] is created in _new_ state. It can be explicitly started with [start][Job.start] function
+ * and will be started implicitly on the first invocation of [join][Job.join].
+ *
  * Uncaught exceptions in this coroutine cancel parent job in the context by default
  * (unless [CoroutineExceptionHandler] is explicitly specified), which means that when `launch` is used with
  * the context of another coroutine, then any uncaught exception leads to the cancellation of parent coroutine.
  *
  * See [newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
  */
-fun launch(context: CoroutineContext, block: suspend CoroutineScope.() -> Unit): Job =
-    StandaloneCoroutine(newCoroutineContext(context)).apply {
-        initParentJob(context[Job])
-        block.startCoroutine(this, this)
-    }
+fun launch(context: CoroutineContext, start: Boolean = true, block: suspend CoroutineScope.() -> Unit): Job {
+    val newContext = newCoroutineContext(context)
+    val coroutine = if (start)
+        StandaloneCoroutine(newContext, active = true) else
+        LazyStandaloneCoroutine(newContext, block)
+    coroutine.initParentJob(context[Job])
+    if (start) block.startCoroutine(coroutine, coroutine)
+    return coroutine
+}
 
 /**
  * Calls the specified suspending block with a given coroutine context, suspends until it completes, and returns
@@ -57,7 +65,7 @@ public suspend fun <T> run(context: CoroutineContext, block: suspend CoroutineSc
     }
 
 /**
- * Runs new coroutine and *blocks* current thread *interruptibly* until its completion.
+ * Runs new coroutine and **blocks** current thread _interruptibly_ until its completion.
  * This function should not be used from coroutine. It is designed to bridge regular blocking code
  * to libraries that are written in suspending style, to be used in `main` functions and in tests.
  *
@@ -84,15 +92,25 @@ public fun <T> runBlocking(context: CoroutineContext = EmptyCoroutineContext, bl
 
 // --------------- implementation ---------------
 
-private class StandaloneCoroutine(
-    val parentContext: CoroutineContext
-) : AbstractCoroutine<Unit>(parentContext) {
+private open class StandaloneCoroutine(
+    val parentContext: CoroutineContext,
+    active: Boolean
+) : AbstractCoroutine<Unit>(parentContext, active) {
     override fun afterCompletion(state: Any?) {
         // note the use of the parent's job context below!
         if (state is CompletedExceptionally) handleCoroutineException(parentContext, state.exception)
     }
 }
 
+private class LazyStandaloneCoroutine(
+    parentContext: CoroutineContext,
+    val block: suspend CoroutineScope.() -> Unit
+) : StandaloneCoroutine(parentContext, active = false) {
+    override fun onStart() {
+        block.startCoroutine(this, this)
+    }
+}
+
 private class InnerCoroutine<in T>(
     override val context: CoroutineContext,
     continuation: Continuation<T>
@@ -104,7 +122,7 @@ private class BlockingCoroutine<T>(
     context: CoroutineContext,
     val blockedThread: Thread,
     val hasPrivateEventLoop: Boolean
-) : AbstractCoroutine<T>(context) {
+) : AbstractCoroutine<T>(context, active = true) {
     val eventLoop: EventLoop? = context[ContinuationInterceptor] as? EventLoop
 
     override fun afterCompletion(state: Any?) {

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

@@ -31,9 +31,11 @@ import kotlin.coroutines.experimental.suspendCoroutine
  * with the specified cancel cause.
  *
  * Cancellable continuation has three states:
- * * _Active_ (initial state) -- [isActive] `true`, [isCancelled] `false`.
- * * _Resumed_ (final _completed_ state) -- [isActive] `false`, [isCancelled] `false`.
- * * _Canceled_ (final _completed_ state) -- [isActive] `false`, [isCancelled] `true`.
+ *
+ * | **State**                           | [isActive] | [isCompleted] | [isCancelled] |
+ * | _Active_ (initial state)            | `true`     | `false`       | `false`       |
+ * | _Resumed_ (final _completed_ state) | `false`    | `true`        | `false`       |
+ * | _Canceled_ (final _completed_ state)| `false`    | `true`        | `true`        |
  *
  * Invocation of [cancel] transitions this continuation from _active_ to _cancelled_ state, while
  * invocation of [resume] or [resumeWithException] transitions it from _active_ to _resumed_ state.
@@ -43,7 +45,9 @@ import kotlin.coroutines.experimental.suspendCoroutine
  */
 public interface CancellableContinuation<in T> : Continuation<T>, Job {
     /**
-     * Returns `true` if this continuation was [cancelled][cancel]. It implies that [isActive] is `false`.
+     * Returns `true` if this continuation was [cancelled][cancel].
+     *
+     * It implies that [isActive] is `false` and [isCompleted] is `true`.
      */
     val isCancelled: Boolean
 
@@ -105,7 +109,7 @@ internal fun getParentJobOrAbort(cont: Continuation<*>): Job? {
 internal class SafeCancellableContinuation<in T>(
         private val delegate: Continuation<T>,
         private val parentJob: Job?
-) : AbstractCoroutine<T>(delegate.context), CancellableContinuation<T> {
+) : AbstractCoroutine<T>(delegate.context, active = true), CancellableContinuation<T> {
     // only updated from the thread that invoked suspendCancellableCoroutine
 
     @Volatile
@@ -144,7 +148,7 @@ internal class SafeCancellableContinuation<in T>(
         while (true) { // lock-free loop on state
             val state = getState() // atomic read
             when (state) {
-                is Active -> if (tryUpdateState(state, value)) return state
+                is Incomplete -> if (tryUpdateState(state, value)) return state
                 else -> return null // cannot resume -- not active anymore
             }
         }
@@ -154,7 +158,7 @@ internal class SafeCancellableContinuation<in T>(
         while (true) { // lock-free loop on state
             val state = getState() // atomic read
             when (state) {
-                is Active -> if (tryUpdateState(state, CompletedExceptionally(exception))) return state
+                is Incomplete -> if (tryUpdateState(state, CompletedExceptionally(exception))) return state
                 else -> return null // cannot resume -- not active anymore
             }
         }

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

@@ -45,6 +45,9 @@ public object Unconfined : CoroutineDispatcher() {
     override fun dispatch(context: CoroutineContext, block: Runnable) { throw UnsupportedOperationException() }
 }
 
+/**
+ * **Deprecated**: `Here` was renamed to `Unconfined`.
+ */
 @Deprecated(message = "`Here` was renamed to `Unconfined`",
         replaceWith = ReplaceWith(expression = "Unconfined"))
 public typealias Here = Unconfined

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

@@ -52,17 +52,22 @@ public abstract class CoroutineDispatcher :
     public abstract fun dispatch(context: CoroutineContext, block: Runnable)
 
     override fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T> =
-            DispatchedContinuation<T>(this, continuation)
+            DispatchedContinuation(this, continuation)
 
+    /**
+     * **Error**: Operator '+' on two CoroutineDispatcher objects is meaningless.
+     * CoroutineDispatcher is a coroutine context element and `+` is a set-sum operator for coroutine contexts.
+     * The dispatcher to the right of `+` just replaces the dispatcher the left of `+`.
+     */
     @Suppress("DeprecatedCallableAddReplaceWith")
     @Deprecated(message = "Operator '+' on two CoroutineDispatcher objects is meaningless. " +
             "CoroutineDispatcher is a coroutine context element and `+` is a set-sum operator for coroutine contexts. " +
-            "The dispatcher to the right of `+` just replaces the dispacher the left of `+`.",
+            "The dispatcher to the right of `+` just replaces the dispatcher the left of `+`.",
             level = DeprecationLevel.ERROR)
     public operator fun plus(other: CoroutineDispatcher) = other
 }
 
-internal class DispatchedContinuation<T>(
+internal class DispatchedContinuation<in T>(
         val dispatcher: CoroutineDispatcher,
         val continuation: Continuation<T>
 ): Continuation<T> by continuation {
@@ -100,7 +105,7 @@ internal class DispatchedContinuation<T>(
         if (dispatcher.isDispatchNeeded(context))
             dispatcher.dispatch(context, Runnable {
                 withCoroutineContext(context) {
-                    if (job?.isActive == false)
+                    if (job?.isCompleted == true)
                         continuation.resumeWithException(job.getCompletionException())
                     else
                         continuation.resume(value)