Merge remote-tracking branch 'origin/master' into develop

Author: elizarov

CHANGES.md

@@ -215,7 +215,7 @@ Visible consequences of include more robust exception handling for large corouti
 * Distribution no longer uses multi-version jar which is not supported on Android (see #510).
 * JS version of the library does not depend on AtomicFu anymore:
   All the atomic boxes in JS are fully erased.
-* Note, that versions 0.25.1-2 are skipped for technical reasons (they were not fully released).
+* Note that versions 0.25.1-2 are skipped for technical reasons (they were not fully released).
 
 ## Version 0.25.0
 

RELEASE.md

@@ -50,7 +50,7 @@ To release new `<version>` of `kotlinx-coroutines`:
    * Run "Deploy (Configure, RUN THIS ONE)" configuration with the corresponding new version.    
 
 2. In [GitHub](https://github.com/kotlin/kotlinx.coroutines) interface:
-   * Create new release named as `<version>`. 
+   * Create a release named `<version>`. 
    * Cut & paste lines from [`CHANGES.md`](CHANGES.md) into description.    
 
 3. Build and publish documentation for web-site: <br>

docs/basics.md

@@ -47,7 +47,7 @@ Run the following code:
 import kotlinx.coroutines.*
 
 fun main() {
-    GlobalScope.launch { // launch new coroutine in background and continue
+    GlobalScope.launch { // launch a new coroutine in background and continue
         delay(1000L) // non-blocking delay for 1 second (default time unit is ms)
         println("World!") // print after delay
     }
@@ -58,7 +58,7 @@ fun main() {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-01.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-01.kt).
 
 You will see the following result:
 
@@ -98,7 +98,7 @@ Let's be explicit about blocking using [runBlocking] coroutine builder:
 import kotlinx.coroutines.*
 
 fun main() { 
-    GlobalScope.launch { // launch new coroutine in background and continue
+    GlobalScope.launch { // launch a new coroutine in background and continue
         delay(1000L)
         println("World!")
     }
@@ -111,15 +111,15 @@ fun main() {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-02.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-02.kt).
 
 <!--- TEST
 Hello,
 World!
 -->
 
 The result is the same, but this code uses only non-blocking [delay]. 
-The main thread, that invokes `runBlocking`, _blocks_ until the coroutine inside `runBlocking` completes. 
+The main thread invoking `runBlocking` _blocks_ until the coroutine inside `runBlocking` completes. 
 
 This example can be also rewritten in a more idiomatic way, using `runBlocking` to wrap 
 the execution of the main function:
@@ -130,7 +130,7 @@ the execution of the main function:
 import kotlinx.coroutines.*
 
 fun main() = runBlocking<Unit> { // start main coroutine
-    GlobalScope.launch { // launch new coroutine in background and continue
+    GlobalScope.launch { // launch a new coroutine in background and continue
         delay(1000L)
         println("World!")
     }
@@ -141,7 +141,7 @@ fun main() = runBlocking<Unit> { // start main coroutine
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-02b.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-02b.kt).
 
 <!--- TEST
 Hello,
@@ -151,7 +151,7 @@ World!
 Here `runBlocking<Unit> { ... }` works as an adaptor that is used to start the top-level main coroutine. 
 We explicitly specify its `Unit` return type, because a well-formed `main` function in Kotlin has to return `Unit`.
 
-This is also a way to write unit-tests for suspending functions:
+This is also a way to write unit tests for suspending functions:
 
 <!--- INCLUDE
 import kotlinx.coroutines.*
@@ -184,7 +184,7 @@ import kotlinx.coroutines.*
 
 fun main() = runBlocking {
 //sampleStart
-    val job = GlobalScope.launch { // launch new coroutine and keep a reference to its Job
+    val job = GlobalScope.launch { // launch a new coroutine and keep a reference to its Job
         delay(1000L)
         println("World!")
     }
@@ -196,7 +196,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03.kt).
 
 <!--- TEST
 Hello,
@@ -209,11 +209,11 @@ the background job in any way. Much better.
 ### Structured concurrency
 
 There is still something to be desired for practical usage of coroutines. 
-When we use `GlobalScope.launch` we create a top-level coroutine. Even though it is light-weight, it still 
+When we use `GlobalScope.launch`, we create a top-level coroutine. Even though it is light-weight, it still 
 consumes some memory resources while it runs. If we forget to keep a reference to the newly launched 
 coroutine it still runs. What if the code in the coroutine hangs (for example, we erroneously
 delay for too long), what if we launched too many coroutines and ran out of memory? 
-Having to manually keep a reference to all the launched coroutines and [join][Job.join] them is error-prone. 
+Having to manually keep references to all the launched coroutines and [join][Job.join] them is error-prone. 
 
 There is a better solution. We can use structured concurrency in our code. 
 Instead of launching coroutines in the [GlobalScope], just like we usually do with threads (threads are always global), 
@@ -231,7 +231,7 @@ in its scope complete. Thus, we can make our example simpler:
 import kotlinx.coroutines.*
 
 fun main() = runBlocking { // this: CoroutineScope
-    launch { // launch new coroutine in the scope of runBlocking
+    launch { // launch a new coroutine in the scope of runBlocking
         delay(1000L)
         println("World!")
     }
@@ -241,7 +241,7 @@ fun main() = runBlocking { // this: CoroutineScope
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03s.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03s.kt).
 
 <!--- TEST
 Hello,
@@ -250,7 +250,7 @@ World!
 
 ### Scope builder
 In addition to the coroutine scope provided by different builders, it is possible to declare your own scope using
-[coroutineScope] builder. It creates new coroutine scope and does not complete until all launched children
+[coroutineScope] builder. It creates a coroutine scope and does not complete until all launched children
 complete. The main difference between [runBlocking] and [coroutineScope] is that the latter does not block the current thread 
 while waiting for all children to complete.
 
@@ -265,23 +265,23 @@ fun main() = runBlocking { // this: CoroutineScope
         println("Task from runBlocking")
     }
 
-    coroutineScope { // Creates a new coroutine scope
+    coroutineScope { // Creates a coroutine scope
         launch {
             delay(500L) 
             println("Task from nested launch")
         }
 
         delay(100L)
-        println("Task from coroutine scope") // This line will be printed before nested launch
+        println("Task from coroutine scope") // This line will be printed before the nested launch
     }
 
-    println("Coroutine scope is over") // This line is not printed until nested launch completes
+    println("Coroutine scope is over") // This line is not printed until the nested launch completes
 }
 ```
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-04.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-04.kt).
 
 <!--- TEST
 Task from coroutine scope
@@ -317,7 +317,7 @@ suspend fun doWorld() {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-05.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-05.kt).
 
 <!--- TEST
 Hello,
@@ -328,10 +328,10 @@ World!
 But what if the extracted function contains a coroutine builder which is invoked on the current scope?
 In this case `suspend` modifier on the extracted function is not enough. Making `doWorld` extension
 method on `CoroutineScope` is one of the solutions, but it may not always be applicable as it does not make API clearer.
-Idiomatic solution is to have either explicit `CoroutineScope` as a field in a class containing target function
-or implicit when outer class implements `CoroutineScope`.
+The idiomatic solution is to have either an explicit `CoroutineScope` as a field in a class containing the target function
+or an implicit one when the outer class implements `CoroutineScope`.
 As a last resort, [CoroutineScope(coroutineContext)][CoroutineScope()] can be used, but such approach is structurally unsafe 
-because you no longer have control on the scope this method is executed. Only private API can use this builder.
+because you no longer have control on the scope of execution of this method. Only private APIs can use this builder.
 
 ### Coroutines ARE light-weight
 
@@ -354,7 +354,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-06.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-06.kt).
 
 <!--- TEST lines.size == 1 && lines[0] == ".".repeat(100_000) -->
 
@@ -386,7 +386,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-07.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-07.kt).
 
 You can run and see that it prints three lines and terminates:
 

docs/cancellation-and-timeouts.md

@@ -64,7 +64,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt).
 
 It produces the following output:
 
@@ -119,7 +119,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt).
 
 Run it to see that it continues to print "I'm sleeping" even after cancellation
 until the job completes by itself after five iterations.
@@ -171,7 +171,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
 
 As you can see, now this loop is cancelled. [isActive] is an extension property that is
 available inside the code of coroutine via [CoroutineScope] object.
@@ -218,7 +218,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
 
 Both [join][Job.join] and [cancelAndJoin] wait for all the finalization actions to complete, 
 so the example above produces the following output:
@@ -274,7 +274,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
 
 <!--- TEST
 I'm sleeping 0 ...
@@ -313,7 +313,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-06.kt).
 
 It produces the following output:
 
@@ -357,7 +357,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-07.kt).
 
 There is no longer an exception when running this code:
 

docs/channels.md

@@ -71,7 +71,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-01.kt).
 
 The output of this code is:
 
@@ -118,7 +118,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-02.kt).
 
 <!--- TEST 
 1
@@ -160,7 +160,7 @@ fun main() = runBlocking {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-03.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-03.kt).
 
 <!--- TEST 
 1
@@ -231,7 +231,7 @@ fun CoroutineScope.square(numbers: ReceiveChannel<Int>): ReceiveChannel<Int> = p
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-04.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-04.kt).
 
 <!--- TEST 
 1
@@ -322,7 +322,7 @@ fun CoroutineScope.filter(numbers: ReceiveChannel<Int>, prime: Int) = produce<In
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-05.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-05.kt).
 
 The output of this code is:
 
@@ -341,7 +341,7 @@ The output of this code is:
 
 <!--- TEST -->
 
-Note, that you can build the same pipeline using 
+Note that you can build the same pipeline using 
 [`iterator`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.sequences/iterator.html) 
 coroutine builder from the standard library. 
 Replace `produce` with `iterator`, `send` with `yield`, `receive` with `next`, 
@@ -425,7 +425,7 @@ fun CoroutineScope.launchProcessor(id: Int, channel: ReceiveChannel<Int>) = laun
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-06.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-06.kt).
 
 The output will be similar to the the following one, albeit the processor ids that receive
 each specific integer may be different:
@@ -445,7 +445,7 @@ Processor #3 received 10
 
 <!--- TEST lines.size == 10 && lines.withIndex().all { (i, line) -> line.startsWith("Processor #") && line.endsWith(" received ${i + 1}") } -->
 
-Note, that cancelling a producer coroutine closes its channel, thus eventually terminating iteration
+Note that cancelling a producer coroutine closes its channel, thus eventually terminating iteration
 over the channel that processor coroutines are doing.
 
 Also, pay attention to how we explicitly iterate over channel with `for` loop to perform fan-out in `launchProcessor` code. 
@@ -505,7 +505,7 @@ suspend fun sendString(channel: SendChannel<String>, s: String, time: Long) {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-07.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-07.kt).
 
 The output is:
 
@@ -557,7 +557,7 @@ fun main() = runBlocking<Unit> {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-08.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-08.kt).
 
 It prints "sending" _five_ times using a buffered channel with capacity of _four_:
 
@@ -612,7 +612,7 @@ suspend fun player(name: String, table: Channel<Ball>) {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-09.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-09.kt).
 
 The "ping" coroutine is started first, so it is the first one to receive the ball. Even though "ping"
 coroutine immediately starts receiving the ball again after sending it back to the table, the ball gets
@@ -627,7 +627,7 @@ pong Ball(hits=4)
 
 <!--- TEST -->
 
-Note, that sometimes channels may produce executions that look unfair due to the nature of the executor
+Note that sometimes channels may produce executions that look unfair due to the nature of the executor
 that is being used. See [this issue](https://github.com/Kotlin/kotlinx.coroutines/issues/111) for details.
 
 ### Ticker channels
@@ -675,7 +675,7 @@ fun main() = runBlocking<Unit> {
 
 </div>
 
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-10.kt)
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-channel-10.kt).
 
 It prints following lines: