• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# kotlinx.coroutines
2
3[![official JetBrains project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
4[![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](https://www.apache.org/licenses/LICENSE-2.0)
5[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=1.4.1) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.4.1)
6[![Kotlin](https://img.shields.io/badge/kotlin-1.4.0-blue.svg?logo=kotlin)](http://kotlinlang.org)
7[![Slack channel](https://img.shields.io/badge/chat-slack-green.svg?logo=slack)](https://kotlinlang.slack.com/messages/coroutines/)
8
9Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
10This is a companion version for Kotlin `1.4.0` release.
11
12```kotlin
13suspend fun main() = coroutineScope {
14    launch {
15       delay(1000)
16       println("Kotlin Coroutines World!")
17    }
18    println("Hello")
19}
20```
21
22> Play with coroutines online [here](https://pl.kotl.in/hG_tKbid_)
23
24## Modules
25
26* [core](kotlinx-coroutines-core/README.md) — common coroutines across all platforms:
27  * [launch] and [async] coroutine builders returning [Job] and [Deferred] light-weight futures with cancellation support;
28  * [Dispatchers] object with [Main][Dispatchers.Main] dispatcher for Android/Swing/JavaFx, and [Default][Dispatchers.Default] dispatcher for background coroutines;
29  * [delay] and [yield] top-level suspending functions;
30  * [Flow] — cold asynchronous stream with [flow][_flow] builder and comprehensive operator set ([filter], [map], etc);
31  * [Channel], [Mutex], and [Semaphore] communication and synchronization primitives;
32  * [coroutineScope][_coroutineScope], [supervisorScope][_supervisorScope], [withContext], and [withTimeout] scope builders;
33  * [MainScope()] for Android and UI applications;
34  * [SupervisorJob()] and [CoroutineExceptionHandler] for supervision of coroutines hierarchies;
35  * [select] expression support and more.
36* [core/jvm](kotlinx-coroutines-core/jvm/) — additional core features available on Kotlin/JVM:
37  * [Dispatchers.IO] dispatcher for blocking coroutines;
38  * [Executor.asCoroutineDispatcher] extension, custom thread pools, and more.
39* [core/js](kotlinx-coroutines-core/js/) — additional core features available on Kotlin/JS:
40  * Integration with `Promise` via [Promise.await] and [promise] builder;
41  * Integration with `Window` via [Window.asCoroutineDispatcher], etc.
42* [test](kotlinx-coroutines-test/README.md) — test utilities for coroutines:
43  * [Dispatchers.setMain] to override [Dispatchers.Main] in tests;
44  * [TestCoroutineScope] to test suspending functions and coroutines.
45* [debug](kotlinx-coroutines-debug/README.md) — debug utilities for coroutines:
46  * [DebugProbes] API to probe, keep track of, print and dump active coroutines;
47  * [CoroutinesTimeout] test rule to automatically dump coroutines on test timeout.
48* [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:
49  * Reactive Streams ([Publisher.collect], [Publisher.awaitSingle], [kotlinx.coroutines.reactive.publish], etc),
50  * Flow (JDK 9) (the same interface as for Reactive Streams),
51  * RxJava 2.x ([rxFlowable], [rxSingle], etc), and
52  * RxJava 3.x ([rxFlowable], [rxSingle], etc), and
53  * Project Reactor ([flux], [mono], etc).
54* [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:
55  * Android, JavaFX, and Swing.
56* [integration](integration/README.md) — modules that provide integration with various asynchronous callback- and future-based libraries:
57  * JDK8 [CompletionStage.await], Guava [ListenableFuture.await], and Google Play Services [Task.await];
58  * SLF4J MDC integration via [MDCContext].
59
60## Documentation
61
62* Presentations and videos:
63  * [Introduction to Coroutines](https://www.youtube.com/watch?v=_hfBv0a09Jc) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/introduction-to-coroutines-kotlinconf-2017))
64  * [Deep dive into Coroutines](https://www.youtube.com/watch?v=YrrUCSi72E8) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/deep-dive-into-coroutines-on-jvm-kotlinconf-2017))
65  * [Kotlin Coroutines in Practice](https://www.youtube.com/watch?v=a3agLJQ6vt8) (Roman Elizarov at KotlinConf 2018, [slides](https://www.slideshare.net/elizarov/kotlin-coroutines-in-practice-kotlinconf-2018))
66* Guides and manuals:
67  * [Guide to kotlinx.coroutines by example](https://kotlinlang.org/docs/reference/coroutines/coroutines-guide.html) (**read it first**)
68  * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
69  * [Debugging capabilities in kotlinx.coroutines](docs/debugging.md)
70* [Compatibility policy and experimental annotations](docs/compatibility.md)
71* [Change log for kotlinx.coroutines](CHANGES.md)
72* [Coroutines design document (KEEP)](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md)
73* [Full kotlinx.coroutines API reference](https://kotlin.github.io/kotlinx.coroutines)
74
75## Using in your projects
76
77The libraries are published to [kotlinx](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines) bintray repository,
78linked to [JCenter](https://bintray.com/bintray/jcenter?filterByPkgName=kotlinx.coroutines) and
79pushed to [Maven Central](https://search.maven.org/#search%7Cga%7C1%7Cg%3Aorg.jetbrains.kotlinx%20a%3Akotlinx-coroutines*).
80
81### Maven
82
83Add dependencies (you can also add other modules that you need):
84
85```xml
86<dependency>
87    <groupId>org.jetbrains.kotlinx</groupId>
88    <artifactId>kotlinx-coroutines-core</artifactId>
89    <version>1.4.1</version>
90</dependency>
91```
92
93And make sure that you use the latest Kotlin version:
94
95```xml
96<properties>
97    <kotlin.version>1.4.0</kotlin.version>
98</properties>
99```
100
101### Gradle
102
103Add dependencies (you can also add other modules that you need):
104
105```groovy
106dependencies {
107    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1'
108}
109```
110
111And make sure that you use the latest Kotlin version:
112
113```groovy
114buildscript {
115    ext.kotlin_version = '1.4.0'
116}
117```
118
119Make sure that you have either `jcenter()` or `mavenCentral()` in the list of repositories:
120
121```
122repository {
123    jcenter()
124}
125```
126
127### Gradle Kotlin DSL
128
129Add dependencies (you can also add other modules that you need):
130
131```groovy
132dependencies {
133    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1")
134}
135```
136
137And make sure that you use the latest Kotlin version:
138
139```groovy
140plugins {
141    kotlin("jvm") version "1.4.0"
142}
143```
144
145Make sure that you have either `jcenter()` or `mavenCentral()` in the list of repositories.
146
147### Multiplatform
148
149Core modules of `kotlinx.coroutines` are also available for
150[Kotlin/JS](#js) and [Kotlin/Native](#native).
151In common code that should get compiled for different platforms, you can add dependency to `kotlinx-coroutines-core` right to the `commonMain` source set:
152```groovy
153commonMain {
154    dependencies {
155        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1")
156    }
157}
158```
159
160### Android
161
162Add [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android)
163module as dependency when using `kotlinx.coroutines` on Android:
164
165```groovy
166implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.1'
167```
168
169This gives you access to Android [Dispatchers.Main]
170coroutine dispatcher and also makes sure that in case of crashed coroutine with unhandled exception this
171exception is logged before crashing Android application, similarly to the way uncaught exceptions in
172threads are handled by Android runtime.
173
174#### R8 and ProGuard
175
176R8 and ProGuard rules are bundled into the [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android) module.
177For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-android/README.md#optimization).
178
179#### Avoiding including the debug infrastructure in the resulting APK
180
181The `kotlinx-coroutines-core` artifact contains a resource file that is not required for the coroutines to operate
182normally and is only used by the debugger. To exclude it at no loss of functionality, add the following snippet to the
183`android` block in your gradle file for the application subproject:
184```groovy
185packagingOptions {
186  exclude "DebugProbesKt.bin"
187}
188```
189
190### JS
191
192[Kotlin/JS](https://kotlinlang.org/docs/reference/js-overview.html) version of `kotlinx.coroutines` is published as
193[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.4.1/jar)
194(follow the link to get the dependency declaration snippet).
195
196You can also use [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM.
197
198### Native
199
200[Kotlin/Native](https://kotlinlang.org/docs/reference/native-overview.html) version of `kotlinx.coroutines` is published as
201[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.4.1/jar)
202(follow the link to get the dependency declaration snippet).
203
204Only single-threaded code (JS-style) on Kotlin/Native is currently supported.
205Kotlin/Native supports only Gradle version 4.10 and you need to enable Gradle metadata in your
206`settings.gradle` file:
207
208```groovy
209enableFeaturePreview('GRADLE_METADATA')
210```
211
212Since Kotlin/Native does not generally provide binary compatibility between versions,
213you should use the same version of Kotlin/Native compiler as was used to build `kotlinx.coroutines`.
214
215## Building and Contributing
216
217See [Contributing Guidelines](CONTRIBUTING.md).
218
219<!--- MODULE kotlinx-coroutines-core -->
220<!--- INDEX kotlinx.coroutines -->
221[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
222[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html
223[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
224[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
225[Dispatchers]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/index.html
226[Dispatchers.Main]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-main.html
227[Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
228[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/delay.html
229[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/yield.html
230[_coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html
231[_supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html
232[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html
233[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html
234[MainScope()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-main-scope.html
235[SupervisorJob()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-supervisor-job.html
236[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-exception-handler/index.html
237[Dispatchers.IO]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html
238[Executor.asCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/java.util.concurrent.-executor/as-coroutine-dispatcher.html
239[Promise.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/kotlin.js.-promise/await.html
240[promise]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/promise.html
241[Window.asCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/org.w3c.dom.-window/as-coroutine-dispatcher.html
242<!--- INDEX kotlinx.coroutines.flow -->
243[Flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html
244[_flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html
245[filter]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/filter.html
246[map]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/map.html
247<!--- INDEX kotlinx.coroutines.channels -->
248[Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/index.html
249<!--- INDEX kotlinx.coroutines.selects -->
250[select]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.selects/select.html
251<!--- INDEX kotlinx.coroutines.sync -->
252[Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/index.html
253[Semaphore]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-semaphore/index.html
254<!--- MODULE kotlinx-coroutines-test -->
255<!--- INDEX kotlinx.coroutines.test -->
256[Dispatchers.setMain]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/kotlinx.coroutines.-dispatchers/set-main.html
257[TestCoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-scope/index.html
258<!--- MODULE kotlinx-coroutines-debug -->
259<!--- INDEX kotlinx.coroutines.debug -->
260[DebugProbes]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/index.html
261<!--- INDEX kotlinx.coroutines.debug.junit4 -->
262[CoroutinesTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug.junit4/-coroutines-timeout/index.html
263<!--- MODULE kotlinx-coroutines-slf4j -->
264<!--- INDEX kotlinx.coroutines.slf4j -->
265[MDCContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-slf4j/kotlinx.coroutines.slf4j/-m-d-c-context/index.html
266<!--- MODULE kotlinx-coroutines-jdk8 -->
267<!--- INDEX kotlinx.coroutines.future -->
268[CompletionStage.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/java.util.concurrent.-completion-stage/await.html
269<!--- MODULE kotlinx-coroutines-guava -->
270<!--- INDEX kotlinx.coroutines.guava -->
271[ListenableFuture.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-guava/kotlinx.coroutines.guava/com.google.common.util.concurrent.-listenable-future/await.html
272<!--- MODULE kotlinx-coroutines-play-services -->
273<!--- INDEX kotlinx.coroutines.tasks -->
274[Task.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-play-services/kotlinx.coroutines.tasks/com.google.android.gms.tasks.-task/await.html
275<!--- MODULE kotlinx-coroutines-reactive -->
276<!--- INDEX kotlinx.coroutines.reactive -->
277[Publisher.collect]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/collect.html
278[Publisher.awaitSingle]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/await-single.html
279[kotlinx.coroutines.reactive.publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
280<!--- MODULE kotlinx-coroutines-rx2 -->
281<!--- INDEX kotlinx.coroutines.rx2 -->
282[rxFlowable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.rx2/rx-flowable.html
283[rxSingle]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.rx2/rx-single.html
284<!--- MODULE kotlinx-coroutines-rx2 -->
285<!--- INDEX kotlinx.coroutines.rx2 -->
286<!--- MODULE kotlinx-coroutines-reactor -->
287<!--- INDEX kotlinx.coroutines.reactor -->
288[flux]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor/kotlinx.coroutines.reactor/flux.html
289[mono]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor/kotlinx.coroutines.reactor/mono.html
290<!--- END -->
291