Improve invokeOnCompletion and invokeOnCancellation API

[qwwdfsad]

trafficstars

• [ ] Revisit documentation, explicitly spell out the purpose of the API, samplify
• [ ] Mark it as delicate API
• [ ] Short-cut it if necessary (#3259)
• [ ] Shift #3505 and #4154 towards a different API shape

[qwwdfsad]

Also, we have #3065 which is similar to this one, but in a slightly different scope

[bubenheimer]

I'm pretty sure that I do not want to mark all my completely safe usages of invokeOnCompletion() with @DelicateCoroutinesApi. It's no more delicate than many other everyday coroutines concepts.

I have seen @DelicateCoroutinesApi being overused for other APIs already.

I do not see the alternatives to invokeOnCompletion() being more compelling, in general, in terms of readability a.k.a. potential for errors. Of course, once you add @DelicateCoroutinesApi, that will change, because using invokeOnCompletion() will be a PITA.

[dkhalanskyjb]

@bubenheimer,

I do not want to mark all my completely safe usages of invokeOnCompletion() with @DelicateCoroutinesApi

I have seen @DelicateCoroutinesApi being overused for other APIs already.

If you feel that you are proficient in kotlinx.coroutines, please use a global opt-in:

kotlin {
    compilerOptions {
        optIn.add("kotlinx.coroutines.DelicateCoroutinesApi")
    }
}

It's no more delicate than many other everyday coroutines concepts.

I heavily disagree. It's often unpredictable in which thread pool (if any) the handler runs; you are not allowed to throw exceptions from there; you are not allowed to make blocking calls from there. These limitations are almost unique to invokeOnCompletion when it comes to coroutine code.

I do not see the alternatives to invokeOnCompletion() being more compelling, in general, in terms of readability a.k.a. potential for errors.

Not having to audit the code in the handler carefully for whether its execution context will always be correct and whether the code can throw does count towards readability.

[bubenheimer]

I have seen @DelicateCoroutinesApi being overused for other APIs already.

If you feel that you are proficient in kotlinx.coroutines, please use a global opt-in:

I don't think a global opt-in can address the point of perceived overuse of @DelicateCoroutinesApi. "Overuse" implies that it is useful for certain things. Few people, if any, could validly claim proficiency in the entirety of kotlinx.coroutines, present and future.

What I am saying is that the more APIs become @DelicateCoroutinesApi, the less meaningful and useful the annotation becomes for users, other than as a cop-out.

The solution I see is to individualize the ability to enable/disable "delicate" warnings on a per-API basis, rather than only a per-use basis. Alternatively, with enough resources one could globally disable @DelicateCoroutinesApi and create custom checker rules for each API. I don't have those resources.

[dkhalanskyjb]

That's fair. If you think that some DelicateCoroutinesApi-marked API entry that is often, not just occasionally, the best tool for the job, then please open an issue for marking it non-delicate, and we'll consider it.

invokeOnCompletion is idiomatic for implementing concurrent data structures that interoperate with kotlinx.coroutines, which most codebases never encounter. From reading the invokeOnCompletion usages, this function is more likely to be misused for resource cleanups and similar unsupported use cases than it is to be used safely: https://grep.app/search?q=invokeOnCompletion

[bubenheimer]

That's fair. If you think that some DelicateCoroutinesApi-marked API entry that is often, not just occasionally, the best tool for the job, then please open an issue for marking it non-delicate, and we'll consider it.

This is not the point that I was making, and I doubt that an issue within those narrow parameters makes sense. I use invokeOnCompletion in specific and safe ways across my codebase, which this issue intends to make harder.

In absence of other options I will have to globally disable @DelicateCoroutinesApi for all affected APIs, not just invokeOnCompletion, as suppressing it individually at each usage site is becoming increasingly counterproductive.

I am holding out hope for an eventual alternative to this annoying infatuation with an all-or-nothing approach.

[murfel]

Request summary: introduce a global opt-in for @DelicateCoroutinesApi per each api individually.