From f4fb204b220b224d5ffa9b7c00ff077b681213e9 Mon Sep 17 00:00:00 2001 From: Yanis Batura Date: Sun, 21 Jun 2020 20:03:40 +0700 Subject: [PATCH] Fix typos in docs (#2098) Co-authored-by: Louis CAD --- docs/coroutine-context-and-dispatchers.md | 2 +- docs/exception-handling.md | 76 +++++++++---------- .../src/future/Future.kt | 4 +- .../jvm/test/guide/example-supervision-01.kt | 10 +-- .../jvm/test/guide/example-supervision-02.kt | 8 +- .../jvm/test/guide/example-supervision-03.kt | 6 +- .../test/guide/test/ExceptionsGuideTest.kt | 22 +++--- .../kotlinx-coroutines-reactive/README.md | 6 +- reactive/kotlinx-coroutines-reactor/README.md | 20 ++--- 9 files changed, 77 insertions(+), 77 deletions(-) diff --git a/docs/coroutine-context-and-dispatchers.md b/docs/coroutine-context-and-dispatchers.md index 5883dda13f..4909206e17 100644 --- a/docs/coroutine-context-and-dispatchers.md +++ b/docs/coroutine-context-and-dispatchers.md @@ -625,7 +625,7 @@ fun main() = runBlocking { In this example we launch a new coroutine in a background thread pool using [Dispatchers.Default], so it works on a different thread from the thread pool, but it still has the value of the thread local variable that we specified using `threadLocal.asContextElement(value = "launch")`, -no matter on what thread the coroutine is executed. +no matter which thread the coroutine is executed on. Thus, the output (with [debug](#debugging-coroutines-and-threads)) is: ```text diff --git a/docs/exception-handling.md b/docs/exception-handling.md index ca78200e0f..5618cafbdc 100644 --- a/docs/exception-handling.md +++ b/docs/exception-handling.md @@ -28,7 +28,7 @@ coroutine throw an exception. Coroutine builders come in two flavors: propagating exceptions automatically ([launch] and [actor]) or exposing them to users ([async] and [produce]). When these builders are used to create a _root_ coroutine, that is not a _child_ of another coroutine, -the former builder treat exceptions as **uncaught** exceptions, similar to Java's `Thread.uncaughtExceptionHandler`, +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). @@ -246,7 +246,7 @@ CoroutineExceptionHandler got java.lang.ArithmeticException ### Exceptions aggregation -When multiple children of a coroutine fail with an exception the +When multiple children of a coroutine fail with an exception, the general rule is "the first exception wins", so the first exception gets handled. All additional exceptions that happen after the first one are attached to the first exception as suppressed ones. @@ -296,8 +296,8 @@ CoroutineExceptionHandler got java.io.IOException with suppressed [java.lang.Ari -> Note, this mechanism currently works only on Java version 1.7+. -Limitation on JS and Native is temporary and will be fixed in the future. +> Note that this mechanism currently only works on Java version 1.7+. +The JS and Native restrictions are temporary and will be lifted in the future. Cancellation exceptions are transparent and are unwrapped by default: @@ -353,14 +353,14 @@ A good example of such a requirement is a UI component with the job defined in i 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. -Another example is a server process that spawns several children jobs and needs to _supervise_ -their execution, tracking their failures and restarting just those children jobs that had failed. +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. #### Supervision job -For these purposes [SupervisorJob][SupervisorJob()] can be used. +The [SupervisorJob][SupervisorJob()] can be used for these purposes. It is similar to a regular [Job][Job()] with the only exception that cancellation is propagated -only downwards. It is easy to demonstrate with an example: +only downwards. This can easily be demonstrated using the following example:
@@ -372,24 +372,24 @@ fun main() = runBlocking { with(CoroutineScope(coroutineContext + supervisor)) { // launch the first child -- its exception is ignored for this example (don't do this in practice!) val firstChild = launch(CoroutineExceptionHandler { _, _ -> }) { - println("First child is failing") - throw AssertionError("First child is cancelled") + println("The first child is failing") + throw AssertionError("The first child is cancelled") } // launch the second child val secondChild = launch { firstChild.join() // Cancellation of the first child is not propagated to the second child - println("First child is cancelled: ${firstChild.isCancelled}, but second one is still active") + println("The first child is cancelled: ${firstChild.isCancelled}, but the second one is still active") try { delay(Long.MAX_VALUE) } finally { // But cancellation of the supervisor is propagated - println("Second child is cancelled because supervisor is cancelled") + println("The second child is cancelled because the supervisor was cancelled") } } // wait until the first child fails & completes firstChild.join() - println("Cancelling supervisor") + println("Cancelling the supervisor") supervisor.cancel() secondChild.join() } @@ -403,18 +403,18 @@ fun main() = runBlocking { The output of this code is: ```text -First child is failing -First child is cancelled: true, but second one is still active -Cancelling supervisor -Second child is cancelled because supervisor is cancelled +The first child is failing +The first child is cancelled: true, but the second one is still active +Cancelling the supervisor +The second child is cancelled because the supervisor was cancelled ``` #### Supervision scope -For _scoped_ concurrency [supervisorScope] can be used instead of [coroutineScope] for the same purpose. It propagates cancellation -in one direction only and cancels all children only if it has failed itself. It also waits for all children before completion +Instead of [coroutineScope], we can use [supervisorScope] for _scoped_ concurrency. It propagates the cancellation +in one direction only and cancels all its children only if it failed itself. It also waits for all children before completion just like [coroutineScope] does.
@@ -428,19 +428,19 @@ fun main() = runBlocking { supervisorScope { val child = launch { try { - println("Child is sleeping") + println("The child is sleeping") delay(Long.MAX_VALUE) } finally { - println("Child is cancelled") + println("The child is cancelled") } } // Give our child a chance to execute and print using yield yield() - println("Throwing exception from scope") + println("Throwing an exception from the scope") throw AssertionError() } } catch(e: AssertionError) { - println("Caught assertion error") + println("Caught an assertion error") } } ``` @@ -452,21 +452,21 @@ fun main() = runBlocking { The output of this code is: ```text -Child is sleeping -Throwing exception from scope -Child is cancelled -Caught assertion error +The child is sleeping +Throwing an exception from the scope +The child is cancelled +Caught an assertion error ``` #### Exceptions in supervised coroutines Another crucial difference between regular and supervisor jobs is exception handling. -Every child should handle its exceptions by itself via exception handling mechanism. -This difference comes from the fact that child's failure is not propagated to the parent. -It means that coroutines launched directly inside [supervisorScope] _do_ use the [CoroutineExceptionHandler] +Every child should handle its exceptions by itself via the exception handling mechanism. +This difference comes from the fact that child's failure does not propagate to the parent. +It means that coroutines launched directly inside the [supervisorScope] _do_ use the [CoroutineExceptionHandler] that is installed in their scope in the same way as root coroutines do -(see [CoroutineExceptionHandler](#coroutineexceptionhandler) section for details). +(see the [CoroutineExceptionHandler](#coroutineexceptionhandler) section for details).
@@ -480,12 +480,12 @@ fun main() = runBlocking { } supervisorScope { val child = launch(handler) { - println("Child throws an exception") + println("The child throws an exception") throw AssertionError() } - println("Scope is completing") + println("The scope is completing") } - println("Scope is completed") + println("The scope is completed") } ``` @@ -496,10 +496,10 @@ fun main() = runBlocking { The output of this code is: ```text -Scope is completing -Child throws an exception +The scope is completing +The child throws an exception CoroutineExceptionHandler got java.lang.AssertionError -Scope is completed +The scope is completed ``` @@ -517,8 +517,8 @@ Scope is completed [runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html [SupervisorJob()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-supervisor-job.html [Job()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job.html -[supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html [coroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/coroutine-scope.html +[supervisorScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/supervisor-scope.html [actor]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/actor.html [produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/produce.html diff --git a/integration/kotlinx-coroutines-jdk8/src/future/Future.kt b/integration/kotlinx-coroutines-jdk8/src/future/Future.kt index 3cd848f2cf..f7fdba5f69 100644 --- a/integration/kotlinx-coroutines-jdk8/src/future/Future.kt +++ b/integration/kotlinx-coroutines-jdk8/src/future/Future.kt @@ -11,10 +11,10 @@ import java.util.function.* import kotlin.coroutines.* /** - * Starts new coroutine and returns its result as an implementation of [CompletableFuture]. + * Starts a new coroutine and returns its result as an implementation of [CompletableFuture]. * The running coroutine is cancelled when the resulting future is cancelled or otherwise completed. * - * Coroutine context is inherited from a [CoroutineScope], additional context elements can be specified with [context] argument. + * The coroutine context is inherited from a [CoroutineScope], additional context elements can be specified with the [context] argument. * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [Dispatchers.Default] is used. * The parent job is inherited from a [CoroutineScope] as well, but it can also be overridden * with corresponding [context] element. diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt b/kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt index ffd56a8f85..db819e4fc6 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt @@ -12,24 +12,24 @@ fun main() = runBlocking { with(CoroutineScope(coroutineContext + supervisor)) { // launch the first child -- its exception is ignored for this example (don't do this in practice!) val firstChild = launch(CoroutineExceptionHandler { _, _ -> }) { - println("First child is failing") - throw AssertionError("First child is cancelled") + println("The first child is failing") + throw AssertionError("The first child is cancelled") } // launch the second child val secondChild = launch { firstChild.join() // Cancellation of the first child is not propagated to the second child - println("First child is cancelled: ${firstChild.isCancelled}, but second one is still active") + println("The first child is cancelled: ${firstChild.isCancelled}, but the second one is still active") try { delay(Long.MAX_VALUE) } finally { // But cancellation of the supervisor is propagated - println("Second child is cancelled because supervisor is cancelled") + println("The second child is cancelled because the supervisor was cancelled") } } // wait until the first child fails & completes firstChild.join() - println("Cancelling supervisor") + println("Cancelling the supervisor") supervisor.cancel() secondChild.join() } diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt b/kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt index dc3a0f2844..50deff3d0b 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt @@ -13,18 +13,18 @@ fun main() = runBlocking { supervisorScope { val child = launch { try { - println("Child is sleeping") + println("The child is sleeping") delay(Long.MAX_VALUE) } finally { - println("Child is cancelled") + println("The child is cancelled") } } // Give our child a chance to execute and print using yield yield() - println("Throwing exception from scope") + println("Throwing an exception from the scope") throw AssertionError() } } catch(e: AssertionError) { - println("Caught assertion error") + println("Caught an assertion error") } } diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt b/kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt index 5efbe69146..943c64f6ee 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt @@ -14,10 +14,10 @@ fun main() = runBlocking { } supervisorScope { val child = launch(handler) { - println("Child throws an exception") + println("The child throws an exception") throw AssertionError() } - println("Scope is completing") + println("The scope is completing") } - println("Scope is completed") + println("The scope is completed") } diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt index 21d2c73b1b..c42ba31d3a 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt @@ -63,30 +63,30 @@ class ExceptionsGuideTest { @Test fun testExampleSupervision01() { test("ExampleSupervision01") { kotlinx.coroutines.guide.exampleSupervision01.main() }.verifyLines( - "First child is failing", - "First child is cancelled: true, but second one is still active", - "Cancelling supervisor", - "Second child is cancelled because supervisor is cancelled" + "The first child is failing", + "The first child is cancelled: true, but the second one is still active", + "Cancelling the supervisor", + "The second child is cancelled because the supervisor was cancelled" ) } @Test fun testExampleSupervision02() { test("ExampleSupervision02") { kotlinx.coroutines.guide.exampleSupervision02.main() }.verifyLines( - "Child is sleeping", - "Throwing exception from scope", - "Child is cancelled", - "Caught assertion error" + "The child is sleeping", + "Throwing an exception from the scope", + "The child is cancelled", + "Caught an assertion error" ) } @Test fun testExampleSupervision03() { test("ExampleSupervision03") { kotlinx.coroutines.guide.exampleSupervision03.main() }.verifyLines( - "Scope is completing", - "Child throws an exception", + "The scope is completing", + "The child throws an exception", "CoroutineExceptionHandler got java.lang.AssertionError", - "Scope is completed" + "The scope is completed" ) } } diff --git a/reactive/kotlinx-coroutines-reactive/README.md b/reactive/kotlinx-coroutines-reactive/README.md index b38202bbdf..0a59b2c251 100644 --- a/reactive/kotlinx-coroutines-reactive/README.md +++ b/reactive/kotlinx-coroutines-reactive/README.md @@ -6,14 +6,14 @@ Coroutine builders: | **Name** | **Result** | **Scope** | **Description** | --------------- | ----------------------------- | ---------------- | --------------- -| [publish] | `Publisher` | [ProducerScope] | Cold reactive publisher that starts coroutine on subscribe +| [publish] | `Publisher` | [ProducerScope] | Cold reactive publisher that starts the coroutine on subscribe Integration with [Flow]: | **Name** | **Result** | **Description** | --------------- | -------------- | --------------- -| [Publisher.asFlow] | `Flow` | Converts the given publisher to flow -| [Flow.asPublisher] | `Publisher` | Converts the given flow to the TCK-compliant publisher +| [Publisher.asFlow] | `Flow` | Converts the given publisher to a flow +| [Flow.asPublisher] | `Publisher` | Converts the given flow to a TCK-compliant publisher If these adapters are used along with `kotlinx-coroutines-reactor` in the classpath, then Reactor's `Context` is properly propagated as coroutine context element (`ReactorContext`) and vice versa. diff --git a/reactive/kotlinx-coroutines-reactor/README.md b/reactive/kotlinx-coroutines-reactor/README.md index 50e1602a3a..cd4a42a34c 100644 --- a/reactive/kotlinx-coroutines-reactor/README.md +++ b/reactive/kotlinx-coroutines-reactor/README.md @@ -6,29 +6,29 @@ Coroutine builders: | **Name** | **Result** | **Scope** | **Description** | --------------- | ------------| ---------------- | --------------- -| [mono] | `Mono` | [CoroutineScope] | Cold mono that starts coroutine on subscribe -| [flux] | `Flux` | [CoroutineScope] | Cold flux that starts coroutine on subscribe +| [mono] | `Mono` | [CoroutineScope] | A cold Mono that starts the coroutine on subscription +| [flux] | `Flux` | [CoroutineScope] | A cold Flux that starts the coroutine on subscription -Note that `Mono` and `Flux` are a subclass of [Reactive Streams](https://www.reactive-streams.org) -`Publisher` and extensions for it are covered by +Note that `Mono` and `Flux` are subclasses of [Reactive Streams](https://www.reactive-streams.org)' +`Publisher` and extensions for it are covered by the [kotlinx-coroutines-reactive](../kotlinx-coroutines-reactive) module. Integration with [Flow]: | **Name** | **Result** | **Description** | --------------- | -------------- | --------------- -| [Flow.asFlux] | `Flux` | Converts the given flow to the TCK-compliant Flux. +| [Flow.asFlux] | `Flux` | Converts the given flow to a TCK-compliant Flux. -This adapter is integrated with Reactor's `Context` and coroutines [ReactorContext]. +This adapter is integrated with Reactor's `Context` and coroutines' [ReactorContext]. Conversion functions: | **Name** | **Description** | -------- | --------------- -| [Job.asMono][kotlinx.coroutines.Job.asMono] | Converts job to hot mono -| [Deferred.asMono][kotlinx.coroutines.Deferred.asMono] | Converts deferred value to hot mono -| [ReceiveChannel.asFlux][kotlinx.coroutines.channels.ReceiveChannel.asFlux] | Converts streaming channel to hot flux -| [Scheduler.asCoroutineDispatcher][reactor.core.scheduler.Scheduler.asCoroutineDispatcher] | Converts scheduler to [CoroutineDispatcher] +| [Job.asMono][kotlinx.coroutines.Job.asMono] | Converts a job to a hot Mono +| [Deferred.asMono][kotlinx.coroutines.Deferred.asMono] | Converts a deferred value to a hot Mono +| [ReceiveChannel.asFlux][kotlinx.coroutines.channels.ReceiveChannel.asFlux] | Converts a streaming channel to a hot Flux +| [Scheduler.asCoroutineDispatcher][reactor.core.scheduler.Scheduler.asCoroutineDispatcher] | Converts a scheduler to a [CoroutineDispatcher]