In `callbackFlow` when should I use `cancel CancellationExce

Question

In `callbackFlow` when should I use `cancel CancellationException e ` and when should I just throw the exception Is there any difference

Dominaezzz · Answer

I m pretty sure just throwing the exception will end up calling `cancel` somewhere internally the channel has to be released somehow right I guess calling `cancel` is a bit better since you can specify more info about cancellation with a string

dave08 · Answer

That s what I was thinking wink just was wondering if there was a better reason since the example in the function docs uses that It also feels a bit funny to create the `CancellationException` there shouldn t `cancel` just recieve its parameters directly It seems like that function only takes in a `CancellationException` anyways

Adam Powell · Answer

this line of questioning implies a potential misunderstanding about cancellation vs errors

Adam Powell · Answer

`callbackFlow` uses a `ProducerScope` that is backed by a channel Your `callbackFlow` is the sender and the downstream collector is the receiver

Adam Powell · Answer

if an error is being reported to your callback and you want to report it downstream you should do so using `close cause Throwable ` not cancel

Adam Powell · Answer

the `cancel` method is in scope as an extension for `CoroutineScope` the scope that you can launch into for parallel decomposition etc It s not for reporting errors That s why it restricts you to `CancellationException` only

dave08 · Answer

Funny so this is wrong <https github com Kotlin kotlinx coroutines blob 99b78e418796412ee739ff799af39eaa420a1a92 kotlinx coroutines core common src flow Builders kt L285>

dave08 · Answer

Very nice explanation by the way so really cancel would just cause the upstream s scope to be cancelled but wouldn t `close` be called anyways on the channel in such a case

Adam Powell · Answer

thinking face < Vsevolod Tolstopyatov JB > what was the intention there That looks like a very strange example Considering an API call failure to be cancellation rather than an error in a flow doesn t seem right

Adam Powell · Answer

< dave08> yes had to check the source to be sure of the exact mechanism just in case slightly smiling face as a producer coroutine scope is cancelled it closes the channel

dave08 · Answer

And closing the channel cancels the scope

dave08 · Answer

If it works either way then it would just be an issue of semantics

dave08 · Answer

Third possibility just throw an exception it ll probably also cancel the scope and close the channel face with thermometer

Adam Powell · Answer

it looks like closing the channel doesn t cancel the scope the dependency is the other way around for producers

dave08 · Answer

And just throwing an exception

Adam Powell · Answer

and the question is where do you throw the exception from If you re in a callback that s receiving an exception as a parameter you re on the call stack of something not in a coroutine Throwing will just throw to the callback s caller not to the flow

Adam Powell · Answer

that s why you can `close e ` to the `callbackFlow` s channel instead that will make the receiver the flow resume with the close exception

Adam Powell · Answer

and it won t lose the other objects you sent offered to the channel ahead of it

dave08 · Answer

Very good point but you mean `cancel` since it closes the channel too or do you still think `close` should be used

Adam Powell · Answer

`close` When it comes to channels `close` is the sender side operation `cancel` is the receiver side operation

Adam Powell · Answer

`cancel` on a channel means I cannot will not receive any more items let the sender know and any still lingering in the buffer will be lost

Adam Powell · Answer

`close` means here s the end of this sequence of items and possibly a throwable cause if the end of sequence is happening for an exceptional reason All of the items sent to the channel before it will still be received before the close signal is

dave08 · Answer

But here we re talking about the `cancel` on the `ProducerScope` not the `cancel` on the actual channel

Adam Powell · Answer

that s right Since `ProducerScope` implements `SendChannel` but not `ReceiveChannel` the channel cancel method isn t even available

Adam Powell · Answer

only the convenience method to cancel a whole `CoroutineScope` which is more often used when cancelling a scope externally e g ```val myScope = CoroutineScope Dispatchers Main + Job override fun onDestroy myScope cancel ```

dave08 · Answer

Oh I think things are clearer now thanks for this explanation So really this should never be called in a `callbackFlow`

dave08 · Answer

Since the receiver in a `Flow` doesn t even have access to that scope anyways so nobody s there to say I can t receive things anymore in that particular way

Adam Powell · Answer

I wouldn t anyway Even outside of the case of flows and channels I haven t found much reason to use that scope extension from inside the scope of its receiver vs simply throwing a `CancellationException` You immediately end up in cooperative cancellation limbo where `isActive` is now false but your code in a cancelled job is still running

Adam Powell · Answer

another useful thought experiment here is this ```try myFlow collect catch ``` what do you want your flow s users to write in the ` ` spots

Adam Powell · Answer

how should they handle errors produced by your flow You probably don t want them to have to catch `CancellationException` check the `cause` then re throw if it s a real coroutine cancellation vs a reported error from your flow you want them to be able to catch your exception type

Adam Powell · Answer

and `close e ` gives you that

Adam Powell · Answer

also thanks to some debugging related things coroutines do with exception cloning and causes to try to provide more helpful stack traces checking the cause of a `CancellationException` like that has major additional issues you might have to unwrap several layers

dave08 · Answer

Well there s the `catch ` operator which probably gives that `CancellationException` too with `cancel` face with head bandage whereas with `close` it would just give `e` But you re saying with `collect ` the `close e ` even with the `Exception` parameter wouldn t throw a `CancellationException` it would just throw the `e` itself This is also a good point I guess that example in the repo is wrong

Adam Powell · Answer

yeah that example has me scratching my head it doesn t result in code I would want to be the caller of

Adam Powell · Answer

and depending on how other flow operators in the chain look it might even be possible to construct a chain where the cancellation isn t reported downstream at all and is treated as a successful end of flow instead if it ends up being collected as part of some internal child job