From 7764e43c6fe9640615747f7830e8aae1b9bc26d2 Mon Sep 17 00:00:00 2001 From: Roman Elizarov Date: Fri, 28 Sep 2018 19:30:08 +0300 Subject: [PATCH] Version 0.30.0 --- CHANGES.md | 19 ++++++++++++++ COMPATIBILITY.md | 25 +++++++++++++++++++ README.md | 10 +++++--- RELEASE.md | 2 +- gradle.properties | 2 +- native/README.md | 2 +- ui/coroutines-guide-ui.md | 2 +- .../animation-app/gradle.properties | 2 +- .../example-app/gradle.properties | 2 +- 9 files changed, 56 insertions(+), 10 deletions(-) create mode 100644 COMPATIBILITY.md diff --git a/CHANGES.md b/CHANGES.md index e6f3c63488..8557b2e345 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,5 +1,24 @@ # Change log for kotlinx.coroutines +## Version 0.30.0 + +* **[Major]** Further improvements in exception handling — no failure exception is lost. + * `async` and async-like builders cancel parent on failure (it affects `CompletableDeferred`, and all reactive integration builders). + * This makes parallel decomposition exception-safe and reliable without having to rember about `awaitAll` (see #552). + * `Job()` wih parent now also cancels parent on failure consistently with other scopes. + * All coroutine builders and `Job` implementations propagate failure to the parent unless it is a `CancellationException`. + * Note, "scoping" builders don't "cancel the parent" verbatim, but rethrow the corresponding exception to the caller for handling. + * `SupervisorJob()` and `supervisorScope { ... }` are introduced, allowing for a flexible implementation of custom exception-handling policies, see a [new section in the guide on supervision](docs/exception-handling.md#supervision). + * Got rid of `awaitAll` in documentation and rewrote `currentScope` section (see #624). +* **[Major]** Coroutine scheduler is used for `Dispatchers.Default` by default instead of deprecated `CommonPool`. + * "`DefaultDispatcher`" is used as a public name of the default impl (you'll see it thread names and in the guide). + * `-Dkotlinx.coroutines.scheduler=off` can be used to switch back to `CommonPool` for a time being (until deprecated CommonPool is removed). +* Make `CoroutineStart.ATOMIC` experimental as it covers important use-case with resource cleanup in finally block (see #627). +* Restored binary compatibility of `Executor.asCoroutineDispatcher` (see #629). +* Fixed OOM in thread-pool dispatchers (see #571). +* Check for cancellation when starting coroutine with `Dispatchers.Unconfined` (see #621). +* A bunch of various performance optimizations and docs fixes, including contributions from @AlexanderPrendota, @PaulWoitaschek. + ## Version 0.27.0 * **[Major]** Public API revision. All public API was reviewed and marked as preparation to `1.0` release: diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000000..405632ddc4 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,25 @@ +# Compatibility policy for kotlinx.coroutines + +All `kotlinx.coroutines` API comes into five flavors: stable, experimental, obsolete, internal and deprecated. + * **Deprecated** API is marked with `@Deprecated` and will be removed in `1.0.0` release. + * **Internal** API is marked with `@InternalCoroutinesApi`. It is intended to be used only by `kotlinx.coroutines` machinery and can (will) be broken without a warning. If you are using internal API, please tell us what problem you are trying to solve, so we can provide a stable alternative. + * **Experimental** API is marked with `ExperimentalCoroutinesApi`. Such API may have (known) design issues or we are unsure about its semantics. + Roughly speaking, there is a chance that those declarations will be deprecated in the near future or the semantics of their behavior may change in the way that may break some code. In that case, proper migration aid + will be provided for next several releases alongside with a stable alternative. + * **Obsolete** API is marked with `@ObsoleteCoroutinesApi`. This API is known to have some serious issues, so it will be replaced with a better alternative. + In the sense of migration and deprecation, it is equal to experimental. + * **Stable** API is public API without any annotations. This API is proven to be stable and it is not going to change. If at some point it will be discovered that such API has unfixable design flaws, + it will be gradually deprecated with proper replacement and migration aid, but won't be removed for at least a year. + +## Migration to 1.0.0 version with Kotlin 1.3 + +The main difference between Kotlin 1.2 and 1.3 is that coroutines are now +stable public API, and thus `kotlinx.coroutines` is leaving its "experimental" status. For that reason, future releases of `kotlinx.coroutines` will be available only for Kotlin 1.3. +Version `1.0.0` (starting with its release candidate build) will have all its deprecated declarations removed and `kotlinx.coroutines.experimental` package will be renamed to `kotlinx.coroutines` without functional changes. +In order to migrate `kotlinx.coroutines` to `1.0.0`, follow these steps: + +1. Update `kotlinx.coroutines` to `0.30.0` version. +2. Inspect compiler warnings about deprecated API and migrate it to a proposed alternative. Most of deprecated API has a corresponding replacement which can be applied from IDEA with quickfix. +3. Update Kotlin version to `1.3.0` or to the latest `1.3.0-rc` and `kotlinx.coroutines` to version `0.30.0-eap13`. Then just get rid of `experimental` suffix in all imports. +4. Update `kotlinx.coroutines` to version `1.0.0` or to the corresponding release candidate of it). + \ No newline at end of file diff --git a/README.md b/README.md index afa0f024d5..17f7b5f7c6 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,13 @@ [![official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0) -[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.27.0) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.27.0) +[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.30.0) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.30.0) Library support for Kotlin coroutines with [multiplatform](#multiplatform) support. This is a companion version for Kotlin 1.2.70 release. +**NOTE**: This is the latest experimental release. See [COMPATIBILITY.md](COMPATIBILITY.md) for details on migration. + ```kotlin GlobalScope.launch { delay(1000) @@ -63,7 +65,7 @@ Add dependencies (you can also add other modules that you need): org.jetbrains.kotlinx kotlinx-coroutines-core - 0.27.0 + 0.30.0 ``` @@ -80,7 +82,7 @@ And make sure that you use the latest Kotlin version: Add dependencies (you can also add other modules that you need): ```groovy -implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.27.0' +implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.30.0' ``` And make sure that you use the latest Kotlin version: @@ -113,7 +115,7 @@ 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:0.27.0' +implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:0.30.0' ``` This gives you access to Android [Dispatchers.Main](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-android/kotlinx.coroutines.experimental.android/kotlinx.coroutines.experimental.-dispatchers/index.html) coroutine dispatcher and also makes sure that in case of crashed coroutine with unhandled exception this diff --git a/RELEASE.md b/RELEASE.md index 1b488ea23c..46094eac17 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -9,7 +9,7 @@ To release new `` of `kotlinx-coroutines`: `git pull` 3. Make sure the `master` branch is fully merged into `develop`: - `git merge master` + `git merge origin/master` 4. Search & replace `` with `` across the project files. Should replace in: * [`README.md`](README.md) diff --git a/gradle.properties b/gradle.properties index 998413e2de..acb537e3e1 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,5 +1,5 @@ # Kotlin -version=0.27.0-SNAPSHOT +version=0.30.0-SNAPSHOT group=org.jetbrains.kotlinx kotlin_version=1.2.70 kotlin_native_version=0.8.2 diff --git a/native/README.md b/native/README.md index 5632d31a6b..b055e4917c 100644 --- a/native/README.md +++ b/native/README.md @@ -42,7 +42,7 @@ repositories { } dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-native:0.27.0' + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-native:0.30.0' } sourceSets { diff --git a/ui/coroutines-guide-ui.md b/ui/coroutines-guide-ui.md index 981b004bde..4a757621a6 100644 --- a/ui/coroutines-guide-ui.md +++ b/ui/coroutines-guide-ui.md @@ -161,7 +161,7 @@ Add dependencies on `kotlinx-coroutines-android` module to the `dependencies { . `app/build.gradle` file: ```groovy -compile "org.jetbrains.kotlinx:kotlinx-coroutines-android:0.27.0" +compile "org.jetbrains.kotlinx:kotlinx-coroutines-android:0.30.0" ``` Coroutines are experimental feature in Kotlin. diff --git a/ui/kotlinx-coroutines-android/animation-app/gradle.properties b/ui/kotlinx-coroutines-android/animation-app/gradle.properties index ad1d93eb5e..d3701fda5f 100644 --- a/ui/kotlinx-coroutines-android/animation-app/gradle.properties +++ b/ui/kotlinx-coroutines-android/animation-app/gradle.properties @@ -19,5 +19,5 @@ org.gradle.jvmargs=-Xmx1536m kotlin.coroutines=enable kotlin_version=1.2.70 -coroutines_version=0.27.0 +coroutines_version=0.30.0 diff --git a/ui/kotlinx-coroutines-android/example-app/gradle.properties b/ui/kotlinx-coroutines-android/example-app/gradle.properties index ad1d93eb5e..d3701fda5f 100644 --- a/ui/kotlinx-coroutines-android/example-app/gradle.properties +++ b/ui/kotlinx-coroutines-android/example-app/gradle.properties @@ -19,5 +19,5 @@ org.gradle.jvmargs=-Xmx1536m kotlin.coroutines=enable kotlin_version=1.2.70 -coroutines_version=0.27.0 +coroutines_version=0.30.0