Abolish distinction between cancelled and failed Job/Deferred

* Job.isCancelled is consistently true on any failure
* Deferred.isCompletedExceptionally is deprecated.
  It is equal to isCancelled && isCompleted
* CompletableDeferred.completeExceptionally is deprecated.
  Use cancel instead.

Fixes #220

Author: elizarov

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

@@ -8,7 +8,6 @@ public abstract class kotlinx/coroutines/experimental/AbstractCoroutine : kotlin
 	protected fun onCancellation (Ljava/lang/Throwable;)V
 	protected fun onCompleted (Ljava/lang/Object;)V
 	protected fun onCompletedExceptionally (Ljava/lang/Throwable;)V
-	protected fun onFailing (Ljava/lang/Throwable;)V
 	protected fun onStart ()V
 	public final fun resume (Ljava/lang/Object;)V
 	public final fun resumeWithException (Ljava/lang/Throwable;)V
@@ -383,7 +382,6 @@ public abstract interface class kotlinx/coroutines/experimental/Job : kotlin/cor
 	public abstract fun isActive ()Z
 	public abstract fun isCancelled ()Z
 	public abstract fun isCompleted ()Z
-	public abstract fun isFailed ()Z
 	public abstract fun join (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public abstract fun plus (Lkotlinx/coroutines/experimental/Job;)Lkotlinx/coroutines/experimental/Job;
 	public abstract fun start ()Z
@@ -455,15 +453,14 @@ public final class kotlinx/coroutines/experimental/NonCancellable : kotlin/corou
 	public fun isActive ()Z
 	public fun isCancelled ()Z
 	public fun isCompleted ()Z
-	public fun isFailed ()Z
 	public fun join (Lkotlin/coroutines/experimental/Continuation;)Ljava/lang/Object;
 	public fun plus (Lkotlinx/coroutines/experimental/Job;)Lkotlinx/coroutines/experimental/Job;
 	public fun start ()Z
 }
 
 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 childCancelled (Ljava/lang/Throwable;)Z
 	public fun dispose ()V
 	public fun toString ()Ljava/lang/String;
 }

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

@@ -89,7 +89,7 @@ internal abstract class AbstractContinuation<in T>(
             return
         }
         parent.start() // make sure the parent is started
-        val handle = parent.invokeOnCompletion(onFailing = true,
+        val handle = parent.invokeOnCompletion(onCancelling = true,
             handler = ChildContinuation(parent, this).asHandler)
 
         parentHandle = handle

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

@@ -20,7 +20,7 @@ import kotlin.coroutines.experimental.*
  * The following methods are available for override:
  *
  * * [onStart] is invoked when coroutine is create in not active state and is [started][Job.start].
- * * [onFailing] is invoked as soon as coroutine is _failing_, or is cancelled,
+ * * [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.
@@ -74,24 +74,16 @@ public abstract class AbstractCoroutine<in T>(
     }
 
     /**
-     * @suppress **Deprecated**: Override [onFailing].
-     */
-    @Deprecated("Override onFailing")
-    protected open fun onCancellation(cause: Throwable?) {}
-
-    /**
-     * This function is invoked once when this coroutine is failing or is completed,
-     * similarly to [invokeOnCompletion] with `onFailing` set to `true`.
+     * 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 override fun onFailing(cause: Throwable?) {
-        onCancellation(cause)
-    }
+    protected override fun onCancellation(cause: Throwable?) {}
 
     /**
      * This function is invoked once when job is completed normally with the specified [value].
@@ -101,6 +93,7 @@ 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")

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 val failsParent: Boolean get() = true
+    override val cancelsParent: Boolean get() = true
     override fun handleJobException(exception: Throwable) = handleExceptionViaHandler(parentContext, exception)
 }
 

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 onFailComplete get() = true
+    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,28 +8,20 @@ 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 and renamed until we get rid of MutableDelegateContinuation in IO**
  *
  * @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**.
- *
- * @suppress **This is unstable API and it is subject to change.**
- */
-internal class Cancelled(cause: Throwable) : CompletedExceptionally(cause)
-
 /**
  * A specific subclass of [CompletedExceptionally] for cancelled [AbstractContinuation].
  *

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

@@ -18,7 +18,7 @@ import kotlin.coroutines.experimental.*
  * successful or failed result of the computation that was carried out. The result of the deferred is
  * available when it is [completed][isCompleted] and can be retrieved by [await] method, which throws
  * exception if the deferred had failed.
- * A _failed_ deferred is considered to be [completed exceptionally][isCompletedExceptionally].
+ * Note, that a _cancelled_ deferred is also considered to be completed.
  * The corresponding exception can be retrieved via [getCompletionExceptionOrNull] from a completed instance of deferred.
  *
  * Usually, a deferred value is created in _active_ state (it is created and started).
@@ -36,14 +36,17 @@ import kotlin.coroutines.experimental.*
 public interface Deferred<out T> : Job {
     /**
      * Returns `true` if computation of this deferred value has _completed exceptionally_.
-     * It is `true` when both [isCompleted] and [isFailed] are true.
+     * It is `true` when both [isCompleted] and [isCancelled] are true.
      * It implies that [isActive] is `false`.
+     *
+     * @suppress **Deprecated**: Use [isCancelled] && [isCompleted]
      */
+    @Deprecated("Use isCancelled && isCompleted", ReplaceWith("this.isCancelled && this.isCompleted"))
     public val isCompletedExceptionally: Boolean
 
     /**
      * Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete,
-     * returning the resulting value or throwing the corresponding exception if the deferred had completed exceptionally or was cancelled.
+     * returning the resulting value or throwing the corresponding exception if the deferred was cancelled.
      *
      * This suspending function is cancellable.
      * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
@@ -63,17 +66,16 @@ public interface Deferred<out T> : Job {
 
     /**
      * Returns *completed* result or throws [IllegalStateException] if this deferred value has not
-     * [completed][isCompleted] yet. It throws the corresponding exception if this deferred has
-     * [completed exceptionally][isCompletedExceptionally].
+     * [completed][isCompleted] yet. It throws the corresponding exception if this deferred was [cancelled][isCancelled].
      *
      * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that
      * the value is already complete. See also [getCompletionExceptionOrNull].
      */
     public fun getCompleted(): T
 
     /**
-     * Returns *completion exception* result if this deferred [completed exceptionally][isCompletedExceptionally],
-     * `null` if it is completed normally, or throws [IllegalStateException] if this deferred value has not
+     * Returns *completion exception* result if this deferred was [cancelled][isCancelled] and has [completed][isCompleted],
+     * `null` if it had completed normally, or throws [IllegalStateException] if this deferred value has not
      * [completed][isCompleted] yet.
      *
      * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that