Skip to content

Commit b75514d

Browse files
authored
Merge pull request #21 from elizarov/0.3-beta
New implementation for Kotlin 1.1.0-beta-17
2 parents 0ccf2fd + 1dccb67 commit b75514d

File tree

53 files changed

+2365
-744
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+2365
-744
lines changed

README.md

Lines changed: 54 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,49 @@
11
# kotlinx.coroutines
2-
Three libraries built upon Kotlin coroutines:
3-
* `kotlinx-coroutines-async` with convenient interfaces/wrappers to commonly
4-
used asynchronous API shipped with standard JDK, namely promise-like `CompletableFuture`
5-
and asynchronous channels from `java.nio` package
6-
* `kotlinx-coroutines-generate` provides ability to create `Sequence` objects
7-
generated by coroutine body containing `yield` suspension points
8-
* `kotlinx-coroutines-rx` allows to use `Observable` objects from
9-
[RxJava](https://github.com/ReactiveX/RxJava) inside a coroutine body to suspend on them
10-
11-
## Examples
12-
### Async
13-
14-
```kotlin
15-
import kotlinx.coroutines.async
16-
import java.util.concurrent.CompletableFuture
17-
18-
private fun startLongAsyncOperation(v: Int) =
19-
CompletableFuture.supplyAsync {
20-
Thread.sleep(1000)
21-
"Result: $v"
22-
}
23-
24-
fun main(args: Array<String>) {
25-
val future = async {
26-
(1..5).map {
27-
startLongAsyncOperation(it).await()
28-
}.joinToString("\n")
29-
}
30-
31-
println(future.get())
32-
}
33-
```
34-
35-
Bear in mind that `async` library actively uses `CompletableFuture` from JDK 8, so
36-
it will not work with earlier versions.
37-
38-
### Generate
39-
40-
```kotlin
41-
import kotlinx.coroutines.generate
42-
43-
fun main(args: Array<String>) {
44-
val sequence = generate {
45-
for (i in 1..5) {
46-
yield(i)
47-
}
48-
}
49-
50-
println(sequence.joinToString(" "))
51-
}
52-
```
53-
54-
### RxJava
55-
56-
```kotlin
57-
import kotlinx.coroutines.asyncRx
58-
import retrofit2.Retrofit
59-
import retrofit2.adapter.rxjava.RxJavaCallAdapterFactory
60-
import retrofit2.converter.gson.GsonConverterFactory
61-
import retrofit2.http.GET
62-
import retrofit2.http.Path
63-
import rx.Observable
64-
65-
interface GitHub {
66-
@GET("orgs/{user}/repos")
67-
fun orgRepos(@Path("user") user: String): Observable<List<Repo>>
68-
}
69-
70-
data class Repo(val name: String)
71-
72-
fun main(args: Array<String>) {
73-
val retrofit = Retrofit.Builder().apply {
74-
baseUrl("https://api.github.com")
75-
addConverterFactory(GsonConverterFactory.create())
76-
addCallAdapterFactory(RxJavaCallAdapterFactory.create())
77-
}.build()
78-
79-
val github = retrofit.create(GitHub::class.java)
802

81-
asyncRx {
82-
for (org in listOf("Kotlin", "ReactiveX")) {
83-
// `awaitSingle()` call here is a suspension point,
84-
// i.e. coroutine's code stops on it until request is not completed
85-
val repos = github.orgRepos(org).take(5).awaitSingle().joinToString()
86-
87-
println("$org: $repos")
88-
}
89-
}
90-
}
91-
```
92-
93-
For more examples you can look at `kotlinx-coroutines-async-example-ui`
94-
and `kotlinx-coroutines-rx-example` samples projects or in tests directories.
3+
Library support for Kotlin coroutines. This is a companion version for Kotlin 1.1.0-beta-17 release.
4+
It contains worked-out implementation of coroutine builders, suspending functions, and contexts that are
5+
used as examples in
6+
[Kotlin coroutines design document](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md)
7+
8+
It consists of the following modules:
9+
10+
* `kotlinx-coroutines-core` module with core primitives to work with coroutines. It is designed to work on any JDK6+ and Android
11+
and contains the following main pieces:
12+
* `lanunch(context) { ... }` to start a coroutine in the given context.
13+
* `run(context) { ... }` to switch to a different context inside a coroutine.
14+
* `runBlocking(context) { ... }` to use asynchronous Kotlin APIs from a thread-blocking code.
15+
* `defer(context) { ... }` to get a deferred result of coroutine execution in a non-blocking way.
16+
* `delay(...)` for a non-blocking sleep in coroutines.
17+
* `Here` and `CommonPool` contexts.
18+
* `newSingleThreadContext(...)` and `newFixedThreadPoolContext(...)` functions.
19+
* Cancellation support with `Job` interface and `suspendCancellableCoroutine` helper function.
20+
* Debugging facilities for coroutines (run JVM with `-ea` or `-Dkotlinx.coroutines.debug` options) and
21+
`newCoroutineContext(context)` function to write user-defined coroutine builders that work with these
22+
debugging facilities.
23+
24+
* `kotlinx-coroutines-jdk8` module with additional libraries for JDK8 (or Android API level 24).
25+
* `future { ... }` coroutine builder that returns `CompletableFuture` and works in `CommonPool` context by default.
26+
* `.await()` suspending function for `CompletableFuture`.
27+
28+
* `kotlinx-coroutines-nio` module with extensions for asynchronous IO on JDK7+ (does not support cancellation yet).
29+
30+
* `kotlinx-coroutines-swing` module with `Swing` context for Swing UI applications.
31+
32+
* `kotlinx-coroutines-javafx` module with `JavaFx` context for JavaFX UI applications.
33+
34+
* `kotlinx-coroutines-rx` module with utilities to build `Observable` objects from
35+
[RxJava](https://github.com/ReactiveX/RxJava) with imperative coroutines and consume their values
36+
from inside coroutines. It is in very basic form now (example-only, not even close to production use)
9537

9638
## Using in your projects
9739

9840
> Note that these libraries are experimental and are subject to change.
9941
10042
The libraries are published to [kotlin-eap-1.1](https://bintray.com/kotlin/kotlin-eap-1.1/kotlinx.coroutines) bintray repository.
10143

102-
These libraries require kotlin compiler version to be at least `1.1-M04` and
44+
These libraries require kotlin compiler version to be at least `1.1-Beta` and
10345
require kotlin runtime of the same version as a dependency, which can be obtained from the same repository.
10446

105-
10647
### Maven
10748

10849
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):
11960
</repository>
12061
```
12162

122-
Add dependencies (you can add just those of them that you need):
63+
Add dependencies (you can also add other modules that you need):
12364

12465
```xml
12566
<dependency>
12667
<groupId>org.jetbrains.kotlinx</groupId>
127-
<artifactId>kotlinx-coroutines-generate</artifactId>
128-
<version>0.2-beta</version>
129-
</dependency>
130-
<dependency>
131-
<groupId>org.jetbrains.kotlinx</groupId>
132-
<artifactId>kotlinx-coroutines-async</artifactId>
133-
<version>0.2-beta</version>
134-
</dependency>
135-
<dependency>
136-
<groupId>org.jetbrains.kotlinx</groupId>
137-
<artifactId>kotlinx-coroutines-rx</artifactId>
138-
<version>0.2-beta</version>
68+
<artifactId>kotlinx-coroutines-core</artifactId>
69+
<version>0.3-beta</version>
13970
</dependency>
14071
```
14172

73+
And make sure that you use the right Kotlin version:
74+
75+
```xml
76+
<properties>
77+
<kotlin.version>1.1.0-beta-17</kotlin.version>
78+
</properties>
79+
```
80+
14281
### Gradle
14382

14483
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 {
15190
}
15291
```
15392

154-
Add dependencies (you can add just those of them that you need):
93+
Add dependencies (you can also add other modules that you need):
15594

15695
```groovy
157-
compile 'org.jetbrains.kotlinx:kotlinx-coroutines-generate:0.2-beta'
158-
compile 'org.jetbrains.kotlinx:kotlinx-coroutines-async:0.2-beta'
159-
compile 'org.jetbrains.kotlinx:kotlinx-coroutines-rx:0.2-beta'
96+
compile 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.3-beta'
16097
```
16198

162-
*NB:* As `async` library is built upon `CompletableFuture` it requires JDK 8 (24 Android API level)
99+
And make sure that you use the right Kotlin version:
163100

101+
```groovy
102+
buildscript {
103+
ext.kotlin_version = '1.1.0-beta-17'
104+
}
105+
```

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

Lines changed: 0 additions & 167 deletions
This file was deleted.

kotlinx-coroutines-generate/pom.xml renamed to kotlinx-coroutines-core/pom.xml

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,16 @@
66
<parent>
77
<groupId>org.jetbrains.kotlinx</groupId>
88
<artifactId>kotlinx-coroutines</artifactId>
9-
<version>0.1-SNAPSHOT</version>
9+
<version>0.3-beta-SNAPSHOT</version>
1010
</parent>
1111

12-
<artifactId>kotlinx-coroutines-generate</artifactId>
12+
<artifactId>kotlinx-coroutines-core</artifactId>
1313
<packaging>jar</packaging>
1414

15-
<name>Kotlin coroutine-based yield/generate library</name>
15+
<name>Kotlin coroutines core library</name>
1616

1717
<build>
1818
<sourceDirectory>src/main/kotlin</sourceDirectory>
1919
<testSourceDirectory>src/test/kotlin</testSourceDirectory>
2020
</build>
21-
2221
</project>

0 commit comments

Comments
 (0)