Job join method documentation

[serddmit]

I have found very strange documentation for join method:

In particular, it means that a parent coroutine invoking join on a child coroutine that was started using launch(coroutineContext) { ... } builder throws CancellationException if the child had crashed, unless a non-standard CoroutineExceptionHandler is installed in the context.

I'm not sure that CoroutineExceptionHandler will have effect for CancellationException.
Example:

fun main() = runBlocking {
    val handler = CoroutineExceptionHandler { _, exception ->
        println("CoroutineExceptionHandler got $exception")
    }
    val job = GlobalScope.launch(handler) {
        val inner = launch { // all this stack of coroutines will get cancelled
            throw IOException() // the original exception
        }
        try {
            inner.join()
        } catch (e: CancellationException) {
            println("handle join")
        }
    }
    job.join()
}

Output:
handle join CoroutineExceptionHandler got java.io.IOException

So basically CancellationException will still be thrown regardless any installed handlers.

[elizarov]

Good catch. Thanks.

[serddmit]

Thanks, now it's clear!

[serddmit]

@elizarov, Don't forget to change documentation for cancelAndJoin, it has the same statement.
https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/cancel-and-join.html

Thanks