Consider stabilizing `Channel.invokeOnClose`

[JakeWharton]

It was added in 0.24 and made experimental in 1.0 later that year. Both of those events were 4 years ago. Time to stabilize?

[qwwdfsad]

Indeed, it's time to, thanks for pointing it out.

If you have any other use-cases apart from the linked one (https://github.com/cashapp/zipline/blob/79cd02d6dfd4936c8de20fd3950a68a121fc8aee/zipline/src/commonMain/kotlin/app/cash/zipline/internal/bridge/flows.kt#L74-L83), please don't hesitate to share.

The most interesting questions here are whether more than one handler is ever required (though I believe we can change this particular restriction at any time) and whether exceptions from the handler should be rethrown right from caller's close/cancel even though they are clearly undeclared

[whyoleg]

Have you considered using CompletionHandler in place of plain lambda - it's typealias, so there is no difference except for consistency with CancellableContinuation.invokeOnCancellation(handler: CompletionHandler) and Job.invokeOnCompletion(handler: CompletionHandler)?

[qwwdfsad]

@whyoleg that's an interesting suggestion, thanks. We'll consider this; one of the potential benefits is the ability to align documentation between various handlers