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