ChannelIterator: add an example

[murfel]

Add an example, stress that different coroutines can iterate over the channel, with their own iterator instance

[dkhalanskyjb]

That's not true, it can be passed around different coroutines as long as this doesn't result in multithreaded access.

[dkhalanskyjb]

Could you describe the sequence of events where this sample would answer a question a user may realistically have? It neither explains the next()/hasNext() interplay useful in deeply technical cases where you'd manipulate ChannelIterator manually, nor does it spell out "hey, this is not the class that you need to use manually, just write for (... in ...) instead" if that was the intention.

[murfel]

I'm addressing my own confusion with the original wording - it primed me to think that only one coroutine is allowed to create instances of the iterator.

[murfel]

Added wording on "don't use directly" and "next/hasNext"

[dkhalanskyjb]

Still not true. The only limitation is that it's non-thread-safe, but like with most other non-thread-safe structures, you can still use it from different threads:

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

suspend fun main() {
    val channel = Channel<Int>()
    val iterator: ChannelIterator<Int> = channel.iterator()
    val mutex = Mutex(locked = false)
    withContext(Dispatchers.Default) {
        repeat(10) { coroutine ->
            launch {
                repeat(10) { iteration ->
                    mutex.withLock {
                        repeat(10) {
                            iterator.hasNext()
                            println("Coroutine $coroutine, iteration $iteration: ${iterator.next()}")
                        }
                    }
                }
            }
        }
        launch {
            repeat(1000) {
                channel.send(it)
            }
        }
    }
    println("Done")
}

No one's stopping us from protecting an iterator with an asynchronous mutex, or a synchronous one, or even sending an iterator from one coroutine to another via other channels once every dozen operations, and then operating on it with complete confidence.

This distinction is not me being pedantic. There are often cases when it actually matters which specific thread (or much more rarely, coroutine) runs some code. We could have added some logic to the ChannelIterator initializer that would check if it's still running on the same coroutine, throwing an exception if it isn't. Some APIs do operate like that. We haven't and aren't planning to. I can't imagine use cases where it makes sense to send some channel iterator to another coroutine, but it's not prohibited in the contract, nor checked in the code.

Even the original formulation is too strict, as it's possible to have safe single-threaded concurrency (on Dispatchers.Main, for example). The only problem is with parallelism.