Version 0.25.0

Author: elizarov

CHANGES.md

@@ -1,5 +1,36 @@
 # Change log for kotlinx.coroutines
 
+## Version 0.25.0
+
+* Major rework on exception-handling and cancellation in coroutines (see #333, #452 and #451):
+  * New ["Exception Handling" section in the guide](coroutines-guide.md#exception-handling) explains exceptions in coroutines. 
+  * Semantics of `Job.cancel` resulting `Boolean` value changed — `true` means exception was handled by the job, caller shall handle otherwise.
+  * Exceptions are properly propagated from children to parents.
+  * Installed `CoroutineExceptionHandler` for a family of coroutines receives one aggregated exception in case of failure.
+  * Change `handleCoroutineException` contract, so custom exception handlers can't break coroutines machinery. 
+  * Unwrap `JobCancellationException` properly to provide exception transparency over whole call chain.
+* Introduced support for thread-local elements in coroutines context (see #119):
+  * `ThreadContextElement` API for custom thread-context sensitive context elements.
+  * `ThreadLocal.asContextElement()` extension function to convert an arbitrary thread-local into coroutine context element.
+  * New ["Thread-local data" subsection in the guide](coroutines-guide.md#thread-local-data) with examples.
+  * SLF4J Mapped Diagnostic Context (MDC) integration is provided via `MDCContext` element defined in [`kotlinx-coroutines-slf4j`](integration/kotlinx-coroutines-slf4j/README.md) integration module.
+* Introduced IO dispatcher to offload blocking I/O-intensive tasks (see #79).
+* Introduced `ExecutorCoroutineDispatcher` instead of `CloseableCoroutineDispatcher` (see #385). 
+* Built with Kotlin 1.2.61 and Kotlin/Native 0.8.2.
+* JAR files for `kotlinx-coroutines` are now [JEP 238](http://openjdk.java.net/jeps/238) multi-release JAR files.
+  * On JDK9+ `VarHandle` is used for atomic operations instead of `Atomic*FieldUpdater` for better performance.
+  * See [AtomicFu](https://github.com/Kotlin/kotlinx.atomicfu/blob/master/README.md) project for details.
+* Reversed addition of `BlockingChecker` extension point to control where `runBlocking` can be used (see #227).
+  * `runBlocking` can be used anywhere without limitations (again), but it would still cause problems if improperly used on UI thread.
+* Corrected return-type of `EventLoop` pseudo-constructor (see #477, PR by @Groostav).  
+* Fixed `as*Future()` integration functions to catch all `Throwable` exceptions (see #469).
+* Fixed `runBlocking` cancellation (see #501).
+* Fixed races and timing bugs in `withTimeoutOrNull` (see #498).
+* Execute `EventLoop.invokeOnTimeout` in `DefaultDispatcher` to allow busy-wait loops inside `runBlocking` (see #479).
+* Removed `kotlinx-coroutines-io` module from the project, it has moved to [kotlinx-io](https://github.com/kotlin/kotlinx-io/).
+* Provide experimental API to create limited view of experimental dispatcher (see #475). 
+* Various minor fixes by @LouisCAD, @Dmitry-Borodin.
+
 ## Version 0.24.0
 
 * Fully multiplatform release with Kotlin/Native support (see #246):

README.md

@@ -2,7 +2,7 @@
 
 [![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.24.0) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.24.0)
+[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=0.25.0) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.25.0)
 
 Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
 This is a companion version for Kotlin 1.2.61 release.
@@ -63,7 +63,7 @@ Add dependencies (you can also add other modules that you need):
 <dependency>
     <groupId>org.jetbrains.kotlinx</groupId>
     <artifactId>kotlinx-coroutines-core</artifactId>
-    <version>0.24.0</version>
+    <version>0.25.0</version>
 </dependency>
 ```
 
@@ -80,7 +80,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.24.0'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:0.25.0'
 ```
 
 And make sure that you use the latest Kotlin version:
@@ -113,7 +113,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.24.0'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:0.25.0'
 ```
 
 This gives you access to Android [UI](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-android/kotlinx.coroutines.experimental.android/-u-i.html)

RELEASE.md

@@ -2,14 +2,14 @@
 
 To release new `<version>` of `kotlinx-coroutines`:
 
-1. Checkout `master` branch: <br> 
-   `git checkout master`
+1. Checkout `develop` branch: <br> 
+   `git checkout develop`
 
-2. Retrieve the most recent `master`: <br> 
+2. Retrieve the most recent `develop`: <br> 
    `git pull`
-
-3. Merge `develop` branch unto `master`: <br>
-   `git merge origin/develop` 
+   
+3. Make sure the `master` branch is fully merged into `develop`:
+   `git merge master`   
 
 4. Search & replace `<old-version>` with `<version>` across the project files. Should replace in:
    * [`README.md`](README.md)
@@ -24,35 +24,51 @@ To release new `<version>` of `kotlinx-coroutines`:
    * Write each change on a single line (don't wrap with CR).
    * Study commit message from previous release.
 
-6. Commit updated files for new version: <br>
+6. Create branch for this release:
+   `git checkout -b version-<version>`
+
+7. Commit updated files to a new version branch:<br>
    `git commit -a -m "Version <version>"`
 
-7. Push new version into `master`: <br>
+8. Push new version into the branch:<br>
+   `git push -u origin version-<version>`
+   
+9. Create Pull-Request on GitHub from `version-<version>` branch into `master`:
+   * Review it.
+   * Make sure it build on CI.
+   * Get approval for it.
+   
+0. Merge new version branch into `master`:<br>
+   `git checkout master`<br>
+   `git merge version-<version>`<br>
    `git push`   
 
-8. On [TeamCity integration server](https://teamcity.jetbrains.com/project.html?projectId=KotlinTools_KotlinxCoroutines):
+1. On [TeamCity integration server](https://teamcity.jetbrains.com/project.html?projectId=KotlinTools_KotlinxCoroutines):
    * Wait until "Build" configuration for committed `master` branch passes tests.
-   * Run "Deploy" configuration with the corresponding new version.    
+   * Run "Deploy (Configure, RUN THIS ONE)" configuration with the corresponding new version.    
 
-9. In [GitHub](http://github.com/kotlin/kotlinx.coroutines) interface:
+2. In [GitHub](http://github.com/kotlin/kotlinx.coroutines) interface:
    * Create new release named as `<version>`. 
    * Cut & paste lines from [`CHANGES.md`](CHANGES.md) into description.    
 
-0. Build and publish documentation for web-site: <br>
+3. Build and publish documentation for web-site: <br>
    `site/deploy.sh <version> push`
 
-1. In [Bintray](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines) admin interface:
+4. In [Bintray](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines) admin interface:
    * Publish artifacts of the new version.
    * Wait until newly published version becomes the most recent.
    * Sync to Maven Central.
 
-2. Announce new release in [Slack](http://kotlinlang.slack.com)   
+5. Announce new release in [Slack](http://kotlinlang.slack.com)   
 
-3. Switch into `develop` branch: <br>
+6. Switch into `develop` branch:<br>
    `git checkout develop`
+ 
+7. Fetch the latest `master`:<br>
+   `git fetch` 
 
-4. Merge release from `master`: <br>
+8. Merge release from `master`:<br>
    `git merge master`
 
-5. Push updates to `develop`: <br>
+9. Push updates to `develop`:<br>
    `git push`      

gradle.properties

@@ -2,7 +2,7 @@
 # Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-version = 0.24.0-SNAPSHOT
+version = 0.25.0-SNAPSHOT
 group = org.jetbrains.kotlinx
 
 kotlin_version = 1.2.61

native/README.md

@@ -42,7 +42,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-native:0.24.0'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-native:0.25.0'
 }
 
 sourceSets {

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.24.0"
+compile "org.jetbrains.kotlinx:kotlinx-coroutines-android:0.25.0"
 ```
 
 Coroutines are experimental feature in Kotlin.

ui/kotlinx-coroutines-android/animation-app/gradle.properties

@@ -19,5 +19,5 @@ org.gradle.jvmargs=-Xmx1536m
 kotlin.coroutines=enable
 
 kotlin_version = 1.2.61
-coroutines_version = 0.24.0
+coroutines_version = 0.25.0
 

ui/kotlinx-coroutines-android/example-app/gradle.properties

@@ -19,5 +19,5 @@ org.gradle.jvmargs=-Xmx1536m
 kotlin.coroutines=enable
 
 kotlin_version = 1.2.61
-coroutines_version = 0.24.0
+coroutines_version = 0.25.0