What's the status of `CoroutineDispatcher` as an `...

# coroutines

[Jeff Lockhart]

What's the status of CoroutineDispatcher as an AbstractCoroutineContextKey being annotated ExperimentalSdlibApi? Is this expected to be stable in a coming coroutines library release? Is it pending anything else, or just still incubating before becoming officially stable? I'm assuming there would be a replacement for doing coroutineContext[CoroutineDispatcher] if the API were to change?

[Jeff Lockhart]

Also, I guess I'd ask, is there any other way to perform coroutineContext[CoroutineDispatcher] that's not an experimental API?

[Jeff Lockhart]

Looks like @ExperimentalStdlibApi is coming from AbstractCoroutineContextKey, which was introduced in Kotlin 1.3. I can't find any info about a timeline for when this experimental opt-in might not be required though. I was hoping this might be removed in a kotlinx-coroutines update, but seems it'll have to come in a Kotlin language update first.

[Jeff Lockhart]

Note, I don't personally have an issue opting in, and already opt-in to many experimental APIs in my own libraries. This question is for an upstream dependency that has stricter expectations on API stability, where I opened a PR that uses this API.

[CLOVIS]

already opt-in to many experimental APIs in my own libraries

Note that you really shouldn't be doing that, and should be propagating the experimental annotation instead. Otherwise, users of your library won't know that some code they are calling may break when updating a dependency.

[CLOVIS]

Only end-user projects should @OptIn , not libraries.

[Jeff Lockhart]

If the experimental API that requires opt-in isn't part of the library's public API, isn't this just an implementation detail? I guess if the user were to update a library dependency that requires opt-in to a version that has removed the API, while continuing to use an old version of my library that requires those APIs, this would be a reason. But this same thing is possible for APIs that don't currently require opt-in that may be deprecated and removed in the future.

Assuming I intend to keep the library up to date and migrate to newer APIs as needed, and provide newer version artifacts that would coincide with future dependencies that have changed opt-in APIs, this shouldn't be problematic for users, right?

There are just so many opt-in APIs currently required with native and multiplatform development that would be needed to propagate on a substantial portion of my code, where opting in globally for the project is much simpler.

[CLOVIS]

I guess if the user were to update a library dependency that requires opt-in to a version that has removed the API, while continuing to use an old version of my library that requires those APIs, this would be a reason.

Yes, that's the reason.

But this same thing is possible for APIs that don't currently require opt-in that may be deprecated and removed in the future.

No, because a properly maintained library will only remove things in a major version, after the full depreciation cycle (warning → error → hidden). For example, to my knowledge, not a single symbol has been removed from the standard library yet, they're at most at the ‘hidden’ stage.

Whereas, an opt-in symbol can be removed at any time, on any version. Let's say you depend on Coroutines and use one of their opt-in. The end user may also depend on Kotest, which requests a newer version of Coroutines. Now, your library breaks, because you're calling code that doesn't exist anymore—and the user didn't even touch the version of your library, they just added another completely unrelated one. And in this version, it's worse, because the code would work in production but fail in tests (since Kotest is not used in production).

If you propagate all experimental annotations, the end user knows that stuff may break.

There are just so many opt-in APIs currently required with native and multiplatform development that would be needed to propagate on a substantial portion of my code, where opting in globally for the project is much simpler.

That's true, but that's at the cost of binary-incompatible updates... I tend to use OptIn before 1.0, and propagate after that.

[Jeff Lockhart]

I tend to use OptIn before 1.0, and propagate after that.

This makes sense. My libraries have only been used internally up to now, so I haven't had to worry about consumers not updating to latest version. But I'm about to release my first library publicly. With its internal use, I consider the Android, JVM, iOS, and macOS targets stable, while the Linux and Windows targets are still experimental. So I haven't decided the version to use, whether pre-1.0 or not. But maybe propagating the opt-ins, even with a 1.0 version will help communicate this status (besides being documented as such).

[CLOVIS]

You can also create custom opt-ins for your own library :)

[Jeff Lockhart]

That's true. I'll have to play with how these annotations work between source set expect/actuals. A consumer could be using the same exact common API, which is stable on one target platform and experimental on another.

[louiscad]

I'd ask in a GitHub issue on the kotlinx.coroutines repo. If you do so, please link it here, I'm interested in the answer.

[Jeff Lockhart]

I asked on the original YouTrack issue and got this response.