Add ReceiveChannel.toList(destination) #4520

dkhalanskyjb · 2025-09-10T08:16:57Z

Use case: collecting elements up until the point the channel is closed without losing the elements when toList when the exception is thrown.

This function is similar to Flow<T>.toList(destination), which we already have, so the addition makes sense from the point of view of consistency as well.

Use case: collecting elements up until the point the channel is closed without losing the elements when `toList` when the exception is thrown. This function is similar to `Flow<T>.toList(destination)`, which we already have, so the addition makes sense from the point of view of consistency as well.

murfel

For context, Flow's toList(destination) that you've referenced

https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/to-list.html

https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/common/src/flow/terminal/Collection.kt#L11

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

murfel · 2025-10-09T09:46:08Z

Could you also fix the Channel.toList docs to avoid saying "all elements" (two entries on this page)
https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/to-list.html

dkhalanskyjb · 2025-10-14T09:10:07Z

@murfel, that page is automatically generated from the documentation comments that are edited in this PR.

murfel · 2025-10-14T09:18:50Z

I'm aware.

murfel · 2025-10-25T06:36:54Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

 *
- * This function will attempt to receive elements and put them into the list until the channel is
+ * 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.


Suggested change

* It is useful for testing code that uses channels to observe the elements the channel contains at the end of the test.

* It is useful for testing to observe the elements the channel contains at the end of the test.

murfel · 2025-10-25T06:42:15Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+ *
+ * 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.


Suggested change

* Please use [consumeAsFlow] and [kotlinx.coroutines.flow.toCollection] for such advanced use-cases.

* Please use either [consumeTo] or [consumeAsFlow] and [kotlinx.coroutines.flow.toCollection] for such advanced use-cases.

We do want to direct the users to Flow here.

