1
1
# 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)
80
2
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)
95
37
96
38
## Using in your projects
97
39
98
40
> Note that these libraries are experimental and are subject to change.
99
41
100
42
The libraries are published to [ kotlin-eap-1.1] ( https://bintray.com/kotlin/kotlin-eap-1.1/kotlinx.coroutines ) bintray repository.
101
43
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
103
45
require kotlin runtime of the same version as a dependency, which can be obtained from the same repository.
104
46
105
-
106
47
### Maven
107
48
108
49
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):
119
60
</repository >
120
61
```
121
62
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):
123
64
124
65
``` xml
125
66
<dependency >
126
67
<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 >
139
70
</dependency >
140
71
```
141
72
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
+
142
81
### Gradle
143
82
144
83
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 {
151
90
}
152
91
```
153
92
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):
155
94
156
95
``` 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'
160
97
```
161
98
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:
163
100
101
+ ``` groovy
102
+ buildscript {
103
+ ext.kotlin_version = '1.1.0-beta-17'
104
+ }
105
+ ```
0 commit comments