Update the documentation for the Channel interface

[dkhalanskyjb]

Note: a major piece of terminology that's changed in this is that when a channel is closed with a cause, it's no longer called a "failed channel". I found it immensely confusing to have channelResult.isClosed that means "the channel is closed", but channelResult.isFailed that doesn't mean "the channel is failed". Also, every cancelled channel is a "failed" channel by the definition of being closed with a cause, which doesn't seem to be the intention. So, I suggest that we remove mentions of "failed channels" throughout and replace them with "closed with a cause". Luckily, it's only relevant in a limited number of places.

[lukellmann]

Note: a major piece of terminology that's changed in this is that when a channel is closed with a cause, it's no longer called a "failed channel".

The term is still used here:

• CoroutineScope.produce (twice)
• CoroutineScope.actor
• ChannelsTest.testToListOnFailedChannel
• ReceiveChannel.receiveOrNull
• ReceiveChannel.receiveOrNull (in Channels.common.kt).

[dkhalanskyjb]

I also think the behavior of SendChannel and ReceiveChannel functions when the channel was cancelled could be described in more detail. Instead of only mentioning in the documentation of ReceiveChannel.cancel that other functions will throw CancellationExceptions, this could be clarified in the documentation of each function this applies to.

Semantically, cancel does not put the channel into a "cancelled" state, it only closes the channel with a CancellationException and consumes the elements, and it looks like every operation that throws when the channel is closed already mentions this.

[lukellmann]

Semantically, cancel does not put the channel into a "cancelled" state, it only closes the channel with a CancellationException and consumes the elements, and it looks like every operation that throws when the channel is closed already mentions this.

Oh, I didn't think about it that way (probably because CancellationExceptions are special). Yes, seems alright.

[kjnsn]

Semantically, cancel does not put the channel into a "cancelled" state, it only closes the channel with a CancellationException and consumes the elements, and it looks like every operation that throws when the channel is closed already mentions this.

I think this could be clarified. When trying to read from a closed channel it doesn't throw a CancellationException (at least from my experience).

[dkhalanskyjb]

When trying to read from a closed channel it doesn't throw a CancellationException

@kjnsn, close the channel with a CancellationException (like cancel does), and it will:

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

fun main() {
    runBlocking {
        val c = Channel<Int>()
        c.close(CancellationException())
        println(runCatching { c.receive() }) // CancellationException
    }
}

Runnable version; https://pl.kotl.in/vutYqCO0B