Merge pull request #2037 from Kotlin/version-1.3.7

Version 1.3.7

Author: qwwdfsad

Diff for: .gitignore

@@ -1,6 +1,9 @@
 **/.idea/*
 !/.idea/icon.png
 !/.idea/vcs.xml
+!/.idea/copyright
+!/.idea/codeStyleSettings.xml
+!/.idea/codeStyles
 *.iml
 .gradle
 .gradletasknamecache

Diff for: .idea/codeStyleSettings.xml

@@ -1,5 +1,14 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.3.7
+
+* Fixed problem that triggered Android Lint failure (#2004).
+* New `Flow.cancellable()` operator for cooperative cancellation (#2026).
+* Emissions from `flow` builder now check cancellation status and are properly cancellable (#2026).
+* New `currentCoroutineContext` function to use unambiguously in the contexts with `CoroutineScope` in receiver position (#2026). 
+* `EXACTLY_ONCE` contract support in coroutine builders.
+* Various documentation improvements.
+
 ## Version 1.3.6
 
 ### Flow

Diff for: .idea/codeStyles/Project.xml

@@ -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.6) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.6)
+[![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)
 
 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.6</version>
+    <version>1.3.7</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.6'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7'
 }
 ```
 
@@ -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.6")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7")
 }
 ```
 
@@ -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.6/jar)
+[`kotlinx-coroutines-core-common`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-common/1.3.7/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.6'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.7'
 ```
 
 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.6/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.3.7/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.6/jar)
+[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.3.7/jar)
 (follow the link to get the dependency declaration snippet).
 
 Only single-threaded code (JS-style) on Kotlin/Native is currently supported. 

Diff for: .idea/codeStyles/codeStyleConfig.xml

@@ -2,24 +2,31 @@
  * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import me.champeau.gradle.*
+import org.jetbrains.kotlin.gradle.tasks.*
 
 plugins {
     id("net.ltgt.apt")
     id("com.github.johnrengelman.shadow")
-    id("me.champeau.gradle.jmh")
+    id("me.champeau.gradle.jmh") apply false
 }
 
 repositories {
     maven("https://repo.typesafe.com/typesafe/releases/")
 }
 
-tasks.withType<KotlinCompile>().configureEach {
-    kotlinOptions.jvmTarget = "1.8"
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
 }
 
-tasks.compileJmhKotlin {
-    kotlinOptions.freeCompilerArgs += "-Xjvm-default=enable"
+apply(plugin="me.champeau.gradle.jmh")
+
+tasks.named<KotlinCompile>("compileJmhKotlin") {
+    kotlinOptions {
+        jvmTarget = "1.8"
+        freeCompilerArgs += "-Xjvm-default=enable"
+    }
 }
 
 /*
@@ -39,20 +46,20 @@ val removeRedundantFiles = tasks.register<Delete>("removeRedundantFiles") {
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$histoOfLetters\$1\$\$special\$\$inlined\$fold\$1\$1.class")
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleBase\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleBase\$play\$histoOfLetters\$1\$\$special\$\$inlined\$fold\$1\$1.class")
-    delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble//SaneFlowPlaysScrabble\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
+    delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/SaneFlowPlaysScrabble\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
 
     // Primes
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/misc/Numbers\$\$special\$\$inlined\$filter\$1\$2\$1.class")
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/misc/Numbers\$\$special\$\$inlined\$filter\$1\$1.class")
 }
 
-tasks.jmhRunBytecodeGenerator {
+tasks.named("jmhRunBytecodeGenerator") {
     dependsOn(removeRedundantFiles)
 }
 
 // It is better to use the following to run benchmarks, otherwise you may get unexpected errors:
 // ./gradlew --no-daemon cleanJmhJar jmh -Pjmh="MyBenchmark"
-jmh {
+extensions.configure<JMHPluginExtension>("jmh") {
     jmhVersion = "1.21"
     duplicateClassesStrategy = DuplicatesStrategy.INCLUDE
     failOnError = true
@@ -63,7 +70,7 @@ jmh {
 //    includeTests = false
 }
 
-tasks.jmhJar {
+tasks.named<Jar>("jmhJar") {
     baseName = "benchmarks"
     classifier = null
     version = null
@@ -76,10 +83,9 @@ dependencies {
     compile("io.reactivex.rxjava2:rxjava:2.1.9")
     compile("com.github.akarnokd:rxjava2-extensions:0.20.8")
 
-    compile("org.openjdk.jmh:jmh-core:1.21")
     compile("com.typesafe.akka:akka-actor_2.12:2.5.0")
     compile(project(":kotlinx-coroutines-core"))
 
     // add jmh dependency on main
-    jmhImplementation(sourceSets.main.get().runtimeClasspath)
+    "jmhImplementation"(sourceSets.main.get().runtimeClasspath)
 }

Diff for: .idea/copyright/kotlinx_coroutines.xml

@@ -8,7 +8,7 @@ import benchmarks.common.*
 import kotlinx.coroutines.*
 import kotlinx.coroutines.flow.*
 import org.openjdk.jmh.annotations.*
-import java.util.concurrent.*
+import java.util.concurrent.TimeUnit
 
 /**
  * Benchmark to measure performance of [kotlinx.coroutines.flow.FlowKt.flattenMerge].

Diff for: .idea/copyright/profiles_settings.xml

@@ -11,7 +11,8 @@ import io.reactivex.functions.*
 import kotlinx.coroutines.*
 import kotlinx.coroutines.flow.*
 import org.openjdk.jmh.annotations.*
-import java.util.concurrent.*
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.Callable
 
 @Warmup(iterations = 7, time = 1, timeUnit = TimeUnit.SECONDS)
 @Measurement(iterations = 7, time = 1, timeUnit = TimeUnit.SECONDS)

Diff for: CHANGES.md

@@ -7,7 +7,7 @@ package benchmarks.flow
 import kotlinx.coroutines.*
 import kotlinx.coroutines.flow.*
 import org.openjdk.jmh.annotations.*
-import java.util.concurrent.*
+import java.util.concurrent.TimeUnit
 import java.util.concurrent.CancellationException
 import kotlin.coroutines.*
 import kotlin.coroutines.intrinsics.*

Diff for: README.md

@@ -9,7 +9,7 @@ import kotlinx.coroutines.flow.*
 import org.openjdk.jmh.annotations.*
 import java.lang.Long.max
 import java.util.*
-import java.util.concurrent.*
+import java.util.concurrent.TimeUnit
 import kotlin.math.*
 
 @Warmup(iterations = 7, time = 1, timeUnit = TimeUnit.SECONDS)

Diff for: benchmarks/build.gradle.kts

@@ -9,7 +9,7 @@ import kotlinx.coroutines.flow.*
 import org.openjdk.jmh.annotations.*
 import java.lang.Long.*
 import java.util.*
-import java.util.concurrent.*
+import java.util.concurrent.TimeUnit
 
 @Warmup(iterations = 7, time = 1, timeUnit = TimeUnit.SECONDS)
 @Measurement(iterations = 7, time = 1, timeUnit = TimeUnit.SECONDS)

Diff for: benchmarks/src/jmh/kotlin/benchmarks/flow/FlowFlattenMergeBenchmark.kt

@@ -3,6 +3,7 @@
  */
 import org.jetbrains.kotlin.konan.target.HostManager
 
