Kotlinx.coroutines: CoroutineDispatcher's names

[fvasco]

CoroutineDispatcher's names are too heterogeneous (CommonPool, Unconfined) and programmer isn't helped to collate these in the same hierarchy.
Other CoroutineDispatchers have too common name (Swing, JavaFX) and are subjects to name clash: Look And Feel engine can also expose "Swing" and "JavaFX" singletons.

My prosose is to define a common suffix like "CoroutineDispatcher", "CDispatcher" or simply "Dispatcher" to grouping names.

I.E.

1. CommonDispatcher
2. UnconfinedDispatcher
3. SwingDispatcher
4. JavaFXDispatcher

launch(CommonDispatcher) {
    . . .
}

[elizarov]

I'm not convinced that a potential name clash is actually a problem. Can you give some examples as to where you have encountered it?

The argument against this change is that dispatchers are exclusively used as arguments to various coroutine builders: launch, async, produce, etc. This particular usage context gives enough disambiguation to make any kind of "Dispatcher" suffix superfluos (or so it seems).

[fvasco]

This issue raised on my first approach on coroutines.

If we consider Java's List then we can have ArrayList, LinkedList, EmptyList and so on. It is simple to aggregate all these on a single cap.

"Unbounded" and "Swing" are too heterogeneous names, and the argument for "async" method is "CoroutineContext" not "CoroutineDispatcher", so I can wrongly use "Swing" as a coroutine's L&F.

In simple case the code a trained programmer can understand correctly the statement: produce(Unconfined) ...
I fear that in more complex use case a wrong name can lead to confuse code.

[fvasco]

Hi @elizarov,
I have a problem naming a Vert.x's dispatcher, following current convention its name should be "Vertx"?

Any suggestion in well accepted, thanks.

[elizarov]

I'd give it a short name, like Vx. However, I'm still keeping this naming issue open to review the naming before we finalise 1.0 version of kotlinx.coroutines. Short names might be good for slide-ware, but it is not that clear-cut for a larger project.

[elizarov]

There is also a related issue of naming various functions that take dispatchers as their arguments. Might renaming run to runOn help? See also discussion here: https://discuss.kotlinlang.org/t/calling-suspending-function-from-regular-function/3670

[voddan]

My issue with coroutine dispatchers not being organized in a hierarchy is poor discoverability. For example, if I want to use a coroutine builder, but forgot the spelling of a dispatcher I need, there is currently no better option than reading the documentation.

I propose to introduce a global singleton Dispatcher for serving as a hierarchy root. Then all coroutine dispatchers can be its extension properties val Dispatcher.Unconfined get() = ... and be used as Dispatcher.Unconfined.

The cost is that we have to use the prefix. The benefit is that IDE now lists all dispatchers for me.

[elizarov]

@voddan That is an interesting idea. I like it more than just giving them longer names. like XXXDispatcher.

[ScottPierce]

I agree that the coroutine dispatcher naming conflict isn't really an issue. It's somewhat nice that it's short and sweet for something that will be commonly used: launch(UI) { ... }

[elizarov]

Closing this issue. We'll leave the general naming approach as it is (a few top-level names).

[elizarov]

I've reopened this discussion in light of structured concurrency (#410) and the proposed change for the Android dispatcher (#533). The goal is to address two concerns:

• Discoverability of different dispatchers.
• Readability of the code, given the fact that dispatcher is always passed as context parameter and there are different types of context element, so it may not be visually obvious which one is a dispatcher.

The concrete proposal I have on the table is to group all the dispatcher references under Dispatchers object:

• Dispatchers.Default — a default dispatcher for background asynchronous tasks (currently backed by CommonPool, a new dispatcher in the future).
• Dispatchers.IO — a dispatcher for blocking background operations (#79).
• Dispatchers.Main — a dispatcher for Android Main Thread (#533).
• Dispatchers.Swing — a dispatcher for Swing Event Dispatch Thread.
• Dispatchers.JavaFx — a dispatcher for JavaFx Application Thread.

[chrisbanes]

I think Dispatchers.Main is going to confuse people. Maybe Dispatchers.Android.Main to make it clearer?

[LouisCAD]

While Dispatchers.Android.Main is a bit more verbose, it is more consistent against Dispatchers.JavaFx and similar, and allows for Dispatchers.Android.UI extension to access the default UI thread with vsync if needed (see #507).

As LifecycleOwners (Activity, Service, etc) are probably going to be CoroutineScopes by themselves, they would default to Dispatchers.Android.Main, so you'd most likely never have to write it by yourself in your codebase.

[elizarov]

@chrisbanes Let me clarify, that Dispatchers.Main is going to be available only when you program for Android and add kotlinx-coroutines-android dependency, so there should not be any confusion about which Main is that. On the other hand, both JavaFx and Swing can be available when you program for Java Desktop, for example, that is why they are named in a more explicit way.

[chrisbanes]

I like the flexibility of @LouisCAD's suggestion. Being able to provide both Android.Main (async) and Android.UI (vsync) dispatchers, but I agree with @adamp in https://github.com/Kotlin/kotlinx.coroutines/issues/427#issuecomment-403562661 that having two dispatchers would be confusing too.

I still think Dispatchers.Main is an unfortunate name since it's such a generic noun. Maybe Dispatchers.Android to be similar to JavaFx and Swing?