Contribution guidelines for integrations and improved JDK8 readme

Author: elizarov

integration/README.md

@@ -4,5 +4,16 @@ This directory contains modules that provide integration with various asynchrono
 
 ## Modules
 
-* [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8) -- extensions for JDK8 `CompletableFuture` (Android API level 24).
-* [kotlinx-coroutines-nio](kotlinx-coroutines-nio) -- extensions for asynchronous IO on JDK7+ (Android O Preview).
+* [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8/README.md) -- extensions for JDK8 `CompletableFuture` (Android API level 24).
+* [kotlinx-coroutines-nio](kotlinx-coroutines-nio/README.md) -- extensions for asynchronous IO on JDK7+ (Android O Preview).
+
+## Contributing
+
+Follow the following simple guidelines when contributing integration with your favorite library:
+
+* Keep it simple and general. Ideally it should fit into a single file. If it does not fit, then consider
+  a separate GitHub project to host this integration.
+* Follow the example of other modules. Don't fear to cut-and-paste [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8)
+  module for a start.
+* Write tests and documentation, include top-level README.md with short overview and example.
+* Include it into the list of modules in this file and to the top-level [pom.xml](../pom.xml).

integration/kotlinx-coroutines-jdk8/README.md

@@ -12,9 +12,39 @@ Extension functions:
 
 | **Name** | **Description**
 | -------- | ---------------
-| [CompletableFuture.await][java.util.concurrent.CompletableFuture.await] | Awaits for completion of the future
+| [CompletionStage.await][java.util.concurrent.CompletionStage.await] | Awaits for completion of the completion stage (non-cancellable)
+| [CompletableFuture.await][java.util.concurrent.CompletableFuture.await] | Awaits for completion of the future (cancellable)
 | [Deferred.asCompletableFuture][kotlinx.coroutines.experimental.Deferred.asCompletableFuture] | Converts a deferred value to the future
 