+apply plugin: 'jdk-convention'
 apply from: rootProject.file("gradle/experimental.gradle")
 
 def rootModule = "kotlinx.coroutines"
@@ -69,7 +70,6 @@ buildscript {
         classpath "org.jetbrains.kotlinx:atomicfu-gradle-plugin:$atomicfu_version"
         classpath "org.jetbrains.kotlinx:kotlinx-knit:$knit_version"
         classpath "com.moowork.gradle:gradle-node-plugin:$gradle_node_version"
-        classpath "org.openjfx:javafx-plugin:$javafx_plugin_version"
         classpath "org.jetbrains.kotlinx:binary-compatibility-validator:$binary_compatibility_validator_version"
 
         // JMH plugins
@@ -264,22 +264,9 @@ configure(subprojects.findAll { !unpublished.contains(it.name) }) {
 // Report Kotlin compiler version when building project
 println("Using Kotlin compiler version: $org.jetbrains.kotlin.config.KotlinCompilerVersion.VERSION")
 
-// --------------- Publish only from under JDK11+ ---------------
-task checkJdkForPublish {
-    doFirst {
-        if (JavaVersionKt.javaVersionMajor < 11) {
-            throw new GradleException("Project can be build for publishing only under JDK 11+, but found ${JavaVersionKt.javaVersion}")
-        }
-    }
-}
-
 // --------------- Configure sub-projects that are published ---------------
 def publishTasks = getTasksByName("publish", true) + getTasksByName("publishNpm", true)
 
-publishTasks.each {
-    it.dependsOn checkJdkForPublish
-}
-
 task deploy(dependsOn: publishTasks)
 
 apply plugin: 'base'

Diff for: benchmarks/src/jmh/kotlin/benchmarks/flow/NumbersBenchmark.kt

@@ -0,0 +1,4 @@
+object Idea {
+    val active: Boolean
+        get() = System.getProperty("idea.active") == "true"
+}

Diff for: benchmarks/src/jmh/kotlin/benchmarks/flow/TakeBenchmark.kt

@@ -0,0 +1,10 @@
+import org.gradle.api.JavaVersion
+
+if (!JavaVersion.current().isJava11Compatible) {
+    val message = "Project required JDK 11+, but found ${JavaVersion.current()}"
+    if (Idea.active) {
+        logger.error(message)
+    } else {
+        throw GradleException(message)
+    }
+}

Diff for: benchmarks/src/jmh/kotlin/benchmarks/flow/scrabble/FlowPlaysScrabbleBase.kt

@@ -3,7 +3,7 @@
 #
 
 # Kotlin
-version=1.3.6-SNAPSHOT
+version=1.3.7-SNAPSHOT
 group=org.jetbrains.kotlinx
 kotlin_version=1.3.71
 

Diff for: benchmarks/src/jmh/kotlin/benchmarks/flow/scrabble/SaneFlowPlaysScrabble.kt

@@ -1,13 +1,16 @@
 /*
  * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
+@file:OptIn(ExperimentalContracts::class)
+
 package kotlinx.coroutines.time
 
 import kotlinx.coroutines.*
 import kotlinx.coroutines.flow.*
 import kotlinx.coroutines.selects.*
 import java.time.*
 import java.time.temporal.*
+import kotlin.contracts.*
 
 /**
  * "java.time" adapter method for [kotlinx.coroutines.delay].
@@ -35,8 +38,12 @@ public fun <R> SelectBuilder<R>.onTimeout(duration: Duration, block: suspend ()
 /**
  * "java.time" adapter method for [kotlinx.coroutines.withTimeout].
  */
-public suspend fun <T> withTimeout(duration: Duration, block: suspend CoroutineScope.() -> T): T =
-        kotlinx.coroutines.withTimeout(duration.coerceToMillis(), block)
+public suspend fun <T> withTimeout(duration: Duration, block: suspend CoroutineScope.() -> T): T {
+    contract {
+        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
+    }
+    return kotlinx.coroutines.withTimeout(duration.coerceToMillis(), block)
+}
 
 /**
  * "java.time" adapter method for [kotlinx.coroutines.withTimeoutOrNull].

Diff for: build.gradle

@@ -214,6 +214,7 @@ public final class kotlinx/coroutines/CoroutineScopeKt {
 	public static synthetic fun cancel$default (Lkotlinx/coroutines/CoroutineScope;Ljava/lang/String;Ljava/lang/Throwable;ILjava/lang/Object;)V
 	public static synthetic fun cancel$default (Lkotlinx/coroutines/CoroutineScope;Ljava/util/concurrent/CancellationException;ILjava/lang/Object;)V
 	public static final fun coroutineScope (Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun currentCoroutineContext (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun ensureActive (Lkotlinx/coroutines/CoroutineScope;)V
 	public static final fun isActive (Lkotlinx/coroutines/CoroutineScope;)Z
 	public static final fun plus (Lkotlinx/coroutines/CoroutineScope;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/CoroutineScope;
@@ -873,6 +874,7 @@ public final class kotlinx/coroutines/flow/FlowKt {
 	public static final fun buffer (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
 	public static synthetic fun buffer$default (Lkotlinx/coroutines/flow/Flow;IILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun callbackFlow (Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun cancellable (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun catch (Lkotlinx/coroutines/flow/Flow;Lkotlin/jvm/functions/Function3;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun channelFlow (Lkotlin/jvm/functions/Function2;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun collect (Lkotlinx/coroutines/flow/Flow;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;