Add ReceiveChannel.consumeTo(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.

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

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.

I don't see how that's connected. Terminal only means that the operation cancels the channel, which does get mentioned.

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.

Please do add when exactly the exception will be rethrown, though.

What happens there is inherent to the behavior of closing the channel: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/close.html

Elaborate this whole scenario.

The text you quote is incorrect, closing the channel still allows accessing all elements there.

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

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

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

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.

The way to trigger the pitfall that used to be described can be boiled down to this pattern: ```kotlin run { channel.consumeEach { if (channel.isEmpty) { // do something return@run } else { // do something else } } } ``` However, here, `isEmpty` is already introducing a race condition, so `consumeEach` itself does not cause any additional issues. This does not seem like a pitfall in realistic scenarios after all. `consumeEach` can perform an early return and thus erase the elements present in the channel, but this also goes for elements that possibly entered the channel long ago; without explicitly checking if the channel is empty, there is no way to distinguish these two scenarios.

dkhalanskyjb · 2025-10-29T06:21:23Z

Good job noticing the discrepancy, fixed it.

murfel

The kdocs still have many discrepancies, the ones I mentioned and other, but that is a non-goal of the PR. Otherwise no concerns.

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

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

murfel requested changes Oct 28, 2025

View reviewed changes

dkhalanskyjb added 2 commits October 29, 2025 06:48

Use the idiomatic Random.nextInt in a snippet

0ba4bc8

dkhalanskyjb requested a review from murfel October 29, 2025 06:22

murfel approved these changes Nov 4, 2025

View reviewed changes

dkhalanskyjb merged commit fdb01da into develop Nov 5, 2025
1 check passed

dkhalanskyjb deleted the dkhalanskyjb/Channel.toList(destination) branch November 5, 2025 07:13

dkhalanskyjb changed the title ~~Add ReceiveChannel.toList(destination)~~ Add ReceiveChannel.consumeTo(destination) Nov 5, 2025

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

Add ReceiveChannel.consumeTo(destination) #4520

Add ReceiveChannel.consumeTo(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!

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!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

murfel commented Oct 28, 2025

Uh oh!

dkhalanskyjb commented Oct 29, 2025

Uh oh!

murfel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dkhalanskyjb commented Oct 14, 2025 •

edited

Loading