Merge branch 'master' into develop

README.md

@@ -135,7 +135,7 @@ And make sure that you use the latest Kotlin version:
 
 ```groovy
 plugins {
- kotlin("jvm") version "1.5.20"
+ kotlin("jvm") version "1.5.30"
 }
 ```
 

docs/topics/cancellation-and-timeouts.md

@@ -388,7 +388,7 @@ If you run the above code you'll see that it does not always print zero, though
 of your machine you may need to tweak timeouts in this example to actually see non-zero values. 
 
 > Note, that incrementing and decrementing `acquired` counter here from 100K coroutines is completely safe,
-> since it always happens from the same main thread. More on that will be explained in the next chapter
+> since it always happens from the same main thread. More on that will be explained in the chapter
 > on coroutine context.
 > 
 {type="note"}

docs/topics/coroutines-basics.md

@@ -75,7 +75,7 @@ Coroutines follow a principle of
 which delimits the lifetime of the coroutine. The above example shows that [runBlocking] establishes the corresponding
 scope and that is why the previous example waits until `World!` is printed after a second's delay and only then exits.
 
-In the real application, you will be launching a lot of coroutines. Structured concurrency ensures that they are not
+In a real application, you will be launching a lot of coroutines. Structured concurrency ensures that they are not
 lost and do not leak. An outer scope cannot complete until all its children coroutines complete. 
 Structured concurrency also ensures that any errors in the code are properly reported and are never lost. 
 

docs/topics/exception-handling.md

@@ -15,7 +15,7 @@ When these builders are used to create a _root_ coroutine, that is not a _child_
 the former builders treat exceptions as **uncaught** exceptions, similar to Java's `Thread.uncaughtExceptionHandler`,
 while the latter are relying on the user to consume the final
 exception, for example via [await][Deferred.await] or [receive][ReceiveChannel.receive] 
-([produce] and [receive][ReceiveChannel.receive] are covered later in [Channels](https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/channels.md) section).
+([produce] and [receive][ReceiveChannel.receive] are covered in [Channels](https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/channels.md) section).
 
 It can be demonstrated by a simple example that creates root coroutines using the [GlobalScope]:
 
@@ -68,7 +68,7 @@ Caught ArithmeticException
 ## CoroutineExceptionHandler
 
 It is possible to customize the default behavior of printing **uncaught** exceptions to the console.
-[CoroutineExceptionHandler] context element on a _root_ coroutine can be used as generic `catch` block for
+[CoroutineExceptionHandler] context element on a _root_ coroutine can be used as a generic `catch` block for
 this root coroutine and all its children where custom exception handling may take place.
 It is similar to [`Thread.uncaughtExceptionHandler`](https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler)).
 You cannot recover from the exception in the `CoroutineExceptionHandler`. The coroutine had already completed
@@ -349,7 +349,7 @@ hierarchy of coroutines. Let us take a look at the case when unidirectional canc
 
 A good example of such a requirement is a UI component with the job defined in its scope. If any of the UI's child tasks
 have failed, it is not always necessary to cancel (effectively kill) the whole UI component,
-but if UI component is destroyed (and its job is cancelled), then it is necessary to fail all child jobs as their results are no longer needed.
+but if the UI component is destroyed (and its job is cancelled), then it is necessary to cancel all child jobs as their results are no longer needed.
 
 Another example is a server process that spawns multiple child jobs and needs to _supervise_
 their execution, tracking their failures and only restarting the failed ones.

docs/topics/select-expression.md

@@ -213,7 +213,7 @@ Channel 'a' is closed
 
 <!--- TEST -->
 
-There are couple of observations to make out of it. 
+There are a couple of observations to make out of it. 
 
 First of all, `select` is _biased_ to the first clause. When several clauses are selectable at the same time, 
 the first one among them gets selected. Here, both channels are constantly producing strings, so `a` channel,
@@ -228,7 +228,7 @@ channel is already closed.
 Select expression has [onSend][SendChannel.onSend] clause that can be used for a great good in combination 
 with a biased nature of selection.
 
-Let us write an example of producer of integers that sends its values to a `side` channel when 
+Let us write an example of a producer of integers that sends its values to a `side` channel when 
 the consumers on its primary channel cannot keep up with it:
 
 ```kotlin

docs/topics/shared-mutable-state-and-concurrency.md

@@ -9,7 +9,7 @@ but others are unique.
 
 ## The problem
 
-Let us launch a hundred coroutines all doing the same action thousand times. 
+Let us launch a hundred coroutines all doing the same action a thousand times. 
 We'll also measure their completion time for further comparisons:
 
 ```kotlin
@@ -384,7 +384,7 @@ single reference to the actor can be carried around as its handle.
 The first step of using an actor is to define a class of messages that an actor is going to process.
 Kotlin's [sealed classes](https://kotlinlang.org/docs/reference/sealed-classes.html) are well suited for that purpose.
 We define `CounterMsg` sealed class with `IncCounter` message to increment a counter and `GetCounter` message
-to get its value. The later needs to send a response. A [CompletableDeferred] communication
+to get its value. The latter needs to send a response. A [CompletableDeferred] communication
 primitive, that represents a single value that will be known (communicated) in the future,
 is used here for that purpose.
 

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

@@ -182,7 +182,11 @@ public fun <T> BroadcastChannel<T>.asFlow(): Flow<T> = flow {
  * Creates a [produce] coroutine that collects the given flow.
  *
  * This transformation is **stateful**, it launches a [produce] coroutine
- * that collects the given flow and thus resulting channel should be properly closed or cancelled.
+ * that collects the given flow, and has the same behavior:
+ *
+ * * if collecting the flow throws, the channel will be closed with that exception
+ * * if the [ReceiveChannel] is cancelled, the collection of the flow will be cancelled
+ * * if collecting the flow completes normally, the [ReceiveChannel] will be closed normally
  *
  * A channel with [default][Channel.Factory.BUFFERED] buffer size is created.
  * Use [buffer] operator on the flow before calling `produceIn` to specify a value other than

reactive/kotlinx-coroutines-rx2/src/RxCompletable.kt

@@ -20,7 +20,7 @@ public fun rxCompletable(
  context: CoroutineContext = EmptyCoroutineContext,
  block: suspend CoroutineScope.() -> Unit
 ): Completable {
- require(context[Job] === null) { "Completable context cannot contain job in it." +
+ require(context[Job] === null) { "Completable context cannot contain job in it. " +
  "Its lifecycle should be managed via Disposable handle. Had $context" }
  return rxCompletableInternal(GlobalScope, context, block)
 }