Merge pull request #1057 from Kotlin/version-1.2.0-alpha

Version 1.2.0-alpha

Author: qwwdfsad

CHANGES.md

@@ -1,5 +1,33 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.2.0-alpha
+
+* Major debug agent improvements. Real stacktraces are merged with coroutine stacktraces for running coroutines, merging heuristic is improved, API is cleaned up and is on its road to stabilization (#997).
+* `CoroutineTimeout` rule or JUnit4 is introduced to simplify coroutines debugging (#938).
+* Stacktrace recovery improvements. Exceptions with custom properties are no longer copied, `CopyableThrowable` interface is introduced, machinery is [documented](https://github.com/Kotlin/kotlinx.coroutines/blob/develop/docs/debugging.md) (#921, #950).
+* `Dispatchers.Unconfined`, `MainCoroutineDispatcher.immediate`, `MainScope` and `CoroutineScope.cancel` are promoted to stable API (#972).
+* `CompletableJob` is introduced (#971).
+* Structured concurrency is integrated into futures and listenable futures (#1008).
+* `ensurePresent` and `isPresent` extensions for `ThreadLocal` (#1028).
+* `ensureActive` extensions for `CoroutineContext`, `CoroutineScope` and `Job` (#963).
+* `SendChannel.isFull` and `ReceiveChannel.isEmpty` are deprecated (#1053).
+* `withContext` checks cancellation on entering (#962).
+* Operator `invoke` on `CoroutineDispatcher` (#428).
+* Java 8 extensions for `delay` and `withTimeout` now properly handle too large values (#428).
+* Performance of `Dispatcher.Main` initialization is significantly improved (#878).
+* A global exception handler for fatal exceptions in coroutines is introduced (#808, #773).
+* Major improvements in cancellation machinery and exceptions delivery consistency. Cancel with custom exception is completely removed.
+* Kotlin version is updated to 1.3.21.
+* Do not use private API on newer Androids to handle exceptions (#822).
+
+Bug fixes:
+* Proper `select` support in debug agent (#931).
+* Proper `supervisorScope` support in debug agent (#915).
+* Throwing `initCause` does no longer trigger an internal error (#933).
+* Lazy actors are started when calling `close` in order to cleanup their resources (#939).
+* Minor bugs in reactive integrations are fixed (#1008).
+* Experimental scheduler shutdown sequence is fixed (#990).
+
 ## Version 1.1.1
 
 * Maintenance release, no changes in the codebase
@@ -184,7 +212,7 @@ Visible consequences of include more robust exception handling for large corouti
 * 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.
+* JAR files for `kotlinx-coroutines` are now [JEP 238](https://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).
@@ -221,7 +249,7 @@ Visible consequences of include more robust exception handling for large corouti
 * Includes multiple fixes to documentation contributed by @paolop, @SahilLone, @rocketraman, @bdavisx, @mtopolnik, @Groostav.   
 * Experimental coroutines scheduler preview (JVM only):
   * Written from scratch and optimized for communicating coroutines.
-  * Performs significantly better than ForkJoinPool on coroutine benchmarks and for connected applications with [ktor](http://ktor.io).
+  * Performs significantly better than ForkJoinPool on coroutine benchmarks and for connected applications with [ktor](https://ktor.io).
   * Supports automatic creating of new threads for blocking operations running on the same thread pool (with an eye on solving #79), but there is no stable public API for it just yet.
   * For preview, run JVM with `-Dkotlinx.coroutines.scheduler` option. In this case `DefaultDispatcher` is set to new experimental scheduler instead of FJP-based `CommonPool`.
   * Submit your feedback to issue #261.
@@ -514,7 +542,7 @@ Visible consequences of include more robust exception handling for large corouti
 * Fixed bug in internal class LockFreeLinkedList that resulted in ISE under stress in extremely rare circumstances.
 * Integrations:
   * [quasar](integration/kotlinx-coroutines-quasar): Introduced integration with suspendable JVM functions
-    that are instrumented with [Parallel Universe Quasar](http://docs.paralleluniverse.co/quasar/) 
+    that are instrumented with [Parallel Universe Quasar](https://docs.paralleluniverse.co/quasar/) 
     (thanks to the help of @pron). 
   * [reactor](reactive/kotlinx-coroutines-reactor): Replaced deprecated `setCancellation` with `onDipose` and 
     updated to Aluminium-SR3 release (courtesy of @yxf07, see #96) 

COMPATIBILITY.md

@@ -1,14 +1,11 @@
 # kotlinx.coroutines 
 
-[![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=1.1.1) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.1.1)
+[![official JetBrains project](https://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)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=1.2.0-alpha) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.2.0-alpha)
 
 Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
-This is a companion version for Kotlin `1.3.20` release.
-
-**NOTE**: `0.30.2` was the last release with Kotlin 1.2 and experimental coroutines.
-See [COMPATIBILITY.md](COMPATIBILITY.md) for details of migration onto the stable Kotlin 1.3 coroutines.
+This is a companion version for Kotlin `1.3.21` release.
 
 ```kotlin
 GlobalScope.launch {
@@ -19,7 +16,7 @@ GlobalScope.launch {
 
 ## Modules
 
-* [common](common/README.md) — common coroutines across all platforms:
+* [core](kotlinx-coroutines-core/README.md) — common coroutines across all platforms:
   * `launch` and `async` coroutine builders;
   * `Job` and `Deferred` light-weight future with cancellation support;
   * `MainScope` for Android and UI applications.
@@ -29,15 +26,17 @@ GlobalScope.launch {
   * `coroutineScope` and `supervisorScope` scope builders;
   * `SupervisorJob` and `CoroutineExceptionHandler` for supervision of coroutines hierarchies;
   * `select` expression support and more.
-* [core](core/README.md) — Kotlin/JVM implementation of common coroutines with additional features:
+* [core/jvm](kotlinx-coroutines-core/jvm/) — additional core features available on Kotlin/JVM:
   * `Dispatchers.IO` dispatcher for blocking coroutines;
   * `Executor.asCoroutineDispatcher()` extension, custom thread pools, and more.
-* [test](core/README.md) — test utilities for coroutines
+* [core/js](kotlinx-coroutines-core/js/) — additional core features available on Kotlin/JS:
+  * Integration with `Promise`;
+  * Integration with `Window`.
+* [test](kotlinx-coroutines-test/README.md) — test utilities for coroutines
   * `Dispatchers.setMain` to override `Dispatchers.Main` in tests.
-* [debug](core/README.md) — debug utilities for coroutines.
+* [debug](kotlinx-coroutines-debug/README.md) — debug utilities for coroutines.
   * `DebugProbes` API to probe, keep track of, print and dump active coroutines.
-* [js](js/README.md) — Kotlin/JS implementation of common coroutines with `Promise` support.
-* [native](native/README.md) — Kotlin/Native implementation of common coroutines with `runBlocking` single-threaded event loop.
+  * `CoroutinesTimeout` test rule to automatically dump coroutines on test timeout.
 * [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:
   * Reactive Streams, RxJava 2.x, and Project Reactor. 
 * [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:
@@ -56,9 +55,11 @@ GlobalScope.launch {
   * [Guide to kotlinx.coroutines by example](docs/coroutines-guide.md) (**read it first**)
   * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
   * [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.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](http://kotlin.github.io/kotlinx.coroutines)
+* [Full kotlinx.coroutines API reference](https://kotlin.github.io/kotlinx.coroutines)
 
 ## Using in your projects
 
@@ -74,15 +75,15 @@ Add dependencies (you can also add other modules that you need):
 <dependency>
     <groupId>org.jetbrains.kotlinx</groupId>
     <artifactId>kotlinx-coroutines-core</artifactId>
-    <version>1.1.1</version>
+    <version>1.2.0-alpha</version>
 </dependency>
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```xml
 <properties>
-    <kotlin.version>1.3.20</kotlin.version>
+    <kotlin.version>1.3.21</kotlin.version>
 </properties>
 ```
 
@@ -92,15 +93,15 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.1.1'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.2.0-alpha'
 }
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```groovy
 buildscript {
-    ext.kotlin_version = '1.3.20'
+    ext.kotlin_version = '1.3.21'
 }
 ```
 
@@ -118,15 +119,15 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.1.1")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.2.0-alpha")
 }
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```groovy
 plugins {
-    kotlin("jvm") version "1.3.20"
+    kotlin("jvm") version "1.3.21"
 }
 ```
 
@@ -146,7 +147,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:1.1.1'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.2.0-alpha'
 ```
 This gives you access to Android [Dispatchers.Main](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-android/kotlinx.coroutines.android/kotlinx.coroutines.-dispatchers/index.html)
 coroutine dispatcher and also makes sure that in case of crashed coroutine with unhandled exception this

README.md

@@ -49,7 +49,7 @@ To release new `<version>` of `kotlinx-coroutines`:
    * Wait until "Build" configuration for committed `master` branch passes tests.
    * Run "Deploy (Configure, RUN THIS ONE)" configuration with the corresponding new version.    
 
-2. In [GitHub](http://github.com/kotlin/kotlinx.coroutines) interface:
+2. In [GitHub](https://github.com/kotlin/kotlinx.coroutines) interface:
    * Create new release named as `<version>`. 
    * Cut & paste lines from [`CHANGES.md`](CHANGES.md) into description.    
 
@@ -61,7 +61,7 @@ To release new `<version>` of `kotlinx-coroutines`:
    * Wait until newly published version becomes the most recent.
    * Sync to Maven Central.
 
-5. Announce new release in [Slack](http://kotlinlang.slack.com)   
+5. Announce new release in [Slack](https://kotlinlang.slack.com)   
 
 6. Switch into `develop` branch:<br>
    `git checkout develop`

RELEASE.md

@@ -7,11 +7,20 @@ apply plugin: "com.github.johnrengelman.shadow"
 apply plugin: "me.champeau.gradle.jmh"
 
 repositories {
-    maven { url "http://repo.typesafe.com/typesafe/releases/" }
+    maven { url "https://repo.typesafe.com/typesafe/releases/" }
 }
 
 jmh.jmhVersion = '1.21'
 
+// It is better to use the following to run benchmarks, otherwise you may get unexpected errors:
+// ../gradlew --no-daemon cleanJmhJar jmh
+jmh {
+    duplicateClassesStrategy DuplicatesStrategy.INCLUDE
+    failOnError = true
+    resultFormat = 'CSV'
+//    include = ['.*ChannelProducerConsumer.*']
+}
+
 jmhJar {
     baseName 'benchmarks'
     classifier = null
@@ -20,8 +29,8 @@ jmhJar {
 }
 
 dependencies {
+    compile "org.openjdk.jmh:jmh-core:1.21"
     compile 'com.typesafe.akka:akka-actor_2.12:2.5.0'
-    compile project(':kotlinx-coroutines-core-common')
     compile project(':kotlinx-coroutines-core')
-    compile "org.openjdk.jmh:jmh-core:1.21"
 }
+