1# Module kotlinx-coroutines-jdk8 2 3Integration with JDK8 [CompletableFuture] (Android API level 24). 4 5Coroutine builders: 6 7| **Name** | **Result** | **Scope** | **Description** 8| -------- | ------------------- | ---------------- | --------------- 9| [future] | [CompletableFuture] | [CoroutineScope] | Returns a single value with the future result 10 11Extension functions: 12 13| **Name** | **Description** 14| -------- | --------------- 15| [CompletionStage.await][java.util.concurrent.CompletionStage.await] | Awaits for completion of the completion stage 16| [CompletionStage.asDeferred][java.util.concurrent.CompletionStage.asDeferred] | Converts completion stage to an instance of [Deferred] 17| [Deferred.asCompletableFuture][kotlinx.coroutines.Deferred.asCompletableFuture] | Converts a deferred value to the future 18 19## Example 20 21Given the following functions defined in some Java API: 22 23```java 24public CompletableFuture<Image> loadImageAsync(String name); // starts async image loading 25public Image combineImages(Image image1, Image image2); // synchronously combines two images using some algorithm 26``` 27 28We can consume this API from Kotlin coroutine to load two images and combine then asynchronously. 29The resulting function returns `CompletableFuture<Image>` for ease of use back from Java. 30 31```kotlin 32fun combineImagesAsync(name1: String, name2: String): CompletableFuture<Image> = future { 33 val future1 = loadImageAsync(name1) // start loading first image 34 val future2 = loadImageAsync(name2) // start loading second image 35 combineImages(future1.await(), future2.await()) // wait for both, combine, and return result 36} 37``` 38 39Note that this module should be used only for integration with existing Java APIs based on `CompletableFuture`. 40Writing pure-Kotlin code that uses `CompletableFuture` is highly not recommended, since the resulting APIs based 41on the futures are quite error-prone. See the discussion on 42[Asynchronous Programming Styles](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md#asynchronous-programming-styles) 43for details on general problems pertaining to any future-based API and keep in mind that `CompletableFuture` exposes 44a _blocking_ method 45[get](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#get--) 46that makes it especially bad choice for coroutine-based Kotlin code. 47 48# Package kotlinx.coroutines.future 49 50Integration with JDK8 [CompletableFuture] (Android API level 24). 51 52[CompletableFuture]: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html 53 54<!--- MODULE kotlinx-coroutines-core --> 55<!--- INDEX kotlinx.coroutines --> 56 57[CoroutineScope]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html 58[Deferred]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html 59 60<!--- MODULE kotlinx-coroutines-jdk8 --> 61<!--- INDEX kotlinx.coroutines.future --> 62 63[future]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/future.html 64[java.util.concurrent.CompletionStage.await]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/await.html 65[java.util.concurrent.CompletionStage.asDeferred]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/as-deferred.html 66[kotlinx.coroutines.Deferred.asCompletableFuture]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/as-completable-future.html 67 68<!--- END --> 69