diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 127 |
1 files changed, 48 insertions, 79 deletions
@@ -2,12 +2,12 @@ [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [](https://www.apache.org/licenses/LICENSE-2.0) -[ ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.4.3) -[](http://kotlinlang.org) +[ ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.4.1) +[](http://kotlinlang.org) [](https://kotlinlang.slack.com/messages/coroutines/) Library support for Kotlin coroutines with [multiplatform](#multiplatform) support. -This is a companion version for Kotlin `1.4.30` release. +This is a companion version for Kotlin `1.4.0` release. ```kotlin suspend fun main() = coroutineScope { @@ -45,7 +45,6 @@ suspend fun main() = coroutineScope { * [debug](kotlinx-coroutines-debug/README.md) — debug utilities for coroutines: * [DebugProbes] API to probe, keep track of, print and dump active coroutines; * [CoroutinesTimeout] test rule to automatically dump coroutines on test timeout. - * Automatic integration with [BlockHound](https://github.com/reactor/BlockHound). * [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries: * Reactive Streams ([Publisher.collect], [Publisher.awaitSingle], [kotlinx.coroutines.reactive.publish], etc), * Flow (JDK 9) (the same interface as for Reactive Streams), @@ -65,10 +64,10 @@ suspend fun main() = coroutineScope { * [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)) * [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)) * Guides and manuals: - * [Guide to kotlinx.coroutines by example](https://kotlinlang.org/docs/coroutines-guide.html) (**read it first**) + * [Guide to kotlinx.coroutines by example](https://kotlinlang.org/docs/reference/coroutines/coroutines-guide.html) (**read it first**) * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md) - * [Debugging capabilities in kotlinx.coroutines](docs/topics/debugging.md) -* [Compatibility policy and experimental annotations](docs/topics/compatibility.md) + * [Debugging capabilities in kotlinx.coroutines](docs/debugging.md) +* [Compatibility policy and experimental annotations](docs/compatibility.md) * [Change log for kotlinx.coroutines](CHANGES.md) * [Coroutines design document (KEEP)](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md) * [Full kotlinx.coroutines API reference](https://kotlin.github.io/kotlinx.coroutines) @@ -87,7 +86,7 @@ Add dependencies (you can also add other modules that you need): <dependency> <groupId>org.jetbrains.kotlinx</groupId> <artifactId>kotlinx-coroutines-core</artifactId> - <version>1.4.3</version> + <version>1.4.1</version> </dependency> ``` @@ -95,7 +94,7 @@ And make sure that you use the latest Kotlin version: ```xml <properties> - <kotlin.version>1.4.30</kotlin.version> + <kotlin.version>1.4.0</kotlin.version> </properties> ``` @@ -105,7 +104,7 @@ Add dependencies (you can also add other modules that you need): ```groovy dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.3' + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1' } ``` @@ -113,15 +112,15 @@ And make sure that you use the latest Kotlin version: ```groovy buildscript { - ext.kotlin_version = '1.4.30' + ext.kotlin_version = '1.4.0' } ``` -Make sure that you have `mavenCentral()` in the list of repositories: +Make sure that you have either `jcenter()` or `mavenCentral()` in the list of repositories: ``` repository { - mavenCentral() + jcenter() } ``` @@ -131,7 +130,7 @@ Add dependencies (you can also add other modules that you need): ```groovy dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.3") + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1") } ``` @@ -139,11 +138,24 @@ And make sure that you use the latest Kotlin version: ```groovy plugins { - kotlin("jvm") version "1.4.30" + kotlin("jvm") version "1.4.0" } ``` -Make sure that you have `mavenCentral()` in the list of repositories. +Make sure that you have either `jcenter()` or `mavenCentral()` in the list of repositories. + +### Multiplatform + +Core modules of `kotlinx.coroutines` are also available for +[Kotlin/JS](#js) and [Kotlin/Native](#native). +In common code that should get compiled for different platforms, you can add dependency to `kotlinx-coroutines-core` right to the `commonMain` source set: +```groovy +commonMain { + dependencies { + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1") + } +} +``` ### Android @@ -151,18 +163,18 @@ Add [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android) module as dependency when using `kotlinx.coroutines` on Android: ```groovy -implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.3' +implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.1' ``` This gives you access to Android [Dispatchers.Main] coroutine dispatcher and also makes sure that in case of crashed coroutine with unhandled exception this -exception is logged before crashing Android application, similarly to the way uncaught exceptions in -threads are handled by Android runtime. +exception is logged before crashing Android application, similarly to the way uncaught exceptions in +threads are handled by Android runtime. #### R8 and ProGuard R8 and ProGuard rules are bundled into the [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android) module. -For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-android/README.md#optimization). +For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-android/README.md#optimization). #### Avoiding including the debug infrastructure in the resulting APK @@ -175,40 +187,27 @@ packagingOptions { } ``` -### Multiplatform +### JS -Core modules of `kotlinx.coroutines` are also available for -[Kotlin/JS](https://kotlinlang.org/docs/reference/js-overview.html) and [Kotlin/Native](https://kotlinlang.org/docs/reference/native-overview.html). - -In common code that should get compiled for different platforms, you can add dependency to `kotlinx-coroutines-core` right to the `commonMain` source set: -```groovy -commonMain { - dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.3") - } -} -``` - -No more additional dependencies is needed, platform-specific artifacts will be resolved automatically via Gradle metadata available since Gradle 5.3. - -Platform-specific dependencies are recommended to be used only for non-multiplatform projects that are compiled only for target platform. - -#### JS - -Kotlin/JS version of `kotlinx.coroutines` is published as -[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.4.3/jar) -(follow the link to get the dependency declaration snippet) and as [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) NPM package. +[Kotlin/JS](https://kotlinlang.org/docs/reference/js-overview.html) version of `kotlinx.coroutines` is published as +[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.4.1/jar) +(follow the link to get the dependency declaration snippet). + +You can also use [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM. -#### Native +### Native -Kotlin/Native version of `kotlinx.coroutines` is published as -[`kotlinx-coroutines-core-$platform`](https://mvnrepository.com/search?q=kotlinx-coroutines-core-) where `$platform` is -the target Kotlin/Native platform. [List of currently supported targets](https://github.com/Kotlin/kotlinx.coroutines/blob/master/gradle/compile-native-multiplatform.gradle#L16). +[Kotlin/Native](https://kotlinlang.org/docs/reference/native-overview.html) version of `kotlinx.coroutines` is published as +[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.4.1/jar) +(follow the link to get the dependency declaration snippet). +Only single-threaded code (JS-style) on Kotlin/Native is currently supported. +Kotlin/Native supports only Gradle version 4.10 and you need to enable Gradle metadata in your +`settings.gradle` file: -Only single-threaded code (JS-style) on Kotlin/Native is supported in stable versions. -Additionally, special `-native-mt` version is released on a regular basis, for the state of multi-threaded coroutines support -please follow the [corresponding issue](https://github.com/Kotlin/kotlinx.coroutines/issues/462) for the additional details. +```groovy +enableFeaturePreview('GRADLE_METADATA') +``` Since Kotlin/Native does not generally provide binary compatibility between versions, you should use the same version of Kotlin/Native compiler as was used to build `kotlinx.coroutines`. @@ -219,7 +218,6 @@ See [Contributing Guidelines](CONTRIBUTING.md). <!--- MODULE kotlinx-coroutines-core --> <!--- INDEX kotlinx.coroutines --> - [launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html [async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html [Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html @@ -241,81 +239,52 @@ See [Contributing Guidelines](CONTRIBUTING.md). [Promise.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/kotlin.js.-promise/await.html [promise]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/promise.html [Window.asCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/org.w3c.dom.-window/as-coroutine-dispatcher.html - <!--- INDEX kotlinx.coroutines.flow --> - [Flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html [_flow]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html [filter]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/filter.html [map]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/map.html - <!--- INDEX kotlinx.coroutines.channels --> - [Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/index.html - <!--- INDEX kotlinx.coroutines.selects --> - [select]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.selects/select.html - <!--- INDEX kotlinx.coroutines.sync --> - [Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/index.html [Semaphore]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-semaphore/index.html - <!--- MODULE kotlinx-coroutines-test --> <!--- INDEX kotlinx.coroutines.test --> - [Dispatchers.setMain]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/kotlinx.coroutines.-dispatchers/set-main.html [TestCoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-scope/index.html - <!--- MODULE kotlinx-coroutines-debug --> <!--- INDEX kotlinx.coroutines.debug --> - [DebugProbes]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/index.html - <!--- INDEX kotlinx.coroutines.debug.junit4 --> - [CoroutinesTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug.junit4/-coroutines-timeout/index.html - <!--- MODULE kotlinx-coroutines-slf4j --> <!--- INDEX kotlinx.coroutines.slf4j --> - [MDCContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-slf4j/kotlinx.coroutines.slf4j/-m-d-c-context/index.html - <!--- MODULE kotlinx-coroutines-jdk8 --> <!--- INDEX kotlinx.coroutines.future --> - [CompletionStage.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/java.util.concurrent.-completion-stage/await.html - <!--- MODULE kotlinx-coroutines-guava --> <!--- INDEX kotlinx.coroutines.guava --> - [ListenableFuture.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-guava/kotlinx.coroutines.guava/com.google.common.util.concurrent.-listenable-future/await.html - <!--- MODULE kotlinx-coroutines-play-services --> <!--- INDEX kotlinx.coroutines.tasks --> - [Task.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-play-services/kotlinx.coroutines.tasks/com.google.android.gms.tasks.-task/await.html - <!--- MODULE kotlinx-coroutines-reactive --> <!--- INDEX kotlinx.coroutines.reactive --> - [Publisher.collect]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/collect.html [Publisher.awaitSingle]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/await-single.html [kotlinx.coroutines.reactive.publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html - <!--- MODULE kotlinx-coroutines-rx2 --> <!--- INDEX kotlinx.coroutines.rx2 --> - [rxFlowable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.rx2/rx-flowable.html [rxSingle]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.rx2/rx-single.html - <!--- MODULE kotlinx-coroutines-rx2 --> <!--- INDEX kotlinx.coroutines.rx2 --> <!--- MODULE kotlinx-coroutines-reactor --> <!--- INDEX kotlinx.coroutines.reactor --> - [flux]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor/kotlinx.coroutines.reactor/flux.html [mono]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor/kotlinx.coroutines.reactor/mono.html - <!--- END --> |