Merge branch 'master' into develop

Author: qwwdfsad

docs/topics/cancellation-and-timeouts.md

@@ -381,7 +381,7 @@ resource inside the block that needs closing or release outside of the block.
 
 For example, here we imitate a closeable resource with the `Resource` class that simply keeps track of how many times 
 it was created by incrementing the `acquired` counter and decrementing the counter in its `close` function.
-Now let us let us create a lot of coroutines, each of which creates a `Resource` at the end of the `withTimeout` block
+Now let us create a lot of coroutines, each of which creates a `Resource` at the end of the `withTimeout` block
 and releases the resource outside the block. We add a small delay so that it is more likely that the timeout occurs
 right when the `withTimeout` block is already finished, which will cause a resource leak.
 
@@ -398,7 +398,7 @@ class Resource {
 
 fun main() {
     runBlocking {
-        repeat(100_000) { // Launch 100K coroutines
+        repeat(10_000) { // Launch 10K coroutines
             launch { 
                 val resource = withTimeout(60) { // Timeout of 60 ms
                     delay(50) // Delay for 50 ms
@@ -446,7 +446,7 @@ class Resource {
 fun main() {
 //sampleStart
     runBlocking {
-        repeat(100_000) { // Launch 100K coroutines
+        repeat(10_000) { // Launch 10K coroutines
             launch { 
                 var resource: Resource? = null // Not acquired yet
                 try {

docs/topics/coroutines-and-channels.md

@@ -215,7 +215,7 @@ is to use _callbacks_.
 Instead of calling the code that should be invoked right after the operation is completed, you can extract it
 into a separate callback, often a lambda, and pass that lambda to the caller in order for it to be called later.
 
-To make the UI responsive, you can either move the whole computation to a separate thread or switch to the Retrofit API,
+To make the UI responsive, you can either move the whole computation to a separate thread or switch to the Retrofit API
 which uses callbacks instead of blocking calls.
 
 ### Use a background thread
@@ -905,7 +905,7 @@ the parent coroutine.
         req: RequestData
     ): List<User> = coroutineScope {
         // ...
-        GlobalScope.async {
+        async {
             log("starting loading for ${repo.name}")
             delay(3000)
             // load repo contributors

docs/topics/coroutines-guide.md

@@ -1,15 +1,15 @@
 [//]: # (title: Coroutines guide)
 
-Kotlin, as a language, provides only minimal low-level APIs in its standard library to enable various other 
+Kotlin provides only minimal low-level APIs in its standard library to enable other 
 libraries to utilize coroutines. Unlike many other languages with similar capabilities, `async` and `await`
 are not keywords in Kotlin and are not even part of its standard library. Moreover, Kotlin's concept
 of _suspending function_ provides a safer and less error-prone abstraction for asynchronous 
 operations than futures and promises.  
 
 `kotlinx.coroutines` is a rich library for coroutines developed by JetBrains. It contains a number of high-level 
-coroutine-enabled primitives that this guide covers, including `launch`, `async` and others. 
+coroutine-enabled primitives that this guide covers, including `launch`, `async`, and others. 
 
-This is a guide on core features of `kotlinx.coroutines` with a series of examples, divided up into different topics.
+This is a guide about the core features of `kotlinx.coroutines` with a series of examples, divided up into different topics.
 
 In order to use coroutines as well as follow the examples in this guide, you need to add a dependency on the `kotlinx-coroutines-core` module as explained 
 [in the project README](https://github.com/Kotlin/kotlinx.coroutines/blob/master/README.md#using-in-your-projects).

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

@@ -57,15 +57,15 @@ public expect object Dispatchers {
      * ```
      * withContext(Dispatchers.Unconfined) {
      *    println(1)
-     *    withContext(Dispatchers.Unconfined) { // Nested unconfined
+     *    launch(Dispatchers.Unconfined) { // Nested unconfined
      *        println(2)
      *    }
      *    println(3)
      * }
      * println("Done")
      * ```
      * Can print both "1 2 3" and "1 3 2". This is an implementation detail that can be changed.
-     * However, it is guaranteed that "Done" will be printed only when both `withContext` calls are completed.
+     * However, it is guaranteed that "Done" will only be printed once the code in both `withContext` and `launch` completes.
      *
      * If you need your coroutine to be confined to a particular thread or a thread-pool after resumption,
      * but still want to execute it in the current call-frame until its first suspension, you can use

kotlinx-coroutines-core/concurrent/src/channels/Channels.kt

@@ -30,7 +30,7 @@ import kotlin.jvm.*
 public fun <E> SendChannel<E>.trySendBlocking(element: E): ChannelResult<Unit> {
     /*
      * Sent successfully -- bail out.
-     * But failure may indicate either that the channel it full or that
+     * But failure may indicate either that the channel is full or that
      * it is close. Go to slow path on failure to simplify the successful path and
      * to materialize default exception.
      */

kotlinx-coroutines-core/jvm/src/Interruptible.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2016-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package kotlinx.coroutines
@@ -8,7 +8,8 @@ import kotlinx.atomicfu.*
 import kotlin.coroutines.*
 
 /**
- * Calls the specified [block] with a given coroutine context in an interruptible manner.
+ * Calls the specified [block] with a given coroutine context in
+ * [an interruptible manner](https://docs.oracle.com/javase/tutorial/essential/concurrency/interrupt.html).
  * The blocking code block will be interrupted and this function will throw [CancellationException]
  * if the coroutine is cancelled.
  *

kotlinx-coroutines-core/jvm/test/guide/example-cancel-09.kt

@@ -16,7 +16,7 @@ class Resource {
 
 fun main() {
     runBlocking {
-        repeat(100_000) { // Launch 100K coroutines
+        repeat(10_000) { // Launch 10K coroutines
             launch { 
                 val resource = withTimeout(60) { // Timeout of 60 ms
                     delay(50) // Delay for 50 ms

kotlinx-coroutines-core/jvm/test/guide/example-cancel-10.kt

@@ -16,7 +16,7 @@ class Resource {
 
 fun main() {
     runBlocking {
-        repeat(100_000) { // Launch 100K coroutines
+        repeat(10_000) { // Launch 10K coroutines
             launch { 
                 var resource: Resource? = null // Not acquired yet
                 try {