+## Example
+
+Given the following functions defined in some Java API:
+
+```java
+public CompletableFuture<Image> loadImageAsync(String name); // starts async image loading
+public Image combineImages(Image image1, Image image2); // synchronously combines two images using some algorithm
+```
+
+We can consume this API from Kotlin coroutine to load two images and combine then asynchronously. 
+The resulting function returns `CompletableFuture<Image>` for ease of use back from Java. 
+
+```kotlin
+fun combineImagesAsync(name1: String, name2: String): CompletableFuture<Image> = future {
+    val future1 = loadImageAsync(name1) // start loading first image
+    val future2 = loadImageAsync(name2) // start loading second image
+    combineImages(future1.await(), future2.await()) // wait for both, combine, and return result
+}
+```
+
+Note, that this module should be used only for integration with existing Java APIs based on `CompletableFuture`. 
+Writing pure-Kotlin code that uses `CompletableFuture` is highly not recommended, since the resulting APIs based
+on the futures are quite error-prone. See the discussion on 
+[Asynchronous Programming Styles](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md#asynchronous-programming-styles)
+for details on general problems pertaining to any future-based API and keep in mind that `CompletableFuture` exposes
+a _blocking_ method 
+[get](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#get--) 
+that makes it especially bad choice for coroutine-based Kotlin code.
+
 # Package kotlinx.coroutines.experimental.future
 
 Additional libraries for JDK8 [CompletableFuture][java.util.concurrent.CompletableFuture].
@@ -24,10 +54,11 @@ Additional libraries for JDK8 [CompletableFuture][java.util.concurrent.Completab
 <!--- INDEX kotlinx.coroutines.experimental -->
 [CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
 <!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8 -->
-<!--- DOCS_ROOT kotlinx-coroutines-jdk8/target/dokka/kotlinx-coroutines-jdk8 -->
+<!--- DOCS_ROOT integration/kotlinx-coroutines-jdk8/target/dokka/kotlinx-coroutines-jdk8 -->
 <!--- INDEX kotlinx.coroutines.experimental.future -->
 [future]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/future.html
 [java.util.concurrent.CompletableFuture]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/java.util.concurrent.-completable-future/index.html
+[java.util.concurrent.CompletionStage.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/java.util.concurrent.-completion-stage/await.html
 [java.util.concurrent.CompletableFuture.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/java.util.concurrent.-completable-future/await.html
 [kotlinx.coroutines.experimental.Deferred.asCompletableFuture]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/kotlinx.coroutines.experimental.-deferred/as-completable-future.html
 <!--- END -->

integration/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt

@@ -18,9 +18,11 @@ package kotlinx.coroutines.experimental.future
 
 import kotlinx.coroutines.experimental.*
 import java.util.concurrent.CompletableFuture
+import java.util.concurrent.CompletionStage
 import kotlin.coroutines.experimental.Continuation
 import kotlin.coroutines.experimental.CoroutineContext
 import kotlin.coroutines.experimental.startCoroutine
+import kotlin.coroutines.experimental.suspendCoroutine
 
 /**
  * Starts new coroutine and returns its results an an implementation of [CompletableFuture].
@@ -44,16 +46,6 @@ public fun <T> future(context: CoroutineContext = CommonPool, block: suspend ()
     return future
 }
 
-
-/**
- * Converts this deferred value to the instance of [CompletableFuture].
- * The deferred value is cancelled when the resulting future is cancelled or otherwise completed.
- * @suppress: **Deprecated**: Renamed to [asCompletableFuture]
- */
-@Deprecated("Renamed to `asCompletableFuture`",
-    replaceWith = ReplaceWith("asCompletableFuture()"))
-public fun <T> Deferred<T>.toCompletableFuture(): CompletableFuture<T> = asCompletableFuture()
-
 /**
  * Converts this deferred value to the instance of [CompletableFuture].
  * The deferred value is cancelled when the resulting future is cancelled or otherwise completed.
@@ -71,16 +63,31 @@ public fun <T> Deferred<T>.asCompletableFuture(): CompletableFuture<T> {
     return future
 }
 
+/**
+ * Awaits for completion of the completion stage without blocking a thread.
+ *
+ * This suspending function is not cancellable, because there is no way to cancel a `CompletionStage`.
+ * Use `CompletableFuture.await()` for cancellation support.
+ */
+public suspend fun <T> CompletionStage<T>.await(): T = suspendCoroutine { cont: Continuation<T> ->
+    whenComplete { result, exception ->
+        if (exception == null) // the stage has been completed normally
+            cont.resume(result)
+        else // the stage has completed with an exception
+            cont.resumeWithException(exception)
+    }
+}
+
 /**
  * Awaits for completion of the future without blocking a thread.
  *
  * This suspending function is cancellable.
  * If the [Job] of the current coroutine is completed while this suspending function is waiting, this function
- * immediately resumes with [CancellationException] .
+ * cancels the `CompletableFuture` and immediately resumes with [CancellationException] .
  */
 public suspend fun <T> CompletableFuture<T>.await(): T {
-    if (isDone) {
-        // then only way to get unwrapped exception from the CompletableFuture...
+    if (isDone) { // fast path when CompletableFuture is already done (does not suspend)
+        // then only way to get unwrapped exception from the CompletableFuture is via whenComplete anyway
         var result: T? = null
         var exception: Throwable? = null
         whenComplete { r, e ->
@@ -90,6 +97,7 @@ public suspend fun <T> CompletableFuture<T>.await(): T {
         if (exception != null) throw exception!!
         return result as T
     }
+    // slow path -- suspend
     return suspendCancellableCoroutine { cont: CancellableContinuation<T> ->
         val completionFuture = whenComplete { result, exception ->
             if (exception == null) // the future has been completed normally
@@ -98,7 +106,6 @@ public suspend fun <T> CompletableFuture<T>.await(): T {
                 cont.resumeWithException(exception)
         }
         cont.cancelFutureOnCompletion(completionFuture)
-        Unit
     }
 }
 
@@ -108,3 +115,16 @@ private class CompletableFutureCoroutine<T>(
     override fun resume(value: T) { complete(value) }
     override fun resumeWithException(exception: Throwable) { completeExceptionally(exception) }
 }
+
+// --------------------------------------- DEPRECATED APIs ---------------------------------------
+// We keep it only for backwards compatibility with old versions of this integration library.
+// Do not copy when using this file an example for other integration.
+
+/**
+ * Converts this deferred value to the instance of [CompletableFuture].
+ * The deferred value is cancelled when the resulting future is cancelled or otherwise completed.
+ * @suppress: **Deprecated**: Renamed to [asCompletableFuture]
+ */
+@Deprecated("Renamed to `asCompletableFuture`",
+    replaceWith = ReplaceWith("asCompletableFuture()"))
+public fun <T> Deferred<T>.toCompletableFuture(): CompletableFuture<T> = asCompletableFuture()

integration/kotlinx-coroutines-jdk8/src/test/kotlin/kotlinx/coroutines/experimental/future/FutureTest.kt

@@ -23,6 +23,7 @@ import java.util.concurrent.ExecutionException
 import java.util.concurrent.atomic.AtomicInteger
 import kotlin.coroutines.experimental.CoroutineContext
 import org.junit.Assert.*
+import java.util.concurrent.CompletionStage
 
 class FutureTest {
     @Test
@@ -32,25 +33,34 @@ class FutureTest {
                 "O"
             }.await() + "K"
         }
-
         assertEquals("OK", future.get())
     }
 
     @Test
-    fun testWaitForCompletion() {
+    fun testWaitForFuture() {
         val toAwait = CompletableFuture<String>()
         val future = future {
             toAwait.await() + "K"
         }
-
         assertFalse(future.isDone)
         toAwait.complete("O")
+        assertEquals("OK", future.get())
+    }
 
+    @Test
+    fun testWaitForCompletionStage() {
+        val completable = CompletableFuture<String>()
+        val toAwait: CompletionStage<String> = completable
+        val future = future {
+            toAwait.await() + "K"
+        }
+        assertFalse(future.isDone)
+        completable.complete("O")
         assertEquals("OK", future.get())
     }
 
     @Test
-    fun testDoneFutureCompletedExceptionally() {
+    fun testDoneFutureExceptionally() {
         val toAwait = CompletableFuture<String>()
         toAwait.completeExceptionally(RuntimeException("O"))
         val future = future<String> {
@@ -63,6 +73,21 @@ class FutureTest {
         assertEquals("OK", future.get())
     }
 
+    @Test
+    fun testDoneCompletionStageExceptionally() {
+        val completable = CompletableFuture<String>()
+        val toAwait: CompletionStage<String> = completable
+        completable.completeExceptionally(RuntimeException("O"))
+        val future = future<String> {
+            try {
+                toAwait.await()
+            } catch (e: RuntimeException) {
+                e.message!!
+            } + "K"
+        }
+        assertEquals("OK", future.get())
+    }
+
     @Test
     fun testAwaitedFutureCompletedExceptionally() {
         val toAwait = CompletableFuture<String>()
@@ -73,10 +98,24 @@ class FutureTest {
                 e.message!!
             } + "K"
         }
-
         assertFalse(future.isDone)
         toAwait.completeExceptionally(RuntimeException("O"))
+        assertEquals("OK", future.get())
+    }
 
+    @Test
+    fun testAwaitedCompletionStageCompletedExceptionally() {
+        val completable = CompletableFuture<String>()
+        val toAwait: CompletionStage<String> = completable
+        val future = future<String> {
+            try {
+                toAwait.await()
+            } catch (e: RuntimeException) {
+                e.message!!
+            } + "K"
+        }
+        assertFalse(future.isDone)
+        completable.completeExceptionally(RuntimeException("O"))
         assertEquals("OK", future.get())
     }
 
@@ -88,7 +127,6 @@ class FutureTest {
             }
             CompletableFuture.supplyAsync { "fail" }.await()
         }
-
         try {
             future.get()
             fail("'get' should've throw an exception")
@@ -101,32 +139,26 @@ class FutureTest {
     @Test
     fun testContinuationWrapped() {
         val depth = AtomicInteger()
-
         val future = future(wrapContinuation {
             depth.andIncrement
             it()
             depth.andDecrement
         }) {
             assertEquals("Part before first suspension must be wrapped", 1, depth.get())
-
             val result =
                     CompletableFuture.supplyAsync {
                         while (depth.get() > 0) ;
                         assertEquals("Part inside suspension point should not be wrapped", 0, depth.get())
                         "OK"
                     }.await()
-
             assertEquals("Part after first suspension should be wrapped", 1, depth.get())
-
             CompletableFuture.supplyAsync {
                 while (depth.get() > 0) ;
                 assertEquals("Part inside suspension point should not be wrapped", 0, depth.get())
                 "ignored"
             }.await()
-
             result
         }
-
         assertEquals("OK", future.get())
     }