Version 1.4.0-M1

CHANGES.md

@@ -1,5 +1,36 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.4.0-M1
+
+### Breaking changes
+
+* The concept of atomic cancellation in channels is removed. All operations in channels
+    and corresponding `Flow` operators are cancellable in non-atomic way (#1813).
+* If `CoroutineDispatcher` throws `RejectedExecutionException`, cancel current `Job` and schedule its execution to `Dispatchers.IO` (#2003).
+* `CancellableContinuation.invokeOnCancellation` is invoked if the continuation was cancelled while its resume has been dispatched (#1915).
+* `Flow.singleOrNull` operator is aligned with standard library and does not longer throw `IllegalStateException` on multiple values (#2289). 
+
+### New experimental features
+
+* `SharedFlow` primitive for managing hot sources of events with support of various subscription mechanisms, replay logs and buffering (#2034).
+* `Flow.shareIn` and `Flow.stateIn` operators to transform cold instances of flow to hot `SharedFlow` and `StateFlow` respectively (#2047).
+
+### Other
+
+* Support leak-free closeable resources transfer via `onUndeliveredElement` in channels (#1936).
+* Changed ABI in reactive integrations for Java interoperability (#2182).
+* Fixed ProGuard rules for `kotlinx-coroutines-core` (#2046, #2266).
+* Lint settings were added to `Flow` to avoid accidental capturing of outer `CoroutineScope` for cancellation check (#2038). 
+
+### External contributions
+
+* Allow nullable types in `Flow.firstOrNull` and `Flow.singleOrNull` by @ansman (#2229).
+* Add `Publisher.awaitSingleOrDefault|Null|Else` extensions by @sdeleuze (#1993).
+* `awaitCancellation` top-level function by @LouisCAD (#2213).
+* Significant part of our Gradle build scripts were migrated to `.kts` by @turansky. 
+
+Thank you for your contributions and participation in the Kotlin community!
+
 ## Version 1.3.9
 
 * Support of `CoroutineContext` in `Flow.asPublisher` and similar reactive builders (#2155).

README.md

@@ -2,7 +2,9 @@
 
 [![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.9) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.3.9)
+[![Download](https://api.bintray.com/packages/kotlin/kotlinx/kotlinx.coroutines/images/download.svg?version=1.4.0-M1) ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/1.4.0-M1)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.4.0-blue.svg?logo=kotlin)](http://kotlinlang.org)
+[![Slack channel](https://img.shields.io/badge/chat-slack-green.svg?logo=slack)](https://kotlinlang.slack.com/messages/coroutines/)
 
 Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
 This is a companion version for Kotlin `1.4.0` release.
@@ -44,7 +46,7 @@ suspend fun main() = coroutineScope {
   * [DebugProbes] API to probe, keep track of, print and dump active coroutines;
   * [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 ([Publisher.collect], [Publisher.awaitSingle], [publish], etc), 
+  * Reactive Streams ([Publisher.collect], [Publisher.awaitSingle], [kotlinx.coroutines.reactive.publish], etc), 
   * Flow (JDK 9) (the same interface as for Reactive Streams),
   * RxJava 2.x ([rxFlowable], [rxSingle], etc), and
   * RxJava 3.x ([rxFlowable], [rxSingle], etc), and
@@ -84,7 +86,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.9</version>
+    <version>1.4.0-M1</version>
 </dependency>
 ```
 
@@ -102,7 +104,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.9'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0-M1'
 }
 ```
 
@@ -128,7 +130,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.9")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0-M1")
 }
 ```
 
@@ -150,7 +152,7 @@ In common code that should get compiled for different platforms, you can add dep
 ```groovy
 commonMain {
     dependencies {
-        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.9")
+        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0-M1")
     }
 }
 ```
@@ -161,7 +163,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.9'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.0-M1'
 ```
 
 This gives you access to Android [Dispatchers.Main]
@@ -174,18 +176,29 @@ threads are handled by Android runtime.
 R8 and ProGuard rules are bundled into the [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android) module.
 For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-android/README.md#optimization). 
 
+#### Avoiding including the debug infrastructure in the resulting APK
+
+The `kotlinx-coroutines-core` artifact contains a resource file that is not required for the coroutines to operate
+normally and is only used by the debugger. To exclude it at no loss of functionality, add the following snippet to the
+`android` block in your gradle file for the application subproject:
+```groovy
+packagingOptions {
+  exclude "DebugProbesKt.bin"
+}
+```
+
 ### 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.9/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.4.0-M1/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.9/jar)
+[`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.4.0-M1/jar)
 (follow the link to get the dependency declaration snippet).
 
 Only single-threaded code (JS-style) on Kotlin/Native is currently supported. 
@@ -263,7 +276,7 @@ See [Contributing Guidelines](CONTRIBUTING.md).
 <!--- INDEX kotlinx.coroutines.reactive -->
 [Publisher.collect]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/collect.html
 [Publisher.awaitSingle]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/org.reactivestreams.-publisher/await-single.html
-[publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
+[kotlinx.coroutines.reactive.publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.reactive/publish.html
 <!--- MODULE kotlinx-coroutines-rx2 -->
 <!--- INDEX kotlinx.coroutines.rx2 -->
 [rxFlowable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.rx2/rx-flowable.html

RELEASE.md

@@ -64,18 +64,14 @@ To release new `<version>` of `kotlinx-coroutines`:
 
 5. Announce new release in [Slack](https://kotlinlang.slack.com)   
 
-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>
+6. Switch into `develop` branch:<br>
    `git checkout develop`
 
-8. Fetch the latest `master`:<br>
+7. Fetch the latest `master`:<br>
    `git fetch` 
 
-9. Merge release from `master`:<br>
+8. Merge release from `master`:<br>
    `git merge origin/master`
 
-0. Push updates to `develop`:<br>
+9. Push updates to `develop`:<br>
    `git push`      

benchmarks/build.gradle.kts

@@ -2,6 +2,8 @@
  * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+@file:Suppress("UnstableApiUsage")
+
 import me.champeau.gradle.*
 import org.jetbrains.kotlin.gradle.tasks.*
 
@@ -33,7 +35,7 @@ tasks.named<KotlinCompile>("compileJmhKotlin") {
  * Due to a bug in the inliner it sometimes does not remove inlined symbols (that are later renamed) from unused code paths,
  * and it breaks JMH that tries to post-process these symbols and fails because they are renamed.
  */
-val removeRedundantFiles = tasks.register<Delete>("removeRedundantFiles") {
+val removeRedundantFiles by tasks.registering(Delete::class) {
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$buildHistoOnScore\$1\$\$special\$\$inlined\$filter\$1\$1.class")
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$nBlanks\$1\$\$special\$\$inlined\$map\$1\$1.class")
     delete("$buildDir/classes/kotlin/jmh/benchmarks/flow/scrabble/FlowPlaysScrabbleOpt\$play\$score2\$1\$\$special\$\$inlined\$map\$1\$1.class")
@@ -71,10 +73,10 @@ extensions.configure<JMHPluginExtension>("jmh") {
 }
 
 tasks.named<Jar>("jmhJar") {
-    baseName = "benchmarks"
-    classifier = null
-    version = null
-    destinationDir = file("$rootDir")
+    archiveBaseName by "benchmarks"
+    archiveClassifier by null
+    archiveVersion by null
+    destinationDirectory.file("$rootDir")
 }
 
 dependencies {

benchmarks/src/jmh/kotlin/benchmarks/tailcall/SimpleChannel.kt

@@ -70,12 +70,12 @@ class NonCancellableChannel : SimpleChannel() {
 }
 
 class CancellableChannel : SimpleChannel() {
-    override suspend fun suspendReceive(): Int = suspendAtomicCancellableCoroutine {
+    override suspend fun suspendReceive(): Int = suspendCancellableCoroutine {
         consumer = it.intercepted()
         COROUTINE_SUSPENDED
     }
 
-    override suspend fun suspendSend(element: Int) = suspendAtomicCancellableCoroutine<Unit> {
+    override suspend fun suspendSend(element: Int) = suspendCancellableCoroutine<Unit> {
         enqueuedValue = element
         producer = it.intercepted()
         COROUTINE_SUSPENDED
@@ -84,13 +84,13 @@ class CancellableChannel : SimpleChannel() {
 
 class CancellableReusableChannel : SimpleChannel() {
     @Suppress("INVISIBLE_MEMBER")
-    override suspend fun suspendReceive(): Int = suspendAtomicCancellableCoroutineReusable {
+    override suspend fun suspendReceive(): Int = suspendCancellableCoroutineReusable {
         consumer = it.intercepted()
         COROUTINE_SUSPENDED
     }
 
     @Suppress("INVISIBLE_MEMBER")
-    override suspend fun suspendSend(element: Int) = suspendAtomicCancellableCoroutineReusable<Unit> {
+    override suspend fun suspendSend(element: Int) = suspendCancellableCoroutineReusable<Unit> {
         enqueuedValue = element
         producer = it.intercepted()
         COROUTINE_SUSPENDED

build.gradle

@@ -46,7 +46,6 @@ buildscript {
     if (using_snapshot_version) {
         repositories {
             mavenLocal()
-            maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
         }
     }
 
@@ -59,6 +58,8 @@ buildscript {
                 password = project.hasProperty('bintrayApiKey') ? project.property('bintrayApiKey') : System.getenv('BINTRAY_API_KEY') ?: ""
             }
         }
+        // Future replacement for kotlin-dev, with cache redirector
+        maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
         maven {
             url "https://kotlin.bintray.com/kotlin-dev"
             credentials {
@@ -82,12 +83,14 @@ buildscript {
         // JMH plugins
         classpath "com.github.jengelman.gradle.plugins:shadow:5.1.0"
     }
+
+    CacheRedirector.configureBuildScript(buildscript, rootProject)
 }
 
 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")) {
+// todo:KLUDGE: Hierarchical project structures are not fully supported in IDEA, enable only for a regular built
+if (!Idea.active) {
     ext.set("kotlin.mpp.enableGranularSourceSetsMetadata", "true")
 }
 
@@ -145,14 +148,15 @@ apiValidation {
 
 // Configure repositories
 allprojects {
-    String projectName = it.name
     repositories {
         /*
          * google should be first in the repository list because some of the play services
          * transitive dependencies was removed from jcenter, thus breaking gradle dependency resolution
          */
         google()
         jcenter()
+        // Future replacement for kotlin-dev, with cache redirector
+        maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
         maven {
             url "https://kotlin.bintray.com/kotlin-dev"
             credentials {
@@ -250,7 +254,14 @@ configure(subprojects.findAll { it.name != coreModule && it.name != rootModule }
 }
 
 // Redefine source sets because we are not using 'kotlin/main/fqn' folder convention
-configure(subprojects.findAll { !sourceless.contains(it.name) && it.name != "benchmarks" && it.name != coreModule }) {
+configure(subprojects.findAll {
+    !sourceless.contains(it.name) &&
+            it.name != "benchmarks" &&
+            it.name != coreModule &&
+            it.name != "example-frontend-js"
+}) {
+    // Pure JS and pure MPP doesn't have this notion and are configured separately
+    // TODO detect it via platformOf and migrate benchmarks to the same scheme
     sourceSets {
         main.kotlin.srcDirs = ['src']
         test.kotlin.srcDirs = ['test']
@@ -286,7 +297,14 @@ 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")
 
+// --------------- Cache redirector ---------------
+
+allprojects {
+    CacheRedirector.configure(project)
+}
+
 // --------------- Configure sub-projects that are published ---------------
+
 def publishTasks = getTasksByName("publish", true) + getTasksByName("publishNpm", true)
 
 task deploy(dependsOn: publishTasks)

buildSrc/build.gradle.kts

@@ -1,11 +1,39 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import java.util.*
+
 plugins {
     `kotlin-dsl`
 }
 
+val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
+
 repositories {
-    gradlePluginPortal()
+    if (cacheRedirectorEnabled) {
+        maven("https://cache-redirector.jetbrains.com/plugins.gradle.org/m2")
+        maven("https://cache-redirector.jetbrains.com/dl.bintray.com/kotlin/kotlin-eap")
+        maven("https://cache-redirector.jetbrains.com/dl.bintray.com/kotlin/kotlin-dev")
+    } else {
+        maven("https://plugins.gradle.org/m2")
+        maven("https://dl.bintray.com/kotlin/kotlin-eap")
+        maven("https://dl.bintray.com/kotlin/kotlin-dev")
+    }
 }
 
 kotlinDslPluginOptions {
     experimentalWarning.set(false)
 }
+
+val props = Properties().apply {
+    file("../gradle.properties").inputStream().use { load(it) }
+}
+
+fun version(target: String): String =
+    props.getProperty("${target}_version")
+
+dependencies {
+    implementation(kotlin("gradle-plugin", version("kotlin")))
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:${version("dokka")}")
+}

buildSrc/settings.gradle.kts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+pluginManagement {
+    repositories {
+        val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
+
+        if (cacheRedirectorEnabled) {
+            println("Redirecting repositories for buildSrc buildscript")
+
+            maven("https://cache-redirector.jetbrains.com/plugins.gradle.org/m2")
+        } else {
+            maven("https://plugins.gradle.org/m2")
+        }
+    }
+}