toList

Consumes the elements of this channel into a list, preserving their order.

This is a convenience function equivalent to calling consumeAsFlow followed by kotlinx.coroutines.flow.toList. It is useful for testing code that uses channels to observe the elements the channel contains at the end of the test.

There is no way to recover channel elements if the channel gets closed with an exception or to apply additional transformations to the elements before building the resulting collection. Please use consumeAsFlow and kotlinx.coroutines.flow.toCollection for such advanced use-cases.

toList attempts to receive elements and put them into the list until the channel is closed. Calling toList on channels that are not eventually closed is always incorrect:

• It will suspend indefinitely if the channel is not closed, but no new elements arrive.

• If new elements do arrive and the channel is not eventually closed, toList will use more and more memory until exhausting it.

If the channel is closed with a cause, toList will rethrow that cause.

Since this function is implemented using consume, it is terminal, meaning that toList will cancel the channel before exiting. A toList call can finish before the sender closes the channel if it gets cancelled while waiting for the next element, or if MutableList.add fails with an exception. In both cases, the exception will be used for cancelling the channel and then rethrown.

Example:

val values = listOf(1, 5, 2, 9, 3, 3, 1)
// start a new coroutine that creates a channel,
// sends elements to it, and closes it
// once the coroutine's body finishes
val channel = produce {
    values.forEach { send(it) }
}
check(channel.toList() == values)