More comments about CancellationException and its consistent use;

JobCancellationException.job is made internal.

Author: elizarov

common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/AbstractCoroutine.kt

@@ -76,8 +76,11 @@ public abstract class AbstractCoroutine<in T>(
      * This function is invoked once when this coroutine is cancelled or is completed,
      * similarly to [invokeOnCompletion] with `onCancelling` set to `true`.
      *
-     * @param cause the cause that was passed to [Job.cancel] function, [JobCancellationException] if it was completed without cause
-     *        or `null` if coroutine is completing normally.
+     * 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_.
      */
     protected open fun onCancellation(cause: Throwable?) {}
 

common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/CompletedExceptionally.kt

@@ -16,6 +16,8 @@
 
 package kotlinx.coroutines.experimental
 
+import kotlinx.coroutines.experimental.internalAnnotations.*
+
 /**
  * Class for an internal state of a job that had completed exceptionally, including cancellation.
  *
@@ -26,7 +28,9 @@ package kotlinx.coroutines.experimental
  *        or artificial JobCancellationException if no cause was provided
  * @suppress **This is unstable API and it is subject to change.**
  */
-open class CompletedExceptionally(public val cause: Throwable) {
+open class CompletedExceptionally(
+    @JvmField public val cause: Throwable
+) {
     override fun toString(): String = "$classSimpleName[$cause]"
 }
 

common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/CompletionHandler.common.kt

@@ -24,6 +24,12 @@ import kotlinx.coroutines.experimental.internal.*
  * Installed handler should not throw any exceptions. If it does, they will get caught,
  * wrapped into [CompletionHandlerException], and rethrown, potentially causing crash of unrelated code.
  *
+ * The meaning of `cause` that is passed to the handler:
+ * * 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_.
+ *
  * **Note**: This type is a part of internal machinery that supports parent-child hierarchies
  * and allows for implementation of suspending functions that wait on the Job's state.
  * This type should not be used in general application code.

common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/Exceptions.common.kt

@@ -25,7 +25,7 @@ public expect class JobCancellationException(
     cause: Throwable?,
     job: Job
 ) : CancellationException {
-    val job: Job
+    internal val job: Job
 }
 
 internal expect class DispatchException(message: String, cause: Throwable) : RuntimeException

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

@@ -279,6 +279,12 @@ public interface Job : CoroutineContext.Element {
      * with a job's exception or cancellation cause or `null`. Otherwise, handler will be invoked once when this
      * job is complete.
      *
+     * The meaning of `cause` that is passed to the handler:
+     * * 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_.
+     *
      * The resulting [DisposableHandle] can be used to [dispose][DisposableHandle.dispose] the
      * registration of this handler and release its memory if its invocation is no longer needed.
      * There is no need to dispose the handler after completion of this job. The references to
@@ -297,6 +303,12 @@ public interface Job : CoroutineContext.Element {
      * with a job's cancellation cause or `null` unless [invokeImmediately] is set to false.
      * Otherwise, handler will be invoked once when this job is cancelled or complete.
      *
+     * The meaning of `cause` that is passed to the handler:
+     * * 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_.
+     *
      * Invocation of this handler on a transition to a transient _cancelling_ state
      * is controlled by [onCancelling] boolean parameter.
      * The handler is invoked on invocation of [cancel] when
@@ -648,7 +660,8 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
         if (proposedUpdate !is CompletedExceptionally) return cancelled // not exception -- just use original cancelled
         val exception = proposedUpdate.cause
         if (cancelled.cause == exception) return cancelled // that is the cancelled we need already!
-
+        // todo: We need to rework this logic to keep original cancellation cause in the state and suppress other exceptions
+        //       that could have occurred while coroutine is being cancelled.
         // Do not spam with JCE in suppressed exceptions
         if (cancelled.cause !is JobCancellationException) {
             exception.addSuppressedThrowable(cancelled.cause)

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

@@ -40,10 +40,7 @@ public actual typealias CancellationException = java.util.concurrent.Cancellatio
 public actual class JobCancellationException public actual constructor(
     message: String,
     cause: Throwable?,
-    /**
-     * The job that was cancelled.
-     */
-    public actual val job: Job
+    @JvmField internal actual val job: Job
 ) : CancellationException(message) {
 
     init {

core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Produce.kt

@@ -124,7 +124,7 @@ private class ProducerCoroutine<E>(
         val cause = exceptionally?.cause
         val processed = when (exceptionally) {
             // producer coroutine was cancelled -- cancel channel, but without cause if it was closed without cause
-            is Cancelled -> _channel.cancel(if (cause is JobCancellationException) null else cause)
+            is Cancelled -> _channel.cancel(if (cause is CancellationException) null else cause)
             else -> _channel.close(cause) // producer coroutine has completed -- close channel
         }
         if (!processed && cause != null)

js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Exceptions.kt

@@ -40,10 +40,7 @@ public actual open class CancellationException actual constructor(message: Strin
 public actual class JobCancellationException public actual constructor(
     message: String,
     public override val cause: Throwable?,
-    /**
-     * The job that was cancelled.
-     */
-    public actual val job: Job
+    internal actual val job: Job
 ) : CancellationException(message.withCause(cause)) {
     override fun toString(): String = "${super.toString()}; job=$job"
     override fun equals(other: Any?): Boolean =

reactive/kotlinx-coroutines-reactive/src/main/kotlin/kotlinx/coroutines/experimental/reactive/Publish.kt

@@ -167,7 +167,7 @@ private class PublisherCoroutine<in T>(
                 _nRequested.value = SIGNALLED // we'll signal onError/onCompleted (that the final state -- no CAS needed)
                 val cause = getCompletionCause()
                 try {
-                    if (cause != null && cause !is JobCancellationException)
+                    if (cause != null && cause !is CancellationException)
                         subscriber.onError(cause)
                     else
                         subscriber.onComplete()

reactive/kotlinx-coroutines-rx1/src/main/kotlin/kotlinx/coroutines/experimental/rx1/RxObservable.kt

@@ -168,7 +168,7 @@ private class RxObservableCoroutine<in T>(
                 _nRequested.value = SIGNALLED // we'll signal onError/onCompleted (that the final state -- no CAS needed)
                 val cause = getCompletionCause()
                 try {
-                    if (cause != null && cause !is JobCancellationException)
+                    if (cause != null && cause !is CancellationException)
                         subscriber.onError(cause)
                     else
                         subscriber.onCompleted()

reactive/kotlinx-coroutines-rx2/src/main/kotlin/kotlinx/coroutines/experimental/rx2/RxObservable.kt

@@ -158,7 +158,7 @@ private class RxObservableCoroutine<T>(
                 _signal.value = SIGNALLED // we'll signal onError/onCompleted (that the final state -- no CAS needed)
                 val cause = getCompletionCause()
                 try {
-                    if (cause != null && cause !is JobCancellationException)
+                    if (cause != null && cause !is CancellationException)
                         subscriber.onError(cause)
                     else
                         subscriber.onComplete()