Merge branch 'master' into develop

# Conflicts:
#	reactive/kotlinx-coroutines-reactive/src/Channel.kt
#	reactive/kotlinx-coroutines-rx2/src/RxChannel.kt

Author: qwwdfsad

CHANGES.md

@@ -1,5 +1,14 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.3.2
+
+This is a maintenance release that does not include any new features or bug fixes.
+
+* Reactive integrations for `Flow` are promoted to stable API.
+* Obsolete reactive API is deprecated.
+* Deprecation level for API deprecated in 1.3.0 is increased.
+* Various documentation improvements.
+
 ## Version 1.3.1
 
 This is a minor update with various fixes:

README.md

@@ -2,7 +2,7 @@
 
 [![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.3.1) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.1)
+[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=1.3.2) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.2)
 
 Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
 This is a companion version for Kotlin `1.3.50` release.
@@ -62,7 +62,6 @@ suspend fun main() = coroutineScope {
 * Guides and manuals: 
   * [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)
@@ -83,7 +82,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.3.1</version>
+    <version>1.3.2</version>
 </dependency>
 ```
 
@@ -101,7 +100,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.1'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.2'
 }
 ```
 
@@ -127,7 +126,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.1")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.2")
 }
 ```
 
@@ -146,7 +145,7 @@ Make sure that you have either `jcenter()` or `mavenCentral()` in the list of re
 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, add dependency to  
-[`kotlinx-coroutines-core-common`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-common/1.3.1/jar)
+[`kotlinx-coroutines-core-common`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-common/1.3.2/jar)
 (follow the link to get the dependency declaration snippet).
 
 ### Android
@@ -155,7 +154,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.3.1'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.2'
 ```
 
 This gives you access to Android [Dispatchers.Main]
@@ -174,15 +173,15 @@ R8 is a replacement for ProGuard in Android ecosystem, it is enabled by default
 ### 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.3.1/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.3.2/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.3.1/jar)
+[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.3.2/jar)
 (follow the link to get the dependency declaration snippet).
 
 Only single-threaded code (JS-style) on Kotlin/Native is currently supported. 

binary-compatibility-validator/resources/api.properties

@@ -4,6 +4,6 @@
 
 module.roots=/ integration reactive ui
 module.marker=build.gradle
-module.ignore=kotlinx-coroutines-rx-example stdlib-stubs benchmarks knit binary-compatibility-validator site publication-validator kotlinx-coroutines-bom
+module.ignore=stdlib-stubs benchmarks knit binary-compatibility-validator site publication-validator kotlinx-coroutines-bom
 
 packages.internal=kotlinx.coroutines.internal

build.gradle

@@ -11,7 +11,7 @@ def coreModule = "kotlinx-coroutines-core"
 def sourceless = ['kotlinx.coroutines', 'site', 'kotlinx-coroutines-bom']
 def internal = ['kotlinx.coroutines', 'site', 'benchmarks', 'knit', 'js-stub', 'stdlib-stubs', 'binary-compatibility-validator']
 // Not published
