Introduce CancellationException

#KT-39126 Fixed

libraries/stdlib/api/js-v1/kotlin.coroutines.cancellation.kt

@@ -0,0 +1,11 @@
+@kotlin.ExperimentalStdlibApi
+@kotlin.SinceKotlin(version = "1.4")
+public open class CancellationException : kotlin.IllegalStateException {
+    public constructor CancellationException()
+
+    public constructor CancellationException(message: kotlin.String?)
+
+    public constructor CancellationException(message: kotlin.String?, cause: kotlin.Throwable?)
+
+    public constructor CancellationException(cause: kotlin.Throwable?)
+}

libraries/stdlib/api/js/kotlin.coroutines.cancellation.kt

@@ -0,0 +1,11 @@
+@kotlin.ExperimentalStdlibApi
+@kotlin.SinceKotlin(version = "1.4")
+public open class CancellationException : kotlin.IllegalStateException {
+    public constructor CancellationException()
+
+    public constructor CancellationException(message: kotlin.String?)
+
+    public constructor CancellationException(message: kotlin.String?, cause: kotlin.Throwable?)
+
+    public constructor CancellationException(cause: kotlin.Throwable?)
+}

libraries/stdlib/js/src/kotlin/coroutines/cancellation/CancellationException.kt

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.coroutines.cancellation
+
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public actual open class CancellationException : IllegalStateException {
+    actual constructor() : super()
+    actual constructor(message: String?) : super(message)
+    constructor(message: String?, cause: Throwable?) : super(message, cause)
+    constructor(cause: Throwable?) : super(cause)
+}

libraries/stdlib/jvm/src/kotlin/coroutines/cancellation/CancellationException.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.coroutines.cancellation
+
+import kotlin.internal.InlineOnly
+
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public actual typealias CancellationException = java.util.concurrent.CancellationException
+
+@InlineOnly
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public actual inline fun CancellationException(message: String?, cause: Throwable?): CancellationException {
+    return CancellationException(message).also { it.initCause(cause) }
+}
+@InlineOnly
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public actual inline fun CancellationException(cause: Throwable?): CancellationException {
+    return CancellationException(cause?.toString()).also { it.initCause(cause) }
+}

libraries/stdlib/src/kotlin/coroutines/cancellation/CancellationExceptionH.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.coroutines.cancellation
+
+/**
+ * Thrown by cancellable suspending functions if the coroutine is cancelled while it is suspended.
+ * It indicates _normal_ cancellation of a coroutine.
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public expect open class CancellationException : IllegalStateException {
+    public constructor()
+    public constructor(message: String?)
+}
+
+/**
+ * Creates an instance of [CancellationException] with the given [message] and [cause].
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+@Suppress("FunctionName", "NO_ACTUAL_FOR_EXPECT")
+public expect fun CancellationException(message: String?, cause: Throwable?): CancellationException
+
+/**
+ * Creates an instance of [CancellationException] with the given [cause].
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+@Suppress("FunctionName", "NO_ACTUAL_FOR_EXPECT")
+public expect fun CancellationException(cause: Throwable?): CancellationException

libraries/stdlib/test/coroutines/cancellation/CancellationExceptionTest.kt

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package coroutines.cancellation
+
+import kotlin.coroutines.cancellation.CancellationException
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class CancellationExceptionTest {
+
+    @Test
+    fun testAllConstructors() {
+        // Mostly test NO_ACTUAL_WITHOUT_EXPECT though
+        val cause = ArithmeticException()
+        val message = "message"
+        checkException(CancellationException(message, cause), cause, message)
+        checkException(CancellationException(message, null), null, message)
+        checkException(CancellationException(cause), cause, cause.defaultMessage())
+        checkException(CancellationException(message), null, message)
+        // TODO doesn't work on js ir KT-39964
+//        checkException(CancellationException(null, cause), cause, null)
+        checkException(CancellationException(cause = cause), cause, cause.defaultMessage())
+        // does not work on JVM because of typealias
+//      checkException(CancellationException(message = message), null, message)
+        checkException(CancellationException(), null, null)
+    }
+
+    private fun Throwable?.defaultMessage() = toString()
+
+    private fun checkException(e: CancellationException, expectedCause: Throwable?, expectedMessage: String?) {
+        assertEquals(expectedCause, e.cause)
+        assertEquals(expectedMessage, e.message)
+    }
+}