Merge pull request #2904 from Kotlin/version-1.5.2

Version 1.5.2

CHANGES.md

@@ -1,5 +1,15 @@
 # Change log for kotlinx.coroutines
 
+## Version 1.5.2
+
+* Kotlin is updated to 1.5.30.
+* New native targets for Apple Silicon are introduced.
+* Fixed a bug when `onUndeliveredElement` was incorrectly called on a properly received elements on JS (#2826).
+* Fixed `Dispatchers.Default` on React Native, it now fully relies on `setTimeout` instead of stub `process.nextTick`. Thanks to @Legion2 (#2843).
+* Optimizations of `Mutex` implementation (#2581).
+* `Mutex` implementation is made completely lock-free as stated (#2590).
+* Various documentation and guides improvements. Thanks to @MasoodFallahpoor and @Pihanya.
+
 ## Version 1.5.1
 
 * Atomic `update`, `getAndUpdate`, and `updateAndGet` operations of `MutableStateFlow` (#2720).

README.md

@@ -2,12 +2,12 @@
 
 [![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://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.5.1)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.5.1/pom)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.5.20-blue.svg?logo=kotlin)](http://kotlinlang.org)
+[![Download](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.5.2)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core/1.5.2/pom)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.5.30-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 the Kotlin `1.5.20` release.
+This is a companion version for the Kotlin `1.5.30` release.
 
 ```kotlin
 suspend fun main() = coroutineScope {
@@ -83,15 +83,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.5.1</version>
+    <version>1.5.2</version>
 </dependency>
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```xml
 <properties>
-    <kotlin.version>1.5.20</kotlin.version>
+    <kotlin.version>1.5.30</kotlin.version>
 </properties>
 ```
 
@@ -101,15 +101,15 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.1'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2'
 }
 ```
 
 And make sure that you use the latest Kotlin version:
 
 ```groovy
 buildscript {
-    ext.kotlin_version = '1.5.20'
+    ext.kotlin_version = '1.5.30'
 }
 ```
 
@@ -127,7 +127,7 @@ Add dependencies (you can also add other modules that you need):
 
 ```groovy
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.1")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2")
 }
 ```
 
@@ -147,7 +147,7 @@ Add [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android)
 module as a dependency when using `kotlinx.coroutines` on Android:
 
 ```groovy
-implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.1'
+implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2'
 ```
 
 This gives you access to the Android [Dispatchers.Main]
@@ -180,7 +180,7 @@ In common code that should get compiled for different platforms, you can add a d
 ```groovy
 commonMain {
     dependencies {
-        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.1")
+        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2")
     }
 }
 ```
@@ -192,7 +192,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.5.1/jar)
+[`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.5.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

docs/topics/exception-handling.md

@@ -364,6 +364,7 @@ only downwards. This can easily be demonstrated using the following example:
 import kotlinx.coroutines.*
 
 fun main() = runBlocking {
+//sampleStart
     val supervisor = SupervisorJob()
     with(CoroutineScope(coroutineContext + supervisor)) {
         // launch the first child -- its exception is ignored for this example (don't do this in practice!)
@@ -389,8 +390,10 @@ fun main() = runBlocking {
         supervisor.cancel()
         secondChild.join()
     }
+//sampleEnd
 }
 ```
+{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
 > You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt).
 >
@@ -418,6 +421,7 @@ import kotlin.coroutines.*
 import kotlinx.coroutines.*
 
 fun main() = runBlocking {
+//sampleStart
     try {
         supervisorScope {
             val child = launch {
@@ -436,8 +440,10 @@ fun main() = runBlocking {
     } catch(e: AssertionError) {
         println("Caught an assertion error")
     }
+//sampleEnd
 }
 ```
+{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
 > You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt).
 >
@@ -468,6 +474,7 @@ import kotlin.coroutines.*
 import kotlinx.coroutines.*
 
 fun main() = runBlocking {
+//sampleStart
     val handler = CoroutineExceptionHandler { _, exception -> 
         println("CoroutineExceptionHandler got $exception") 
     }
@@ -479,8 +486,10 @@ fun main() = runBlocking {
         println("The scope is completing")
     }
     println("The scope is completed")
+//sampleEnd
 }
 ```
+{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
 > You can get the full code [here](../../kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt).
 >

gradle.properties

@@ -3,14 +3,14 @@
 #
 
 # Kotlin
-version=1.5.1-SNAPSHOT
+version=1.5.2-SNAPSHOT
 group=org.jetbrains.kotlinx
-kotlin_version=1.5.20
+kotlin_version=1.5.30
 
 # Dependencies
 junit_version=4.12
 junit5_version=5.7.0
-atomicfu_version=0.16.2
+atomicfu_version=0.16.3
 knit_version=0.3.0
 html_version=0.7.2
 lincheck_version=2.14
@@ -22,7 +22,7 @@ rxjava2_version=2.2.8
 rxjava3_version=3.0.2
 javafx_version=11.0.2
 javafx_plugin_version=0.0.8
-binary_compatibility_validator_version=0.6.0
+binary_compatibility_validator_version=0.7.0
 blockhound_version=1.0.2.RELEASE
 jna_version=5.5.0
 
@@ -56,3 +56,4 @@ jekyll_version=4.0
 org.gradle.jvmargs=-Xmx4g
 
 kotlin.mpp.enableCompatibilityMetadataVariant=true
+kotlin.mpp.stability.nowarn=true

gradle/compile-native-multiplatform.gradle

@@ -25,6 +25,10 @@ kotlin {
         addTarget(presets.watchosArm64)
         addTarget(presets.watchosX86)
         addTarget(presets.watchosX64)
+        addTarget(presets.iosSimulatorArm64)
+        addTarget(presets.watchosSimulatorArm64)
+        addTarget(presets.tvosSimulatorArm64)
+        addTarget(presets.macosArm64)
     }
 
     sourceSets {

gradle/opt-in.gradle

@@ -3,6 +3,7 @@
  */
 
 ext.optInAnnotations = [
+        "kotlin.RequiresOptIn",
         "kotlin.experimental.ExperimentalTypeInference",
         "kotlin.ExperimentalMultiplatform",
         "kotlinx.coroutines.DelicateCoroutinesApi",

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

@@ -81,6 +81,10 @@ public interface CancellableContinuation<in T> : Continuation<T> {
      * Same as [tryResume] but with [onCancellation] handler that called if and only if the value is not
      * delivered to the caller because of the dispatch in the process, so that atomicity delivery
      * guaranteed can be provided by having a cancellation fallback.
+     *
+     * Implementation note: current implementation always returns RESUME_TOKEN or `null`
+     *
+     * @suppress  **This is unstable API and it is subject to change.**
      */
     @InternalCoroutinesApi
     public fun tryResume(value: T, idempotent: Any?, onCancellation: ((cause: Throwable) -> Unit)?): Any?

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

@@ -21,7 +21,7 @@ public interface CompletableJob : Job {
      *
      * Subsequent invocations of this function have no effect and always produce `false`.
      *
-     * This function transitions this job into _completed- state if it was not completed or cancelled yet.
+     * This function transitions this job into _completed_ state if it was not completed or cancelled yet.
      * However, that if this job has children, then it transitions into _completing_ state and becomes _complete_
      * once all its children are [complete][isCompleted]. See [Job] for details.
      */

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

@@ -49,7 +49,7 @@ import kotlin.coroutines.intrinsics.*
  * * `CoroutineScope()` uses [Dispatchers.Default] for its coroutines.
  * * `MainScope()` uses [Dispatchers.Main] for its coroutines.
  *
- * **The key part of custom usage of `CustomScope` is cancelling it and the end of the lifecycle.**
+ * **The key part of custom usage of `CustomScope` is cancelling it at the end of the lifecycle.**
  * The [CoroutineScope.cancel] extension function shall be used when the entity that was launching coroutines
  * is no longer needed. It cancels all the coroutines that might still be running on behalf of it.
  *
@@ -185,7 +185,7 @@ public val CoroutineScope.isActive: Boolean
  * }
  * ```
  *
- * In top-level code, when launching a concurrent operation operation from a non-suspending context, an appropriately
+ * In top-level code, when launching a concurrent operation from a non-suspending context, an appropriately
  * confined instance of [CoroutineScope] shall be used instead of a `GlobalScope`. See docs on [CoroutineScope] for
  * details.
  *

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

@@ -168,7 +168,7 @@ public interface Job : CoroutineContext.Element {
 
     /**
      * Starts coroutine related to this job (if any) if it was not started yet.
-     * The result `true` if this invocation actually started coroutine or `false`
+     * The result is `true` if this invocation actually started coroutine or `false`
      * if it was already started or completed.
      */
     public fun start(): Boolean

kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt

@@ -136,6 +136,7 @@ internal abstract class AbstractSendChannel<E>(
         return sendSuspend(element)
     }
 
+    @Suppress("DEPRECATION")
     override fun offer(element: E): Boolean {
         // Temporary migration for offer users who rely on onUndeliveredElement
         try {

kotlinx-coroutines-core/common/src/flow/Channels.kt

@@ -171,7 +171,7 @@ private class ChannelAsFlow<T>(
  */
 @Deprecated(
     level = DeprecationLevel.WARNING,
-    message = "'BroadcastChannel' is obsolete and all coreresponding operators are deprecated " +
+    message = "'BroadcastChannel' is obsolete and all corresponding operators are deprecated " +
         "in the favour of StateFlow and SharedFlow"
 ) // Since 1.5.0, was @FlowPreview, safe to remove in 1.7.0
 public fun <T> BroadcastChannel<T>.asFlow(): Flow<T> = flow {
@@ -182,7 +182,7 @@ public fun <T> BroadcastChannel<T>.asFlow(): Flow<T> = flow {
  * ### Deprecated
  *
  * **This API is deprecated.** The [BroadcastChannel] provides a complex channel-like API for hot flows.
- * [SharedFlow] is a easier-to-use and more flow-centric API for the same purposes, so using
+ * [SharedFlow] is an easier-to-use and more flow-centric API for the same purposes, so using
  * [shareIn] operator is preferred. It is not a direct replacement, so please
  * study [shareIn] documentation to see what kind of shared flow fits your use-case. As a rule of thumb:
  *

kotlinx-coroutines-core/common/src/flow/SharedFlow.kt

@@ -469,7 +469,7 @@ private class SharedFlowImpl<T>(
         // outside of the lock: register dispose on cancellation
         emitter?.let { cont.disposeOnCancellation(it) }
         // outside of the lock: resume slots if needed
-        for (cont in resumes) cont?.resume(Unit)
+        for (r in resumes) r?.resume(Unit)
     }
 
     private fun cancelEmitter(emitter: Emitter) = synchronized(this) {

kotlinx-coroutines-core/common/src/flow/operators/Lint.kt

@@ -83,7 +83,8 @@ public val FlowCollector<*>.coroutineContext: CoroutineContext
     get() = noImpl()
 
 @Deprecated(
-    message = "SharedFlow never completes, so this operator has no effect.",
+    message = "SharedFlow never completes, so this operator typically has not effect, it can only " +
+        "catch exceptions from 'onSubscribe' operator",
     level = DeprecationLevel.WARNING,
     replaceWith = ReplaceWith("this")
 )

kotlinx-coroutines-core/common/src/flow/terminal/Collect.kt

@@ -44,7 +44,7 @@ public suspend fun Flow<*>.collect(): Unit = collect(NopCollector)
  *     .launchIn(uiScope)
  * ```
  *
- * Note that resulting value of [launchIn] is not used the provided scope takes care of cancellation.
+ * Note that the resulting value of [launchIn] is not used and the provided scope takes care of cancellation.
  */
 public fun <T> Flow<T>.launchIn(scope: CoroutineScope): Job = scope.launch {
     collect() // tail-call

kotlinx-coroutines-core/common/src/internal/StackTraceRecovery.common.kt

@@ -20,6 +20,7 @@ internal expect fun <E: Throwable> recoverStackTrace(exception: E, continuation:
 /**
  * initCause on JVM, nop on other platforms
  */
+@Suppress("EXTENSION_SHADOWED_BY_MEMBER")
 internal expect fun Throwable.initCause(cause: Throwable)
 
 /**