Add awaitCancellation()

Resolves issue Kotlin#2213

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

@@ -7,6 +7,14 @@ package kotlinx.coroutines
 import kotlinx.atomicfu.*
 import kotlin.coroutines.*
 
+/**
+ * Suspends until cancellation, in which case it will throw a [CancellationException].
+ *
+ * Handy because it returns [Nothing], allowing it to be used in any coroutine,
+ * regardless of the required return type.
+ */
+public suspend inline fun awaitCancellation(): Nothing = suspendCancellableCoroutine {}
+
 /**
  * Awaits for completion of given deferred values without blocking a thread and resumes normally with the list of values
  * when all deferred computations are complete or resumes with the first thrown exception if any of computations

kotlinx-coroutines-core/common/test/AwaitCancellationTest.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.coroutines
+
+import kotlin.test.*
+
+class AwaitCancellationTest : TestBase() {
+
+    @Test
+    fun testCancellation() = runTest(expected = { it is CancellationException }) {
+        expect(1)
+        coroutineScope {
+            val deferred: Deferred<Nothing> = async {
+                expect(2)
+                awaitCancellation()
+            }
+            yield()
+            expect(3)
+            require(deferred.isActive)
+            deferred.cancel()
+            finish(4)
+            deferred.await()
+        }
+    }
+}