Fix inconsistencies in the documentation on exception handling and cancellation

[mtopolnik]

These are a few quotes from exception-handling.html in the official docs:

(1)

Coroutine builders come in two flavors: propagating exceptions automatically (launch and actor) or exposing them to users (async and produce). The former treat exceptions as unhandled, similar to Java's Thread.uncaughtExceptionHandler, while the latter are relying on the user to consume the final exception, for example via await or receive

(2)

If a coroutine encounters 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 which do not depend on CoroutineExceptionHandler implementation.

(3)

CoroutineExceptionHandler is invoked only on exceptions which are not expected to be handled by the user, so registering it in async builder and the like of it has no effect.

These sentences convey a confusing message.

(1) seems to claim that launch and async are different and async won't propagate the exceptions, relying on the user to receive them in an await().

(2) seems to contradict that and claim that exceptions always cancel their coroutine and propagate to the parent.

(3) seems to once again make a difference between launch and async.

The actual behavior is that all builders propagate the exception to their parent, so the claim in (1) is incorrect. That in turn means that all exceptions are equally treated as "unhandled", which defeats the rationale given in (3). Yet the actual behavior is as stated, async ignores exception handlers.

[ylemoigne]

Ok, this is related to a question I asked today on coroutine slack channel.

The questions is : "why In 'uncaughtExceptionHandler' ... is called ?"

import kotlinx.coroutines.*
import kotlinx.coroutines.channels.produce

// From : https://kotlinlang.org/docs/reference/coroutines/exception-handling.html
//
// Coroutine builders come in two flavors: propagating exceptions automatically (launch and actor) or
// exposing them to users (async and produce).
//
// The former treat exceptions as unhandled, similar to Java's Thread.uncaughtExceptionHandler,
// while the latter are relying on the user to consume the final exception,
// for example via await or receive (produce and receive are covered later in Channels section).
fun main() {
    val job = GlobalScope.launch(CoroutineExceptionHandler { _, t -> println("In 'uncaughtExceptionHandler' $t") }) {
        try {

            val ch = doJob2()
            for (e in ch) {
                println("Receive $e")
            }

        } catch (e: Exception) {
            println("Catched exception $e, not rethrown")
        }
    }

    runBlocking { job.join() }
}


fun CoroutineScope.doJob2() = produce<String> {
    for (i in 0..10) {
        println("Send $i")
        send("Emit $i")
        if (i == 3) close(IllegalStateException("Haha !"))
    }
}

[ylemoigne]

Now the question is : how to prevent exception to be considered unhandled ?

[elizarov]

I've made another pass over exception-handling.html and I think I've addressed all remaining inconsistencies there.