Version 1.3.8

CHANGES.md

@@ -1,5 +1,25 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.3.8
+
+### New experimental features
+
+* Added `Flow.transformWhile operator` (#2065).
+* Replaced `scanReduce` with `runningReduce` to be consistent with the Kotlin standard library (#2139).
+
+### Bug fixes and improvements
+
+* Improve user experience for the upcoming coroutines debugger (#2093, #2118, #2131).
+* Debugger no longer retains strong references to the running coroutines (#2129).
+* Fixed race in `Flow.asPublisher` (#2109).
+* Fixed `ensureActive` to work in the empty context case to fix `IllegalStateException` when using flow from `suspend fun main` (#2044).
+* Fixed a problem with `AbortFlowException` in the `Flow.first` operator to avoid erroneous `NoSuchElementException` (#2051).
+* Fixed JVM dependency on Android annotations (#2075).
+* Removed keep rules mentioning `kotlinx.coroutines.android` from core module (#2061 by @mkj-gram).
+* Corrected some docs and examples (#2062, #2071, #2076, #2107, #2098, #2127, #2078, #2135).                                                                          
+* Improved the docs and guide on flow cancellation (#2043).
+* Updated Gradle version to `6.3` (it only affects multiplatform artifacts in this release).
+
 ## Version 1.3.7
 
 * Fixed problem that triggered Android Lint failure (#2004).

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.7) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.7)
+[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=1.3.8) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.8)
 
 Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
 This is a companion version for Kotlin `1.3.71` release.
@@ -84,7 +84,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.7</version>
+    <version>1.3.8</version>
 </dependency>
 ```
 
@@ -102,7 +102,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.8'
 }
 ```
 
@@ -128,7 +128,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.8")
 }
 ```
 
@@ -147,7 +147,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.7/jar)
+[`kotlinx-coroutines-core-common`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-common/1.3.8/jar)
 (follow the link to get the dependency declaration snippet).
 
 ### Android
@@ -156,7 +156,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.7'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.8'
 ```
 
 This gives you access to Android [Dispatchers.Main]
@@ -172,15 +172,15 @@ For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-
 ### 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.7/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.3.8/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.7/jar)
+[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.3.8/jar)
 (follow the link to get the dependency declaration snippet).
 
 Only single-threaded code (JS-style) on Kotlin/Native is currently supported. 

benchmarks/src/jmh/kotlin/benchmarks/flow/TakeWhileBenchmark.kt

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+@file:Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
+
+package benchmarks.flow
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.flow.internal.*
+import org.openjdk.jmh.annotations.*
+import java.util.concurrent.TimeUnit
+
+@Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Fork(value = 1)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
+@State(Scope.Benchmark)
+open class TakeWhileBenchmark {
+    @Param("1", "10", "100", "1000")
+    private var size: Int = 0
+
+    private suspend inline fun Flow<Long>.consume() =
+        filter { it % 2L != 0L }
+            .map { it * it }.count()
+
+    @Benchmark
+    fun baseline() = runBlocking<Int> {
+        (0L until size).asFlow().consume()
+    }
+
+    @Benchmark
+    fun takeWhileDirect() = runBlocking<Int> {
+        (0L..Long.MAX_VALUE).asFlow().takeWhileDirect { it < size }.consume()
+    }
+
+    @Benchmark
+    fun takeWhileViaCollectWhile() = runBlocking<Int> {
+        (0L..Long.MAX_VALUE).asFlow().takeWhileViaCollectWhile { it < size }.consume()
+    }
+
+    // Direct implementation by checking predicate and throwing AbortFlowException
+    private fun <T> Flow<T>.takeWhileDirect(predicate: suspend (T) -> Boolean): Flow<T> = unsafeFlow {
+        try {
+            collect { value ->
+                if (predicate(value)) emit(value)
+                else throw AbortFlowException(this)
+            }
+        } catch (e: AbortFlowException) {
+            e.checkOwnership(owner = this)
+        }
+    }
+
+    // Essentially the same code, but reusing the logic via collectWhile function
+    private fun <T> Flow<T>.takeWhileViaCollectWhile(predicate: suspend (T) -> Boolean): Flow<T> = unsafeFlow {
+        // This return is needed to work around a bug in JS BE: KT-39227
+        return@unsafeFlow collectWhile { value ->
+            if (predicate(value)) {
+                emit(value)
+                true
+            } else {
+                false
+            }
+        }
+    }
+}

build.gradle

@@ -2,6 +2,7 @@
  * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 import org.jetbrains.kotlin.konan.target.HostManager
+import org.gradle.util.VersionNumber
 
 apply plugin: 'jdk-convention'
 apply from: rootProject.file("gradle/experimental.gradle")
@@ -79,6 +80,11 @@ buildscript {
 
 import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType
 
+// Hierarchical project structures are not fully supported in 1.3.7x MPP, enable conditionally for 1.4.x
+if (VersionNumber.parse(kotlin_version) > VersionNumber.parse("1.3.79")) {
+    ext.set("kotlin.mpp.enableGranularSourceSetsMetadata", "true")
+}
+
 // todo:KLUDGE: This is needed to workaround dependency resolution between Java and MPP modules
 def configureKotlinJvmPlatform(configuration) {
     configuration.attributes.attribute(KotlinPlatformType.attribute, KotlinPlatformType.jvm)
@@ -126,6 +132,7 @@ apiValidation {
     if (build_snapshot_train) {
         ignoredProjects.remove("site")
         ignoredProjects.remove("example-frontend-js")
+        ignoredProjects.add("kotlinx-coroutines-core")
     }
     ignoredPackages += "kotlinx.coroutines.internal"
 }
@@ -192,6 +199,8 @@ if (build_snapshot_train) {
             exclude '**/*definitely/not/kotlinx*'
             // Disable because of KT-11567 in 1.4
             exclude '**/*CasesPublicAPITest*'
+            // Kotlin
+            exclude '**/*PrecompiledDebugProbesTest*'
         }
     }
 

coroutines-guide.md

@@ -47,7 +47,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
     * <a name='suspending-functions'></a>[Suspending functions](docs/flow.md#suspending-functions)
     * <a name='flows'></a>[Flows](docs/flow.md#flows)
   * <a name='flows-are-cold'></a>[Flows are cold](docs/flow.md#flows-are-cold)
-  * <a name='flow-cancellation'></a>[Flow cancellation](docs/flow.md#flow-cancellation)
+  * <a name='flow-cancellation-basics'></a>[Flow cancellation basics](docs/flow.md#flow-cancellation-basics)
   * <a name='flow-builders'></a>[Flow builders](docs/flow.md#flow-builders)
   * <a name='intermediate-flow-operators'></a>[Intermediate flow operators](docs/flow.md#intermediate-flow-operators)
     * <a name='transform-operator'></a>[Transform operator](docs/flow.md#transform-operator)
@@ -79,6 +79,8 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
     * <a name='successful-completion'></a>[Successful completion](docs/flow.md#successful-completion)
   * <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-cancellation-checks'></a>[Flow cancellation checks](docs/flow.md#flow-cancellation-checks)
+    * <a name='making-busy-flow-cancellable'></a>[Making busy flow cancellable](docs/flow.md#making-busy-flow-cancellable)
   * <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)

docs/basics.md

@@ -338,7 +338,7 @@ import kotlinx.coroutines.*
 fun main() = runBlocking {
     repeat(100_000) { // launch a lot of coroutines
         launch {
-            delay(1000L)
+            delay(5000L)
             print(".")
         }
     }
@@ -351,7 +351,7 @@ fun main() = runBlocking {
 
 <!--- TEST lines.size == 1 && lines[0] == ".".repeat(100_000) -->
 
-It launches 100K coroutines and, after a second, each coroutine prints a dot. 
+It launches 100K coroutines and, after 5 seconds, each coroutine prints a dot. 
 
 Now, try that with threads. What would happen? (Most likely your code will produce some sort of out-of-memory error)