Add CompletableDeferred.completeWith(result: Result<T>)

The naming for this convenience function is inspired by Continuation.resumeWith.

Author: glasser

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

@@ -119,6 +119,7 @@ public final class kotlinx/coroutines/CompletableDeferredKt {
 	public static final fun CompletableDeferred (Ljava/lang/Object;)Lkotlinx/coroutines/CompletableDeferred;
 	public static final fun CompletableDeferred (Lkotlinx/coroutines/Job;)Lkotlinx/coroutines/CompletableDeferred;
 	public static synthetic fun CompletableDeferred$default (Lkotlinx/coroutines/Job;ILjava/lang/Object;)Lkotlinx/coroutines/CompletableDeferred;
+	public static final fun completeWith (Lkotlinx/coroutines/CompletableDeferred;Ljava/lang/Object;)Z
 }
 
 public abstract interface class kotlinx/coroutines/CompletableJob : kotlinx/coroutines/Job {

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

@@ -45,6 +45,18 @@ public interface CompletableDeferred<T> : Deferred<T> {
     public fun completeExceptionally(exception: Throwable): Boolean
 }
 
+/**
+ * Completes this deferred value with the value or exception in the given [result]. Returns `true` if this deferred
+ * was completed as a result of this invocation and `false` otherwise (if it was already completed).
+ *
+ * Subsequent invocations of this function have no effect and always produce `false`.
+ *
+ * This function transitions this deferred in the same ways described by [CompletableDeferred.complete] and
+ * [CompletableDeferred.completeExceptionally].
+ */
+@ExperimentalCoroutinesApi // since 1.3.2, tentatively until 1.4.0
+public fun <T> CompletableDeferred<T>.completeWith(result: Result<T>) = result.fold({ complete(it) }, { completeExceptionally(it) })
+
 /**
  * Creates a [CompletableDeferred] in an _active_ state.
  * It is optionally a child of a [parent] job.

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

@@ -79,6 +79,26 @@ class CompletableDeferredTest : TestBase() {
         assertTrue(c.getCompletionExceptionOrNull() is TestException)
     }
 
+    @Test
+    fun testCompleteWithResultOK() {
+        val c = CompletableDeferred<String>()
+        assertEquals(true, c.completeWith(Result.success("OK")))
+        checkCompleteOk(c)
+        assertEquals("OK", c.getCompleted())
+        assertEquals(false, c.completeWith(Result.success("OK")))
+        checkCompleteOk(c)
+        assertEquals("OK", c.getCompleted())
+    }
+
+    @Test
+    fun testCompleteWithResultException() {
+        val c = CompletableDeferred<String>()
+        assertEquals(true, c.completeWith(Result.failure(TestException())))
+        checkCancelWithException(c)
+        assertEquals(false, c.completeWith(Result.failure(TestException())))
+        checkCancelWithException(c)
+    }
+
     @Test
     fun testParentCancelsChild() {
         val parent = Job()