Merge pull request #3304 from Kotlin/version-1.6.2

Version 1.6.2

.gitignore

@@ -12,3 +12,4 @@ build
 out
 target
 local.properties
+/kotlin-js-store

CHANGES.md

@@ -1,5 +1,15 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.6.2
+
+* Fixed a bug with `ThreadLocalElement` not being correctly updated when the most outer `suspend` function was called directly without `kotlinx.coroutines` (#2930).
+* Fixed multiple data races: one that might have been affecting `runBlocking` event loop, and a benign data race in `Mutex` (#3250, #3251).
+* Obsolete `TestCoroutineContext` is removed, which fixes the `kotlinx-coroutines-test` JPMS package being split between `kotlinx-coroutines-core` and `kotlinx-coroutines-test` (#3218).
+* Updated the ProGuard rules to further shrink the size of the resulting DEX file with coroutines (#3111, #3263). Thanks, @agrieve!
+* Atomicfu is updated to `0.17.2`, which includes a more efficient and robust JS IR transformer (#3255).
+* Kotlin is updated to `1.6.21`, Gradle version is updated to `7.4.2` (#3281). Thanks, @wojtek-kalicinski!
+* Various documentation improvements.
+
 ## Version 1.6.1
 
 * Rollback of time-related functions dispatching on `Dispatchers.Main`.

README.md

@@ -3,7 +3,7 @@
 [![Kotlin Stable](https://kotl.in/badges/stable.svg)](https://kotlinlang.org/docs/components-stability.html)
 [![JetBrains official 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://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.6.1)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.6.1/pom)
+[![Download](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.6.2)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.6.2/pom)
 [![Kotlin](https://img.shields.io/badge/kotlin-1.6.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/)
 
@@ -62,9 +62,9 @@ suspend fun main() = coroutineScope {
 ## Documentation
 
 * Presentations and videos:
-  * [Introduction to Coroutines](https://www.youtube.com/watch?v=_hfBv0a09Jc) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/introduction-to-coroutines-kotlinconf-2017))
-  * [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))
+  * [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))
+  * [History of Structured Concurrency in Coroutines](https://www.youtube.com/watch?v=Mj5P47F6nJg) (Roman Elizarov at Hydra 2019, [slides](https://speakerdeck.com/elizarov/structured-concurrency))
 * Guides and manuals: 
   * [Guide to kotlinx.coroutines by example](https://kotlinlang.org/docs/coroutines-guide.html) (**read it first**)
   * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
@@ -84,15 +84,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.6.1</version>
+    <version>1.6.2</version>
 </dependency>
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```xml
 <properties>
-    <kotlin.version>1.6.0</kotlin.version>
+    <kotlin.version>1.6.20</kotlin.version>
 </properties>
 ```
 
@@ -102,7 +102,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```kotlin
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.1")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.2")
 }
 ```
 
@@ -111,10 +111,10 @@ And make sure that you use the latest Kotlin version:
 ```kotlin
 plugins {
     // For build.gradle.kts (Kotlin DSL)
-    kotlin("jvm") version "1.6.0"
+    kotlin("jvm") version "1.6.20"
 
     // For build.gradle (Groovy DSL)
-    id "org.jetbrains.kotlin.jvm" version "1.6.0"
+    id "org.jetbrains.kotlin.jvm" version "1.6.20"
 }
 ```
 
@@ -132,7 +132,7 @@ Add [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android)
 module as a dependency when using `kotlinx.coroutines` on Android:
 
 ```kotlin
-implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.1")
+implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.2")
 ```
 
 This gives you access to the Android [Dispatchers.Main]
@@ -167,7 +167,7 @@ In common code that should get compiled for different platforms, you can add a d
 ```kotlin
 commonMain {
     dependencies {
-        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.1")
+        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.2")
     }
 }
 ```
@@ -179,7 +179,7 @@ Platform-specific dependencies are recommended to be used only for non-multiplat
 #### JS
 
 Kotlin/JS version of `kotlinx.coroutines` is published as 
-[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.6.1/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.6.2/jar)
 (follow the link to get the dependency declaration snippet) and as [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) NPM package. 
 
 #### Native

benchmarks/build.gradle.kts

@@ -8,7 +8,6 @@ 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") apply false
 }
@@ -31,8 +30,6 @@ tasks.named<KotlinCompile>("compileJmhKotlin") {
     }
 }
 
-
-
 // It is better to use the following to run benchmarks, otherwise you may get unexpected errors:
 // ./gradlew --no-daemon cleanJmhJar jmh -Pjmh="MyBenchmark"
 extensions.configure<JMHPluginExtension>("jmh") {
@@ -54,6 +51,12 @@ val jmhJarTask = tasks.named<Jar>("jmhJar") {
 }
 
 tasks {
+    // For some reason the DuplicatesStrategy from jmh is not enough
+    // and errors with duplicates appear unless I force it to WARN only:
+    withType<Copy> {
+        duplicatesStrategy = DuplicatesStrategy.WARN
+    }
+
     build {
         dependsOn(jmhJarTask)
     }

benchmarks/src/jmh/kotlin/benchmarks/ParametrizedDispatcherBase.kt

@@ -25,7 +25,6 @@ abstract class ParametrizedDispatcherBase : CoroutineScope {
     private var closeable: Closeable? = null
 
     @Setup
-    @UseExperimental(InternalCoroutinesApi::class)
     open fun setup() {
         coroutineContext = when {
             dispatcher == "fjp" -> ForkJoinPool.commonPool().asCoroutineDispatcher()

build.gradle

@@ -54,13 +54,13 @@ buildscript {
         classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
         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 "com.github.node-gradle:gradle-node-plugin:$gradle_node_version"
         classpath "org.jetbrains.kotlinx:binary-compatibility-validator:$binary_compatibility_validator_version"
-        classpath "ru.vyarus:gradle-animalsniffer-plugin:1.5.3" // Android API check
+        classpath "ru.vyarus:gradle-animalsniffer-plugin:1.5.4" // Android API check
         classpath "org.jetbrains.kotlinx:kover:$kover_version"
 
         // JMH plugins
-        classpath "com.github.jengelman.gradle.plugins:shadow:5.1.0"
+        classpath "gradle.plugin.com.github.johnrengelman:shadow:7.1.2"
     }
 
     CacheRedirector.configureBuildScript(buildscript, rootProject)
@@ -130,6 +130,9 @@ allprojects {
     }
 }
 
+// needs to be before evaluationDependsOn due to weird Gradle ordering
+apply plugin: "animalsniffer-conventions"
+
 // Add dependency to core source sets. Core is configured in kx-core/build.gradle
 configure(subprojects.findAll { !sourceless.contains(it.name) && it.name != coreModule }) {
     evaluationDependsOn(":$coreModule")
@@ -232,7 +235,7 @@ def core_docs_url = "https://kotlin.github.io/kotlinx.coroutines/$coreModule/"
 def core_docs_file = "$projectDir/kotlinx-coroutines-core/build/dokka/htmlPartial/package-list"
 apply plugin: "org.jetbrains.dokka"
 
-configure(subprojects.findAll { !unpublished.contains(it.name) }) {
+configure(subprojects.findAll { !unpublished.contains(it.name) && it.name != coreModule }) {
     if (it.name != 'kotlinx-coroutines-bom') {
         apply from: rootProject.file('gradle/dokka.gradle.kts')
     }
@@ -303,8 +306,6 @@ def publishTasks = getTasksByName("publish", true) + getTasksByName("publishNpm"
 
 task deploy(dependsOn: publishTasks)
 
-apply plugin: "animalsniffer-conventions"
-
 clean.dependsOn gradle.includedBuilds.collect { it.task(':clean') }
 
 // --------------- Knit configuration ---------------

buildSrc/src/main/kotlin/Publishing.kt

@@ -7,6 +7,7 @@
 import org.gradle.api.Project
 import org.gradle.api.artifacts.dsl.*
 import org.gradle.api.publish.maven.*
+import org.gradle.kotlin.dsl.*
 import org.gradle.plugins.signing.*
 import java.net.*
 
@@ -56,6 +57,11 @@ fun configureMavenPublication(rh: RepositoryHandler, project: Project) {
             password = project.getSensitiveProperty("libs.sonatype.password")
         }
     }
+
+    // Something that's easy to "clean" for development, not mavenLocal
+    rh.maven("${project.rootProject.buildDir}/repo") {
+        name = "buildRepo"
+    }
 }
 
 fun signPublicationIfKeyPresent(project: Project, publication: MavenPublication) {

buildSrc/src/main/kotlin/animalsniffer-conventions.gradle.kts

@@ -4,17 +4,19 @@
 
 import ru.vyarus.gradle.plugin.animalsniffer.*
 
-subprojects {
+configure(subprojects) {
     // Skip JDK 8 projects or unpublished ones
-    if (!shouldSniff()) return@subprojects
+    if (!shouldSniff()) return@configure
     apply(plugin = "ru.vyarus.animalsniffer")
-    configure<AnimalSnifferExtension> {
-        sourceSets = listOf((project.extensions.getByName("sourceSets") as SourceSetContainer).getByName("main"))
-    }
-    val signature: Configuration by configurations
-    dependencies {
-        signature("net.sf.androidscents.signature:android-api-level-14:4.0_r4@signature")
-        signature("org.codehaus.mojo.signature:java17:1.0@signature")
+    project.plugins.withType(JavaPlugin::class.java) {
+        configure<AnimalSnifferExtension> {
+            sourceSets = listOf((project.extensions.getByName("sourceSets") as SourceSetContainer).getByName("main"))
+        }
+        val signature: Configuration by configurations
+        dependencies {
+            signature("net.sf.androidscents.signature:android-api-level-14:4.0_r4@signature")
+            signature("org.codehaus.mojo.signature:java17:1.0@signature")
+        }
     }
 }
 

docs/topics/cancellation-and-timeouts.md

@@ -103,6 +103,42 @@ job: I'm sleeping 4 ...
 main: Now I can quit.
 -->
 
+The same problem can be observed by catching a [CancellationException] and not rethrowing it:
+
+```kotlin
+import kotlinx.coroutines.*
+
+fun main() = runBlocking {
+//sampleStart
+    val job = launch(Dispatchers.Default) {
+        repeat(5) { i ->
+            try {
+                // print a message twice a second
+                println("job: I'm sleeping $i ...")
+                delay(500)
+            } catch (e: Exception) {
+                // log the exception
+                println(e)
+            }
+        }
+    }
+    delay(1300L) // delay a bit
+    println("main: I'm tired of waiting!")
+    job.cancelAndJoin() // cancels the job and waits for its completion
+    println("main: Now I can quit.")
+//sampleEnd    
+}
+```
+{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
+
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
+>
+{type="note"}
+
+While catching `Exception` is an anti-pattern, this issue may surface in more subtle ways, like when using the
+[`runCatching`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run-catching.html) function,
+which does not know rethrow [CancellationException].
+
 ## Making computation code cancellable
 
 There are two approaches to making computation code cancellable. The first one is to periodically 
@@ -137,7 +173,7 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
 >
 {type="note"}
 
@@ -182,7 +218,7 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
 >
 {type="note"}
 
@@ -237,7 +273,7 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt).
 >
 {type="note"}
 
@@ -275,7 +311,7 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt).
 >
 {type="note"}
 
@@ -318,7 +354,7 @@ fun main() = runBlocking {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt).
 >
 {type="note"}
 
@@ -378,7 +414,7 @@ fun main() {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-08.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt).
 >
 {type="note"}
 
@@ -431,7 +467,7 @@ fun main() {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt).
+> You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt).
 >
 {type="note"}
 

docs/topics/coroutine-context-and-dispatchers.md

@@ -334,8 +334,8 @@ fun main() = runBlocking<Unit> {
     }
     delay(500)
     request.cancel() // cancel processing of the request
-    delay(1000) // delay a second to see what happens
     println("main: Who has survived request cancellation?")
+    delay(1000) // delay the main thread for a second to see what happens
 //sampleEnd
 }
 ```
@@ -350,8 +350,8 @@ The output of this code is:
 ```text
 job1: I run in my own Job and execute independently!
 job2: I am a child of the request coroutine
-job1: I am not affected by cancellation of the request
 main: Who has survived request cancellation?
+job1: I am not affected by cancellation of the request
 ```
 
 <!--- TEST -->