murfel · 2025-10-25T07:01:39Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

 * check(channel.toList() == values)
 * ```
 */
 public suspend fun <E> ReceiveChannel<E>.toList(): List<E> = buildList {


We forgot about lost elements (onUndeliveredElement). It should be at least mentioned in the doc, and possibly onUndeliveredElement could be added as a parameter.

onUndeliveredElement overcomplicates the signature for no real use-case, but provides completeness. No strong opinion on my end.

Could you explain what behavior of onUndeliveredElement is missing from the description? We do say that the elements that did get delivered may still be lost if the channel is closed with a cause.

Ah, found it.

It should be placed (or duplicated) at the end, near the description of its terminal behaviour, since it's logically connected.

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

murfel · 2025-10-25T10:05:11Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+ * [consumeTo] attempts to receive elements and put them into the collection until the channel is
+ * [closed][SendChannel.close].
+ *
+ * If the channel is [closed][SendChannel.close] with a cause, [consumeTo] will rethrow that cause.


Suggested change

* If the channel is [closed][SendChannel.close] with a cause, [consumeTo] will rethrow that cause.

* If the channel is [closed][SendChannel.close] with a cause, [consumeTo] will rethrow that cause immediately.

* The channel could still contain elements that will never be received.

Not true: https://pl.kotl.in/U4TKRZ-I2

Nevermind, I short circuited (and also misread the docs). Please do add when exactly the exception will be rethrown, though.

The channel could still contain elements that will never be received.

Elaborate this whole scenario.

murfel · 2025-10-25T10:08:24Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+ * In practice, this means that if adding new elements to the collection fails with an exception,
+ * that exception will be used for [cancelling][ReceiveChannel.cancel] the channel and rethrown.
+ *
+ * The intended use case for this function is collecting the remaining elements of a closed channel


Not necessarily "the remaining elements of a closed channel".

It is definitely for use when we know that the channel is or will be closed at some point.

Your sample is of this use-case, but there are others.

What you're describing is not the intended use case. If you only know the channel will be closed at some point, then consumeTo uses an unbound amount of memory, which we try to avoid. A possible use case is sending a bounded number of elements (for example, we know there will be at most 100 elements before the channel gets closed). I'd argue that channels are not the right tool for the job in that case, you should instead build a list on the sender's side and publish it as a whole to the receiver.

If you have a fairly closed scope for channels in mind, could you elaborate such use-cases in the kdoc? Currently it leaves me puzzled as to why this is the only case presented, even though I can see that I can use it in other ways.

Yes, it's a good idea to mention Flow (which take over most of the typical use cases for Channel) in the Channel documentation: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/

Certainly out of scope of this PR, though.

Sure, but I still can't verify if that's the only reasonable use-case worth mentioning.

murfel · 2025-10-25T12:55:01Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+ *         channel.consumeTo(remainingElements)
+ *     } finally {
+ *         println("Remaining elements: $remainingElements")
+ *     }


A more closer example would be to have a channel which is can be closed with a cause, to separate the usage of this function from just channel.toList()

Also would be nice to show an example when consumeTo is used before the channel is definitely closed.

(This example could approach this by just removing delay on L251)

I'm a bit wary that you are advocating exclusively for one particular use-case, here in the sample and in the kdoc.

Let's discuss the intention of this API and samples on Monday!

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

murfel · 2025-10-28T11:17:25Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

- *     while (Random.nextInt() % 100 != 42) {
+ *     while (Random.nextInt() % 100 != 0) {


It's better to teach users to use even adjacent things properly. Random.nextInt(100) requires less random bits per invokation and is also genuinely uniformly distributed.

murfel · 2025-10-28T12:36:55Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

 * check(channel.toList() == values)
 * ```
 */
 public suspend fun <E> ReceiveChannel<E>.toList(): List<E> = buildList {


Ah, found it.

It should be placed (or duplicated) at the end, near the description of its terminal behaviour, since it's logically connected.

murfel · 2025-10-28T12:40:44Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+ * [consumeTo] attempts to receive elements and put them into the collection until the channel is
+ * [closed][SendChannel.close].
+ *
+ * If the channel is [closed][SendChannel.close] with a cause, [consumeTo] will rethrow that cause.


Nevermind, I short circuited (and also misread the docs). Please do add when exactly the exception will be rethrown, though.

The channel could still contain elements that will never be received.

Elaborate this whole scenario.

murfel · 2025-10-28T12:43:17Z

kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+ * In practice, this means that if adding new elements to the collection fails with an exception,
+ * that exception will be used for [cancelling][ReceiveChannel.cancel] the channel and rethrown.
+ *
+ * The intended use case for this function is collecting the remaining elements of a closed channel


If you have a fairly closed scope for channels in mind, could you elaborate such use-cases in the kdoc? Currently it leaves me puzzled as to why this is the only case presented, even though I can see that I can use it in other ways.

murfel · 2025-10-28T12:43:57Z

Each consume-like function has a very similar description. Could you unify these descriptions? Since they are saying the same thing with different words. Or worse, give slightly different information.

E.g. consume and consumeEach both end with

consume

 * [consume] does not guarantee that new elements will not enter the channel after [block] finishes executing, so
 * some channel elements may be lost.
 * Use the `onUndeliveredElement` parameter of a manually created [Channel] to define what should happen with these
 * elements during [ReceiveChannel.cancel].

consumeEach

 * **Pitfall**: even though the name says "each", some elements could be left unprocessed if they are added after
 * this function decided to close the channel.
 * In this case, the elements will simply be lost.
 * If the elements of the channel are resources that must be closed (like file handles, sockets, etc.),
 * an `onUndeliveredElement` must be passed to the [Channel] on construction.
 * It will be called for each element left in the channel at the point of cancellation.

dkhalanskyjb requested a review from murfel September 10, 2025 08:16

murfel reviewed Sep 10, 2025

View reviewed changes

kotlinx-coroutines-core/common/src/channels/Channels.common.kt Outdated Show resolved Hide resolved

kotlinx-coroutines-core/common/src/channels/Channels.common.kt Show resolved Hide resolved

Keep only one overload

2d8f52b

dkhalanskyjb force-pushed the dkhalanskyjb/Channel.toList(destination) branch from 63b1e1a to 2d8f52b Compare September 10, 2025 10:49

murfel reviewed Sep 10, 2025

View reviewed changes

kotlinx-coroutines-core/common/src/channels/Channels.common.kt Outdated Show resolved Hide resolved

murfel reviewed Sep 10, 2025

View reviewed changes

kotlinx-coroutines-core/common/src/channels/Channels.common.kt Outdated Show resolved Hide resolved

dkhalanskyjb force-pushed the dkhalanskyjb/Channel.toList(destination) branch from 4992f06 to aa1adf1 Compare September 10, 2025 11:04

Fixup

6039cf8

dkhalanskyjb force-pushed the dkhalanskyjb/Channel.toList(destination) branch from aa1adf1 to 6039cf8 Compare September 10, 2025 11:05

murfel approved these changes Sep 10, 2025

View reviewed changes

murfel self-requested a review October 9, 2025 09:43

Introduce ReceiveChannel.consumeTo

caed24d

dkhalanskyjb force-pushed the dkhalanskyjb/Channel.toList(destination) branch from 938369e to caed24d Compare October 14, 2025 10:41

murfel requested changes Oct 25, 2025

View reviewed changes

Implement the corrections

e096635

murfel reviewed Oct 28, 2025

View reviewed changes

murfel requested changes Oct 28, 2025

View reviewed changes

	* It is useful for testing code that uses channels to observe the elements the channel contains at the end of the test.
	* It is useful for testing to observe the elements the channel contains at the end of the test.

	* Please use [consumeAsFlow] and [kotlinx.coroutines.flow.toCollection] for such advanced use-cases.
	* Please use either [consumeTo] or [consumeAsFlow] and [kotlinx.coroutines.flow.toCollection] for such advanced use-cases.

	* If the channel is [closed][SendChannel.close] with a cause, [consumeTo] will rethrow that cause.
	* If the channel is [closed][SendChannel.close] with a cause, [consumeTo] will rethrow that cause immediately.
	* The channel could still contain elements that will never be received.

		* while (Random.nextInt() % 100 != 42) {
		* while (Random.nextInt() % 100 != 0) {

Uh oh!

Add ReceiveChannel.toList(destination) #4520

Are you sure you want to change the base?

Add ReceiveChannel.toList(destination) #4520

Conversation

dkhalanskyjb commented Sep 10, 2025

Uh oh!

murfel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

murfel commented Oct 9, 2025

Uh oh!

dkhalanskyjb commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

murfel commented Oct 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

murfel commented Oct 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

dkhalanskyjb commented Oct 14, 2025 •

edited

Loading