Skip to content

Deprecate abstract coroutine context keys #4522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 27, 2025
Merged

Deprecate abstract coroutine context keys #4522

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions kotlinx-coroutines-core/common/src/CoroutineDispatcher.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ public abstract class CoroutineDispatcher :
AbstractCoroutineContextElement(ContinuationInterceptor), ContinuationInterceptor {

/** @suppress */
@Deprecated("Use ContinuationInterceptor.Key and attempt " +
Copy link
Member

@qwwdfsad qwwdfsad Sep 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a bit of a nuisance.

I would consider coupling this change with introduction of .dispatcher and .dispatcherOrNull extensions on CoroutineContext (not sure about the CoroutineScope).

Copy link
Collaborator Author

@dkhalanskyjb dkhalanskyjb Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what you mean, but this pattern is very niche anyway: https://grep.app/search?f.lang=Kotlin&regexp=true&q=%5B%5E+%5D%5C%5BCoroutineDispatcher%5C%5D

In addition, in most cases, using ContinuationInterceptor instead of CoroutineDispatcher doesn't make any functional difference (or even makes the code a bit more flexible), which means directing the few existing cases to .dispatcher is not ideal.

Copy link
Member

@qwwdfsad qwwdfsad Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've figured, but still see it as a good idea:

  • That's, generally, an informal respect to backwards compatibility and migration paths (i.e. not how we did it with capitalize) for users who do use that
  • The cost of this addition is negligible
  • In the spirit of the standard library, it is a small but really convenient addition when you need it. I believe even I was in need of that quite a few times (I was also pretty sure I created an issue for that, but I failed to find it)

Copy link
Contributor

@LouisCAD LouisCAD Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My 2 cents:

The fact that something is niche shouldn't be the reason to dismiss/remove it.
It should only be a secondary factor, if a main reason justifies the removal/dismissal of something, IMO.

Also, beware that grep.app isn't finding all usages that GitHub search would.

For this case, your link leads to 66 usages, while I got 338 with public-only GitHub search: https://github.com/search?q=%22t%5BCoroutineDispatcher%5D%22+language%3AKotlin&type=code

If the measuring tool you use is minimizing usage of stuff, you'll end believing things are much more niche than they actually are.

That would risk churning more Kotlin devs than you would think if actions are made based on flawed data.

Copy link
Collaborator Author

@dkhalanskyjb dkhalanskyjb Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Louis,

Since you're raising the topic of grep.app's reliability for the second time, I assume you'd appreciate an extended description of the methodology.

Yes, you are right, if something is barely used, it's not a reason to remove it or make it intentionally inconvenient. The criterion for inclusion of an API is that it should either solve a common need or not be easily expressible, but for removal, the harm of the API must outweigh its popularity. A terribly harmful API may get modified or removed even at the cost of far-reaching changes, whereas to remove an API that's just non-idiomatic and has a better alternative, it's enough for it to be niche.

grep.app is indeed not finding all usages. Neither does github, as there is a lot of code that's not on github at all. This is not a problem for our analysis, as the goal is not to evaluate how many codebases will be affected, but what fraction of them correspond to which measure of popularity. https://grep.app/search?q=kotlinx.coroutines.Job or https://grep.app/search?q=kotlinx.coroutines.flow.combine are examples of widely used APIs. https://grep.app/search?q=kotlinx.coroutines.channels.toList is niche.

The distribution of hits on grep.app is a bit different from the one on GitHub, as grep.app filters out duplicate files. If a user copy-pastes a library into their project, it results in additional hits on GitHub but not on grep.app. This means that not only absolute numbers will be different between GitHub and grep.app, but also the relative ones. I link to grep.app, as I believe that copies of libraries are not important for our analysis, since users are unlikely to maintain them on their own, so grep.app's results are more representative.

Another reason to use grep.app is to understand the usage patterns. This is often much more significant than it is to just count usages, as that way, we can learn more about why people are using an API at all and whether we can provide them with a better alternative. Removal of duplicates on the grep.app's side helps us more conveniently sift through the files.

To sum it up, yes, we are aware of the tool's limitations, which is why we would never say "this change will affect 100 codebases." We have no way of knowing. What we can fairly confidently say is, "the usage is dominated by uncommon requirements of a few large foundational codebases that have the resources to fix this."

Please let me know if this answers your doubts.

Copy link
Contributor

@LouisCAD LouisCAD Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello Dmitry,
Thanks for the answer!
I appreciate it, and it makes sense to me.

Copy link
Contributor

@murfel murfel Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I may chip in my 2 cents, I believe we should prioritise moving faster on the minor occasions, rather than being excessively thorough. So I vote not to do anything and merge this already :)

Copy link
Collaborator Author

@dkhalanskyjb dkhalanskyjb Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided against adding the .dispatcher extension, as the typical use case of duplicating another coroutine's dispatcher doesn't need to distinguish between ContinuationInterceptor and CoroutineDispatcher, which means the extension would be .continuationInterceptor.
Otherwise, .dispatcher[OrNull] would hide a subtle bug, as the code would read as, "This context has no dispatcher", when in fact, there is a continuation interceptor, even if it's not actually a dispatcher.
.continuationInterceptor doesn't seem any better than [ContinuationInterceptor] to me, so I don't see the point.

"casting the context element to CoroutineDispatcher instead",
level = DeprecationLevel.WARNING)
// WARNING since 1.11, ERROR since 1.12, remove in 1.13
@ExperimentalStdlibApi
public companion object Key : AbstractCoroutineContextKey<ContinuationInterceptor, CoroutineDispatcher>(
ContinuationInterceptor,
Expand Down
1 change: 0 additions & 1 deletion kotlinx-coroutines-core/common/src/flow/SharingStarted.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,6 @@ private class StartedWhileSubscribed(
.dropWhile { it != SharingCommand.START } // don't emit any STOP/RESET_BUFFER to start with, only START
.distinctUntilChanged() // just in case somebody forgets it, don't leak our multiple sending of START

@OptIn(ExperimentalStdlibApi::class)
override fun toString(): String {
val params = buildList(2) {
if (stopTimeout > 0) add("stopTimeout=${stopTimeout}ms")
Expand Down
6 changes: 2 additions & 4 deletions kotlinx-coroutines-core/common/src/selects/SelectOld.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,19 +122,17 @@ internal suspend inline fun <R> selectUnbiasedOld(crossinline builder: SelectBui
scope.initSelectResult()
}

@OptIn(ExperimentalStdlibApi::class)
private fun <T> CancellableContinuation<T>.resumeUndispatched(result: T) {
val dispatcher = context[CoroutineDispatcher]
val dispatcher = context[ContinuationInterceptor] as? CoroutineDispatcher
Copy link
Contributor

@murfel murfel Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use the explicit ContinuationInterceptor.Key, as per the deprecation advice? Or, alternatively, fix the advice to use the implicit ContinuationInterceptor and fix all usages to be implicit.

I'd mildly prefer all usages in the codebase to be either all ContinuationInterceptor xor all ContinuationInterceptor.Key, not just the ones you touch in this PR.

I don't have a strong opinion, just noticing a tiny inconsistency. Feel free to discard if it makes some sense to keep them different.

Copy link
Collaborator Author

@dkhalanskyjb dkhalanskyjb Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The specific syntax doesn't matter here and can be chosen abritrarily, but for the deprecation message, there is an important distinction.

A ContinuationInterceptor is the general version of a CoroutineDispatcher: something that controls what happens to a coroutine when it's resumed. In this PR, the problem is with ways of referring to a continuation interceptor. Saying "use ContinuationInterceptor instead of a CoroutineDispatcher" is meaningless, as a CoroutineDispatcher is a ContinuationInterceptor, we are already using one. As objects, however, ContinuationInterceptor is equal to ContinuationInterceptor.Key but distinct from CoroutineDispatcher[.Key].

We could say "use the ContinuationInterceptor companion object", or "use the ContinuationInterceptor key", but I prefer ContinuationInterceptor.Key over that, as this gives the user a clear reference to look up.

if (dispatcher != null) {
dispatcher.resumeUndispatched(result)
} else {
resume(result)
}
}

@OptIn(ExperimentalStdlibApi::class)
private fun CancellableContinuation<*>.resumeUndispatchedWithException(exception: Throwable) {
val dispatcher = context[CoroutineDispatcher]
val dispatcher = context[ContinuationInterceptor] as? CoroutineDispatcher
if (dispatcher != null) {
dispatcher.resumeUndispatchedWithException(exception)
} else {
Expand Down
1 change: 0 additions & 1 deletion kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,6 @@ class ShareInTest : TestBase() {
fun testWhileSubscribedCustomAtLeast2() =
testWhileSubscribed(2, SharingStarted.WhileSubscribedAtLeast(2))

@OptIn(ExperimentalStdlibApi::class)
private fun testWhileSubscribed(threshold: Int, started: SharingStarted) = runTest {
expect(1)
val flowState = FlowState()
Expand Down
1 change: 0 additions & 1 deletion kotlinx-coroutines-core/common/test/flow/sharing/SharedFlowScenarioTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,6 @@ class SharedFlowScenarioTest : TestBase() {
private data class ResumeCollecting(val job: TestJob) : Action()
private data class Cancelled(val job: TestJob) : Action()

@OptIn(ExperimentalStdlibApi::class)
private class ScenarioDsl<T>(
val sharedFlow: MutableSharedFlow<T>,
coroutineContext: CoroutineContext
Expand Down
4 changes: 4 additions & 0 deletions kotlinx-coroutines-core/jvm/src/Executors.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@ import kotlin.AutoCloseable
*/
public abstract class ExecutorCoroutineDispatcher : CoroutineDispatcher(), Closeable, AutoCloseable {
/** @suppress */
@Deprecated("Use ContinuationInterceptor.Key and attempt " +
"casting the context element to ExecutorCoroutineDispatcher instead",
level = DeprecationLevel.WARNING)
@ExperimentalStdlibApi
@Suppress("DEPRECATION")
public companion object Key : AbstractCoroutineContextKey<CoroutineDispatcher, ExecutorCoroutineDispatcher>(
CoroutineDispatcher,
{ it as? ExecutorCoroutineDispatcher })
Expand Down
3 changes: 1 addition & 2 deletions kotlinx-coroutines-core/jvm/src/debug/internal/DebugProbesImpl.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,6 @@ internal object DebugProbesImpl {
* Internal (JVM-public) method used by IDEA debugger as of 1.6.0-RC.
* See KTIJ-24102.
*/
@OptIn(ExperimentalStdlibApi::class)
fun dumpCoroutinesInfoAsJsonAndReferences(): Array<Any> {
val coroutinesInfo = dumpCoroutinesInfo()
val size = coroutinesInfo.size
Expand All @@ -186,7 +185,7 @@ internal object DebugProbesImpl {
for (info in coroutinesInfo) {
val context = info.context
val name = context[CoroutineName.Key]?.name?.toStringRepr()
val dispatcher = context[CoroutineDispatcher.Key]?.toStringRepr()
val dispatcher = context[ContinuationInterceptor.Key]?.toStringRepr()
coroutinesInfoAsJson.add(
"""
{
Expand Down
5 changes: 2 additions & 3 deletions kotlinx-coroutines-core/jvm/test/DispatchersToStringTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
@file:OptIn(ExperimentalStdlibApi::class)

package kotlinx.coroutines

import kotlinx.coroutines.scheduling.CORE_POOL_SIZE
import kotlinx.coroutines.scheduling.MAX_POOL_SIZE
import kotlin.coroutines.ContinuationInterceptor
import kotlin.test.*

class DispatchersToStringTest {
Expand Down Expand Up @@ -44,7 +43,7 @@ class DispatchersToStringTest {
assertEquals("12", limitedNamed.limitedParallelism(12, "12").toString())

runBlocking {
val d = coroutineContext[CoroutineDispatcher]!!
val d = coroutineContext[ContinuationInterceptor] as CoroutineDispatcher
assertContains(d.toString(), "BlockingEventLoop")
val limited = d.limitedParallelism(2)
assertContains(limited.toString(), "BlockingEventLoop")
Expand Down
1 change: 0 additions & 1 deletion kotlinx-coroutines-core/native/src/internal/CoroutineExceptionHandlerImpl.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ internal actual fun ensurePlatformExceptionHandlerLoaded(callback: CoroutineExce
}
}

@OptIn(ExperimentalStdlibApi::class)
internal actual fun propagateExceptionFinalResort(exception: Throwable) {
// log exception
processUnhandledException(exception)
Expand Down
1 change: 0 additions & 1 deletion kotlinx-coroutines-core/nativeOther/src/Dispatchers.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ internal actual fun createDefaultDispatcher(): CoroutineDispatcher = DefaultDisp

private object DefaultDispatcher : CoroutineDispatcher() {
// Be consistent with JVM -- at least 2 threads to provide some liveness guarantees in case of improper uses
@OptIn(ExperimentalStdlibApi::class)
private val ctx = newFixedThreadPoolContext(Platform.getAvailableProcessors().coerceAtLeast(2), "Dispatchers.Default")

override fun dispatch(context: CoroutineContext, block: Runnable) {
Expand Down
4 changes: 1 addition & 3 deletions kotlinx-coroutines-debug/test/DumpCoroutineInfoAsJsonAndReferencesTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
@file:Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
package kotlinx.coroutines.debug

import kotlinx.coroutines.testing.*
import com.google.gson.*
import kotlinx.coroutines.*
import kotlinx.coroutines.debug.internal.*
import org.junit.Test
import kotlin.coroutines.*
import kotlin.test.*

@ExperimentalStdlibApi
class DumpCoroutineInfoAsJsonAndReferencesTest : DebugTestBase() {
private data class CoroutineInfoFromJson(
val name: String?,
Expand Down Expand Up @@ -93,7 +91,7 @@ class DumpCoroutineInfoAsJsonAndReferencesTest : DebugTestBase() {
val context = info.context
assertEquals(context[CoroutineName.Key]?.name, infoFromJson.name)
assertEquals(context[CoroutineId.Key]?.id, infoFromJson.id)
assertEquals(context[CoroutineDispatcher.Key]?.toString(), infoFromJson.dispatcher)
assertEquals(context[ContinuationInterceptor.Key]?.toString(), infoFromJson.dispatcher)
}
}
}