update: update docs for the new WebHelp engine (#2393)
* update: update cancellation-and-timeouts.md
* update: update channels.md
* update: update composing-suspending-functions.md
* update: update coroutine-context-and-dispatchers.md
* update: update coroutines-guide.md
* update: update exception-handling.md
* update: update select-expression.md
* update: update shared-mutable-state-and-concurrency.md
* update: update basics.md
* update: update flow.md
* update: update flow.md
* update: update _nav.yml
* update: add _nav.tree
* update: update links
* update: fixes after review
* update: get rid of divs
* update: add new lines for WebHelp parser
* update: add new lines for WebHelp parser
* fix: fix knit errors
* removed _nav.yml;
* renamed _nav.tree to kc.tree.
* removed coroutines overview from the list; a title for a hands-on tutorial
* update: Made kc.tree as valid XML
* update: added a configuration file project.ihp
* update: added a configuration file buildprofiles.xml
* update: moved coroutines overview from the main repository
* update: update cancellation-and-timeouts.md
* update: update channels.md
* update: update composing-suspending-functions.md
* update: update coroutine-context-and-dispatchers.md
* update: update coroutines-guide.md
* update: update exception-handling.md
* update: update select-expression.md
* update: update shared-mutable-state-and-concurrency.md
* update: update basics.md
* update: update flow.md
* update: update flow.md
* update: update _nav.yml
* update: add _nav.tree
* update: update links
* update: fixes after review
* update: get rid of divs
* removed _nav.yml;
* renamed _nav.tree to kc.tree.
* removed coroutines overview from the list; a title for a hands-on tutorial
* update: Made kc.tree as valid XML
* update: added a configuration file project.ihp
* update: added a configuration file buildprofiles.xml
* update: moved coroutines overview from the main repository
* update: move debug tutorials to coroutines repository
* update: update after knit
* update: move all docs files to topics/
* update: corrected the xml version of project.ihp
* update: move old jvm tutorial coroutines-basic-jvm.md
* update: moved knit.properties to resolve relative path correctly
* update: add stubs for moved pages
* update: update README.md
Co-authored-by: Ekaterina.Volodko <ekaterina.volodko@jetbrains.com>
diff --git a/docs/exception-handling.md b/docs/exception-handling.md
index b96837b..77dbac9 100644
--- a/docs/exception-handling.md
+++ b/docs/exception-handling.md
@@ -1,530 +1,3 @@
-<!--- TEST_NAME ExceptionsGuideTest -->
+The documentation has been moved to the [https://kotlinlang.org/docs/exception-handling.html](https://kotlinlang.org/docs/exception-handling.html) page.
-**Table of contents**
-
-<!--- TOC -->
-
-* [Exception Handling](#exception-handling)
- * [Exception propagation](#exception-propagation)
- * [CoroutineExceptionHandler](#coroutineexceptionhandler)
- * [Cancellation and exceptions](#cancellation-and-exceptions)
- * [Exceptions aggregation](#exceptions-aggregation)
- * [Supervision](#supervision)
- * [Supervision job](#supervision-job)
- * [Supervision scope](#supervision-scope)
- * [Exceptions in supervised coroutines](#exceptions-in-supervised-coroutines)
-
-<!--- END -->
-
-## Exception Handling
-
-This section covers exception handling and cancellation on exceptions.
-We already know that a cancelled coroutine throws [CancellationException] in suspension points and that it
-is ignored by the coroutines' machinery. Here we look at what happens if an exception is thrown during cancellation or multiple children of the same
-coroutine throw an exception.
-
-### Exception propagation
-
-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 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).
-
-It can be demonstrated by a simple example that creates root coroutines using the [GlobalScope]:
-
-<div class="sample" markdown="1" theme="idea" data-highlight-only>
-
-```kotlin
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
- val job = GlobalScope.launch { // root coroutine with launch
- println("Throwing exception from launch")
- throw IndexOutOfBoundsException() // Will be printed to the console by Thread.defaultUncaughtExceptionHandler
- }
- job.join()
- println("Joined failed job")
- val deferred = GlobalScope.async { // root coroutine with async
- println("Throwing exception from async")
- throw ArithmeticException() // Nothing is printed, relying on user to call await
- }
- try {
- deferred.await()
- println("Unreached")
- } catch (e: ArithmeticException) {
- println("Caught ArithmeticException")
- }
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-01.kt).
-
-The output of this code is (with [debug](https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/coroutine-context-and-dispatchers.md#debugging-coroutines-and-threads)):
-
-```text
-Throwing exception from launch
-Exception in thread "DefaultDispatcher-worker-2 @coroutine#2" java.lang.IndexOutOfBoundsException
-Joined failed job
-Throwing exception from async
-Caught ArithmeticException
-```
-
-<!--- TEST EXCEPTION-->
-
-### 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
-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
-with the corresponding exception when the handler is called. Normally, the handler is used to
-log the exception, show some kind of error message, terminate, and/or restart the application.
-
-On JVM it is possible to redefine global exception handler for all coroutines by registering [CoroutineExceptionHandler] via
-[`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).
-Global exception handler is similar to
-[`Thread.defaultUncaughtExceptionHandler`](https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#setDefaultUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler))
-which is used when no more specific handlers are registered.
-On Android, `uncaughtExceptionPreHandler` is installed as a global coroutine exception handler.
-
-`CoroutineExceptionHandler` is invoked only on **uncaught** exceptions — exceptions that were not handled in any other way.
-In particular, all _children_ coroutines (coroutines created in the context of another [Job]) delegate handling of
-their exceptions to their parent coroutine, which also delegates to the parent, and so on until the root,
-so the `CoroutineExceptionHandler` installed in their context is never used.
-In addition to that, [async] builder always catches all exceptions and represents them in the resulting [Deferred] object,
-so its `CoroutineExceptionHandler` has no effect either.
-
-> Coroutines running in supervision scope do not propagate exceptions to their parent and are
-excluded from this rule. A further [Supervision](#supervision) section of this document gives more details.
-
-<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
-
-```kotlin
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
-//sampleStart
- val handler = CoroutineExceptionHandler { _, exception ->
- println("CoroutineExceptionHandler got $exception")
- }
- val job = GlobalScope.launch(handler) { // root coroutine, running in GlobalScope
- throw AssertionError()
- }
- val deferred = GlobalScope.async(handler) { // also root, but async instead of launch
- throw ArithmeticException() // Nothing will be printed, relying on user to call deferred.await()
- }
- joinAll(job, deferred)
-//sampleEnd
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-02.kt).
-
-The output of this code is:
-
-```text
-CoroutineExceptionHandler got java.lang.AssertionError
-```
-
-<!--- TEST-->
-
-### Cancellation and exceptions
-
-Cancellation is closely related to exceptions. Coroutines internally use `CancellationException` for cancellation, these
-exceptions are ignored by all handlers, so they should be used only as the source of additional debug information, which can
-be obtained by `catch` block.
-When a coroutine is cancelled using [Job.cancel], it terminates, but it does not cancel its parent.
-
-<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
-
-```kotlin
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
-//sampleStart
- val job = launch {
- val child = launch {
- try {
- delay(Long.MAX_VALUE)
- } finally {
- println("Child is cancelled")
- }
- }
- yield()
- println("Cancelling child")
- child.cancel()
- child.join()
- yield()
- println("Parent is not cancelled")
- }
- job.join()
-//sampleEnd
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-03.kt).
-
-The output of this code is:
-
-```text
-Cancelling child
-Child is cancelled
-Parent is not cancelled
-```
-
-<!--- TEST-->
-
-If a coroutine encounters an exception other than `CancellationException`, it cancels its parent with that exception.
-This behaviour cannot be overridden and is used to provide stable coroutines hierarchies for
-[structured concurrency](https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/composing-suspending-functions.md#structured-concurrency-with-async).
-[CoroutineExceptionHandler] implementation is not used for child coroutines.
-
-> In these examples [CoroutineExceptionHandler] is always installed to a coroutine
-that is created in [GlobalScope]. It does not make sense to install an exception handler to a coroutine that
-is launched in the scope of the main [runBlocking], since the main coroutine is going to be always cancelled
-when its child completes with exception despite the installed handler.
-
-The original exception is handled by the parent only when all its children terminate,
-which is demonstrated by the following example.
-
-<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
-
-```kotlin
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
-//sampleStart
- val handler = CoroutineExceptionHandler { _, exception ->
- println("CoroutineExceptionHandler got $exception")
- }
- val job = GlobalScope.launch(handler) {
- launch { // the first child
- try {
- delay(Long.MAX_VALUE)
- } finally {
- withContext(NonCancellable) {
- println("Children are cancelled, but exception is not handled until all children terminate")
- delay(100)
- println("The first child finished its non cancellable block")
- }
- }
- }
- launch { // the second child
- delay(10)
- println("Second child throws an exception")
- throw ArithmeticException()
- }
- }
- job.join()
-//sampleEnd
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-04.kt).
-
-The output of this code is:
-
-```text
-Second child throws an exception
-Children are cancelled, but exception is not handled until all children terminate
-The first child finished its non cancellable block
-CoroutineExceptionHandler got java.lang.ArithmeticException
-```
-<!--- TEST-->
-
-### Exceptions aggregation
-
-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.
-
-<!--- INCLUDE
-import kotlinx.coroutines.exceptions.*
--->
-
-<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
-
-```kotlin
-import kotlinx.coroutines.*
-import java.io.*
-
-fun main() = runBlocking {
- val handler = CoroutineExceptionHandler { _, exception ->
- println("CoroutineExceptionHandler got $exception with suppressed ${exception.suppressed.contentToString()}")
- }
- val job = GlobalScope.launch(handler) {
- launch {
- try {
- delay(Long.MAX_VALUE) // it gets cancelled when another sibling fails with IOException
- } finally {
- throw ArithmeticException() // the second exception
- }
- }
- launch {
- delay(100)
- throw IOException() // the first exception
- }
- delay(Long.MAX_VALUE)
- }
- job.join()
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-05.kt).
-
-> Note: This above code will work properly only on JDK7+ that supports `suppressed` exceptions
-
-The output of this code is:
-
-```text
-CoroutineExceptionHandler got java.io.IOException with suppressed [java.lang.ArithmeticException]
-```
-
-<!--- TEST-->
-
-> 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:
-
-<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
-
-```kotlin
-import kotlinx.coroutines.*
-import java.io.*
-
-fun main() = runBlocking {
-//sampleStart
- val handler = CoroutineExceptionHandler { _, exception ->
- println("CoroutineExceptionHandler got $exception")
- }
- val job = GlobalScope.launch(handler) {
- val inner = launch { // all this stack of coroutines will get cancelled
- launch {
- launch {
- throw IOException() // the original exception
- }
- }
- }
- try {
- inner.join()
- } catch (e: CancellationException) {
- println("Rethrowing CancellationException with original cause")
- throw e // cancellation exception is rethrown, yet the original IOException gets to the handler
- }
- }
- job.join()
-//sampleEnd
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-exceptions-06.kt).
-
-The output of this code is:
-
-```text
-Rethrowing CancellationException with original cause
-CoroutineExceptionHandler got java.io.IOException
-```
-<!--- TEST-->
-
-### Supervision
-
-As we have studied before, cancellation is a bidirectional relationship propagating through the whole
-hierarchy of coroutines. Let us take a look at the case when unidirectional cancellation is required.
-
-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.
-
-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
-
-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. This can easily be demonstrated using the following example:
-
-<div class="sample" markdown="1" theme="idea" data-highlight-only>
-
-```kotlin
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
- val supervisor = SupervisorJob()
- 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("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("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("The second child is cancelled because the supervisor was cancelled")
- }
- }
- // wait until the first child fails & completes
- firstChild.join()
- println("Cancelling the supervisor")
- supervisor.cancel()
- secondChild.join()
- }
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-supervision-01.kt).
-
-The output of this code is:
-
-```text
-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-->
-
-
-#### Supervision scope
-
-Instead of [coroutineScope][_coroutineScope], we can use [supervisorScope][_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][_coroutineScope] does.
-
-<div class="sample" markdown="1" theme="idea" data-highlight-only>
-
-```kotlin
-import kotlin.coroutines.*
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
- try {
- supervisorScope {
- val child = launch {
- try {
- println("The child is sleeping")
- delay(Long.MAX_VALUE)
- } finally {
- println("The child is cancelled")
- }
- }
- // Give our child a chance to execute and print using yield
- yield()
- println("Throwing an exception from the scope")
- throw AssertionError()
- }
- } catch(e: AssertionError) {
- println("Caught an assertion error")
- }
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-supervision-02.kt).
-
-The output of this code is:
-
-```text
-The child is sleeping
-Throwing an exception from the scope
-The child is cancelled
-Caught an assertion error
-```
-<!--- TEST-->
-
-#### Exceptions in supervised coroutines
-
-Another crucial difference between regular and supervisor jobs is exception handling.
-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][_supervisorScope] _do_ use the [CoroutineExceptionHandler]
-that is installed in their scope in the same way as root coroutines do
-(see the [CoroutineExceptionHandler](#coroutineexceptionhandler) section for details).
-
-<div class="sample" markdown="1" theme="idea" data-highlight-only>
-
-```kotlin
-import kotlin.coroutines.*
-import kotlinx.coroutines.*
-
-fun main() = runBlocking {
- val handler = CoroutineExceptionHandler { _, exception ->
- println("CoroutineExceptionHandler got $exception")
- }
- supervisorScope {
- val child = launch(handler) {
- println("The child throws an exception")
- throw AssertionError()
- }
- println("The scope is completing")
- }
- println("The scope is completed")
-}
-```
-
-</div>
-
-> You can get the full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-supervision-03.kt).
-
-The output of this code is:
-
-```text
-The scope is completing
-The child throws an exception
-CoroutineExceptionHandler got java.lang.AssertionError
-The scope is completed
-```
-<!--- TEST-->
-
-<!--- MODULE kotlinx-coroutines-core -->
-<!--- INDEX kotlinx.coroutines -->
-
-[CancellationException]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html
-[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
-[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html
-[Deferred.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html
-[GlobalScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-global-scope/index.html
-[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-exception-handler/index.html
-[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
-[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
-[Job.cancel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/cancel.html
-[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
-[_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
-
-<!--- INDEX kotlinx.coroutines.channels -->
-
-[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
-[ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-receive-channel/receive.html
-
-<!--- END -->
+To edit the documentation, open the [topics/exception-handling.md](topics/exception-handling.md) page.
\ No newline at end of file