Merge branch 'develop' into pr/890

Author: elizarov

CHANGES.md

@@ -1,5 +1,55 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.2.0
+
+ * Kotlin updated to 1.3.30.
+ * New API: `CancellableContinuation.resume` with `onCancelling` lambda (#1044) to consistently handle closeable resources.
+ * Play services task version updated to 16.0.1.
+ * `ReceiveChannel.isEmpty` is no longer deprecated
+
+A lot of `Flow` improvements:
+  * Purity property is renamed to context preservation and became more restrictive.
+  * `zip` and `combineLatest` operators.
+  * Integration with RxJava2
+  * `flatMap`, `merge` and `concatenate` are replaced with `flattenConcat`, `flattenMerge`, `flatMapConcat` and `flatMapMerge`.
+  * Various documentation improvements and minor bug fixes.
+  
+Note that `Flow` **is not** leaving its [preview status](/docs/compatibility.md#flow-preview-api).
+  
+## Version 1.2.0-alpha-2
+
+This release contains major [feature preview](/docs/compatibility.md#flow-preview-api): cold streams aka `Flow` (#254). 
+
+Performance:
+* Performance of `Dispatcher.Main` initialization is significantly improved (#878).
+
+## 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).
+* 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 +234,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 +271,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 +564,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,25 +1,27 @@
 # 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) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.2.0)
 
 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.30` release.
 
 ```kotlin
-GlobalScope.launch {
-    delay(1000)
-    println("Hello from Kotlin Coroutines!")
+suspend fun main() = coroutineScope {
+    launch { 
+       delay(1000)
+       println("Kotlin Coroutines World!") 
+    }
+    println("Hello")
 }
 ```
 
+> Play with coroutines online [here](https://pl.kotl.in/hG_tKbid_)
+
 ## 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 +31,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:
@@ -53,12 +57,14 @@ GlobalScope.launch {
   * [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](docs/coroutines-guide.md) (**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)
   * [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 +80,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</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.30</kotlin.version>
 </properties>
 ```
 
@@ -92,15 +98,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'
 }
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```groovy
 buildscript {
-    ext.kotlin_version = '1.3.20'
+    ext.kotlin_version = '1.3.30'
 }
 ```
 
@@ -118,15 +124,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")
 }
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```groovy
 plugins {
-    kotlin("jvm") version "1.3.20"
+    kotlin("jvm") version "1.3.30"
 }
 ```
 
@@ -135,19 +141,20 @@ Make sure that you have either `jcenter()` or `mavenCentral()` in the list of re
 ### Multiplatform
 
 Core modules of `kotlinx.coroutines` are also available for 
-[Kotlin/JS](js/README.md) and [Kotlin/Native](native/README.md). If you write
-a common code that should get compiled or different platforms, add 
-[`org.jetbrains.kotlinx:kotlinx-coroutines-core-common:<version>`](common/kotlinx-coroutines-core-common/README.md) 
-to your common code dependencies.
+[Kotlin/JS](#js) and [Kotlin/Native](#native).
+In common code that should get compiled for different platforms, add dependency to  
+[`kotlinx-coroutines-core-common`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-common/1.2.0/jar)
+(follow the link to get the dependency declaration snippet).
 
 ### Android
 
 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'
 ```
+
 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
 exception is logged before crashing Android application, similarly to the way uncaught exceptions in 
@@ -157,10 +164,35 @@ threads are handled by Android runtime.
 
 For R8 no actions required, it will take obfuscation rules from the jar.
 
-For Proguard  you need to add options from [coroutines.pro](core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro) to your rules manually.
+For Proguard  you need to add options from [coroutines.pro](kotlinx-coroutines-core/jvm/resources/META-INF/proguard/coroutines.pro) to your rules manually.
 
 R8 is a replacement for ProGuard in Android ecosystem, it is enabled by default since Android gradle plugin 3.3.0-beta.
 
+### JS
+
+[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.2.0/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
+
+[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.2.0/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:
+
+```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`. 
+
 ## Building 
 
 This library is built with Gradle. To build it, use `./gradlew build`. 

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,16 +61,20 @@ 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>
+6. Create a ticket to update coroutines version on [try.kotlinlang.org](try.kotlinlang.org).
+   * Use [KT-30870](https://youtrack.jetbrains.com/issue/KT-30870) as a template
+   * This step should be skipped for eap versions that are not merged to `master`
+
+7. Switch into `develop` branch:<br>
    `git checkout develop`
 
-7. Fetch the latest `master`:<br>
+8. Fetch the latest `master`:<br>
    `git fetch` 
 
-8. Merge release from `master`:<br>
+9. Merge release from `master`:<br>
    `git merge origin/master`
 
-9. Push updates to `develop`:<br>
+10. Push updates to `develop`:<br>
    `git push`