-def unpublished = internal + ['kotlinx-coroutines-rx-example', 'example-frontend-js', 'android-unit-tests']
+def unpublished = internal + ['example-frontend-js', 'android-unit-tests']
 
 static def platformOf(project) {
     def name = project.name

coroutines-guide.md

@@ -79,6 +79,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
     * <a name='upstream-exceptions-only'></a>[Upstream exceptions only](docs/flow.md#upstream-exceptions-only)
   * <a name='imperative-versus-declarative'></a>[Imperative versus declarative](docs/flow.md#imperative-versus-declarative)
   * <a name='launching-flow'></a>[Launching flow](docs/flow.md#launching-flow)
+  * <a name='flow-and-reactive-streams'></a>[Flow and Reactive Streams](docs/flow.md#flow-and-reactive-streams)
 <!--- TOC_REF docs/channels.md -->
 * <a name='channels'></a>[Channels](docs/channels.md#channels)
   * <a name='channel-basics'></a>[Channel basics](docs/channels.md#channel-basics)

docs/coroutines-guide.md

@@ -28,6 +28,5 @@ In order to use coroutines as well as follow the examples in this guide, you nee
 ## Additional references
 
 * [Guide to UI programming with coroutines](../ui/coroutines-guide-ui.md)
-* [Guide to reactive streams with coroutines](../reactive/coroutines-guide-reactive.md)
 * [Coroutines design document (KEEP)](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md)
 * [Full kotlinx.coroutines API reference](https://kotlin.github.io/kotlinx.coroutines)

docs/flow.md

@@ -58,6 +58,7 @@ class FlowGuideTest {
     * [Upstream exceptions only](#upstream-exceptions-only)
   * [Imperative versus declarative](#imperative-versus-declarative)
   * [Launching flow](#launching-flow)
+  * [Flow and Reactive Streams](#flow-and-reactive-streams)
 
 <!--- END_TOC -->
 
@@ -1794,6 +1795,18 @@ as cancellation and structured concurrency serve this purpose.
 Note that [launchIn] also returns a [Job], which can be used to [cancel][Job.cancel] the corresponding flow collection
 coroutine only without cancelling the whole scope or to [join][Job.join] it.
 
+### Flow and Reactive Streams
+
+For those who are familiar with [Reactive Streams](https://www.reactive-streams.org/) or reactive frameworks such as RxJava and project Reactor, 
+design of the Flow may look very familiar.
+
+Indeed, its design was inspired by Reactive Streams and its various implementations. But Flow main goal is to have as simple design as possible, 
+be Kotlin and suspension friendly and respect structured concurrency. Achieving this goal would be impossible without reactive pioneers and their tremendous work. You can read the complete story in [Reactive Streams and Kotlin Flows](https://medium.com/@elizarov/reactive-streams-and-kotlin-flows-bfd12772cda4) article.
+
+While being different, conceptually, Flow *is* a reactive stream and it is possible to convert it to the reactive (spec and TCK compliant) Publisher and vice versa.
+Such converters are provided by `kotlinx.coroutines` out-of-the-box and can be found in corresponding reactive modules (`kotlinx-coroutines-reactive` for Reactive Streams, `kotlinx-coroutines-reactor` for Project Reactor and `kotlinx-coroutines-rx2` for RxJava2).
+Integration modules include conversions from and to `Flow`, integration with Reactor's `Context` and suspension-friendly ways to work with various reactive entities.
+ 
 <!-- stdlib references -->
 
 [collections]: https://kotlinlang.org/docs/reference/collections-overview.html 

gradle.properties

@@ -3,7 +3,7 @@
 #
 
 # Kotlin
-version=1.3.1-SNAPSHOT
+version=1.3.2-SNAPSHOT
 group=org.jetbrains.kotlinx
 kotlin_version=1.3.50
 

kotlinx-coroutines-core/common/src/Dispatchers.common.kt

@@ -54,9 +54,9 @@ public expect object Dispatchers {
      *
      * For example, the following code:
      * ```
-     * withContext(Dispatcher.Unconfined) {
+     * withContext(Dispatchers.Unconfined) {
      *    println(1)
-     *    withContext(Dispatcher.Unconfined) { // Nested unconfined
+     *    withContext(Dispatchers.Unconfined) { // Nested unconfined
      *        println(2)
      *    }
      *    println(3)

kotlinx-coroutines-core/jvm/src/Dispatchers.kt

@@ -71,9 +71,9 @@ public actual object Dispatchers {
      *
      * For example, the following code:
      * ```
-     * withContext(Dispatcher.Unconfined) {
+     * withContext(Dispatchers.Unconfined) {
      *    println(1)
-     *    withContext(Dispatcher.Unconfined) { // Nested unconfined
+     *    withContext(Dispatchers.Unconfined) { // Nested unconfined
      *        println(2)
      *    }
      *    println(3)

kotlinx-coroutines-debug/README.md

@@ -18,7 +18,7 @@ of coroutines hierarchy referenced by a [Job] or [CoroutineScope] instances usin
 Add `kotlinx-coroutines-debug` to your project test dependencies:
 ```
 dependencies {
-    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.3.1'
+    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.3.2'
 }
 ```
 
@@ -56,7 +56,7 @@ stacktraces will be dumped to the console.
 ### Using as JVM agent
 
 It is possible to use this module as a standalone JVM agent to enable debug probes on the application startup.
-You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.3.1.jar`.
+You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.3.2.jar`.
 Additionally, on Linux and Mac OS X you can use `kill -5 $pid` command in order to force your application to print all alive coroutines.
 
 

kotlinx-coroutines-test/README.md

@@ -9,7 +9,7 @@ This package provides testing utilities for effectively testing coroutines.
 Add `kotlinx-coroutines-test` to your project test dependencies:
 ```
 dependencies {
-    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.3.1'
+    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.3.2'
 }
 ```