Merge pull request #21 from elizarov/0.3-beta

New implementation for Kotlin 1.1.0-beta-17

Author: elizarov

README.md

@@ -1,108 +1,49 @@
 # kotlinx.coroutines
-Three libraries built upon Kotlin coroutines:
-* `kotlinx-coroutines-async` with convenient interfaces/wrappers to commonly
-used asynchronous API shipped with standard JDK, namely promise-like `CompletableFuture`
-and asynchronous channels from `java.nio` package
-* `kotlinx-coroutines-generate` provides ability to create `Sequence` objects
-generated by coroutine body containing `yield` suspension points
-* `kotlinx-coroutines-rx` allows to use `Observable` objects from
-[RxJava](https://github.com/ReactiveX/RxJava) inside a coroutine body to suspend on them
-
-## Examples
-### Async
-
-```kotlin
-import kotlinx.coroutines.async
-import java.util.concurrent.CompletableFuture
-
-private fun startLongAsyncOperation(v: Int) =
-        CompletableFuture.supplyAsync {
-            Thread.sleep(1000)
-            "Result: $v"
-        }
-
-fun main(args: Array<String>) {
-    val future = async {
-        (1..5).map {
-            startLongAsyncOperation(it).await()
-        }.joinToString("\n")
-    }
-
-    println(future.get())
-}
-```
-
-Bear in mind that `async` library actively uses `CompletableFuture` from JDK 8, so
-it will not work with earlier versions.
-
-### Generate
-
-```kotlin
-import kotlinx.coroutines.generate
-
-fun main(args: Array<String>) {
-    val sequence = generate {
-        for (i in 1..5) {
-            yield(i)
-        }
-    }
-
-    println(sequence.joinToString(" "))
-}
-```
-
-### RxJava
-
-```kotlin
-import kotlinx.coroutines.asyncRx
-import retrofit2.Retrofit
-import retrofit2.adapter.rxjava.RxJavaCallAdapterFactory
-import retrofit2.converter.gson.GsonConverterFactory
-import retrofit2.http.GET
-import retrofit2.http.Path
-import rx.Observable
-
-interface GitHub {
-    @GET("orgs/{user}/repos")
-    fun orgRepos(@Path("user") user: String): Observable<List<Repo>>
-}
-
-data class Repo(val name: String)
-
-fun main(args: Array<String>) {
-    val retrofit = Retrofit.Builder().apply {
-        baseUrl("https://api.github.com")
-        addConverterFactory(GsonConverterFactory.create())
-        addCallAdapterFactory(RxJavaCallAdapterFactory.create())
-    }.build()
-
-    val github = retrofit.create(GitHub::class.java)
 
-    asyncRx {
-        for (org in listOf("Kotlin", "ReactiveX")) {
-            // `awaitSingle()` call here is a suspension point,
-            // i.e. coroutine's code stops on it until request is not completed
-            val repos = github.orgRepos(org).take(5).awaitSingle().joinToString()
-
-            println("$org: $repos")
-        }
-    }
-}
-```
-
-For more examples you can look at `kotlinx-coroutines-async-example-ui`
-and `kotlinx-coroutines-rx-example` samples projects or in tests directories.
+Library support for Kotlin coroutines. This is a companion version for Kotlin 1.1.0-beta-17 release. 
+It contains worked-out implementation of coroutine builders, suspending functions, and contexts that are
+used as examples in 
+[Kotlin coroutines design document](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md)
+ 
+It consists of the following modules:
+
+* `kotlinx-coroutines-core` module with core primitives to work with coroutines. It is designed to work on any JDK6+ and Android
+and contains the following main pieces:
+  * `lanunch(context) { ... }` to start a coroutine in the given context.
+  * `run(context) { ... }` to switch to a different context inside a coroutine.
+  * `runBlocking(context) { ... }` to use asynchronous Kotlin APIs from a thread-blocking code.  
+  * `defer(context) { ... }` to get a deferred result of coroutine execution in a non-blocking way.
+  * `delay(...)` for a non-blocking sleep in coroutines.
+  * `Here` and `CommonPool` contexts.
+  * `newSingleThreadContext(...)` and `newFixedThreadPoolContext(...)` functions.
+  * Cancellation support with `Job` interface and `suspendCancellableCoroutine` helper function.
+  * Debugging facilities for coroutines (run JVM with `-ea` or `-Dkotlinx.coroutines.debug` options) and
+    `newCoroutineContext(context)` function to write user-defined coroutine builders that work with these
+     debugging facilities.
+ 
+* `kotlinx-coroutines-jdk8` module with additional libraries for JDK8 (or Android API level 24).
+  * `future { ... }` coroutine builder that returns `CompletableFuture` and works in `CommonPool` context by default.
+  * `.await()` suspending function for `CompletableFuture`.
+
+* `kotlinx-coroutines-nio` module with extensions for asynchronous IO on JDK7+ (does not support cancellation yet).
+
+* `kotlinx-coroutines-swing` module with `Swing` context for Swing UI applications.
+
+* `kotlinx-coroutines-javafx` module with `JavaFx` context for JavaFX UI applications.
+
+* `kotlinx-coroutines-rx` module with utilities to build `Observable` objects from
+[RxJava](https://github.com/ReactiveX/RxJava) with imperative coroutines and consume their values 
+from inside coroutines. It is in very basic form now (example-only, not even close to production use)
 
 ## Using in your projects
 
 > Note that these libraries are experimental and are subject to change.
 
 The libraries are published to [kotlin-eap-1.1](https://bintray.com/kotlin/kotlin-eap-1.1/kotlinx.coroutines) bintray repository.
 
-These libraries require kotlin compiler version to be at least `1.1-M04` and 
+These libraries require kotlin compiler version to be at least `1.1-Beta` and 
 require kotlin runtime of the same version as a dependency, which can be obtained from the same repository.
 
-
 ### Maven
 
 Add the bintray repository to `<repositories>` section (and also add `pluginRepository` to `<pluginRepositories>`,
@@ -119,26 +60,24 @@ if you're willing to get `kotlin-maven-plugin` from there):
 </repository>
 ```
 
-Add dependencies (you can add just those of them that you need):
+Add dependencies (you can also add other modules that you need):
 
 ```xml
 <dependency>
     <groupId>org.jetbrains.kotlinx</groupId>
-    <artifactId>kotlinx-coroutines-generate</artifactId>
-    <version>0.2-beta</version>
-</dependency>
-<dependency>
-    <groupId>org.jetbrains.kotlinx</groupId>
-    <artifactId>kotlinx-coroutines-async</artifactId>
-    <version>0.2-beta</version>
-</dependency>
-<dependency>
-    <groupId>org.jetbrains.kotlinx</groupId>
-    <artifactId>kotlinx-coroutines-rx</artifactId>
-    <version>0.2-beta</version>
+    <artifactId>kotlinx-coroutines-core</artifactId>
+    <version>0.3-beta</version>
 </dependency>
 ```
 
+And make sure that you use the right Kotlin version:
+
+```xml
+<properties>
+    <kotlin.version>1.1.0-beta-17</kotlin.version>
+</properties>
+```
+
 ### Gradle
 
 Add the bintray repository (and also add it to `buildScript` section, if you're willing to get `kotlin-gradle-plugin` from there):
@@ -151,13 +90,16 @@ repositories {
 }
 ```
 
-Add dependencies (you can add just those of them that you need):
+Add dependencies (you can also add other modules that you need):
 
 ```groovy
-compile 'org.jetbrains.kotlinx:kotlinx-coroutines-generate:0.2-beta'
-compile 'org.jetbrains.kotlinx:kotlinx-coroutines-async:0.2-beta'
-compile 'org.jetbrains.kotlinx:kotlinx-coroutines-rx:0.2-beta'
+compile 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.3-beta'
 ```
 
-*NB:* As `async` library is built upon `CompletableFuture` it requires JDK 8 (24 Android API level)
+And make sure that you use the right Kotlin version:
 
+```groovy
+buildscript {
+    ext.kotlin_version = '1.1.0-beta-17'
+}
+```

kotlinx-coroutines-async/src/main/kotlin/async.kt

@@ -6,17 +6,16 @@
     <parent>
         <groupId>org.jetbrains.kotlinx</groupId>
         <artifactId>kotlinx-coroutines</artifactId>
-        <version>0.1-SNAPSHOT</version>
+        <version>0.3-beta-SNAPSHOT</version>
     </parent>
 
-    <artifactId>kotlinx-coroutines-generate</artifactId>
+    <artifactId>kotlinx-coroutines-core</artifactId>
     <packaging>jar</packaging>
 
-    <name>Kotlin coroutine-based yield/generate library</name>
+    <name>Kotlin coroutines core library</name>
 
     <build>
         <sourceDirectory>src/main/kotlin</sourceDirectory>
         <testSourceDirectory>src/test/kotlin</testSourceDirectory>
     </build>
-
 </project>