Formally `runBlocking` is a coroutine builder, but...

# coroutines

[marcinmoskala]

Formally runBlocking is a coroutine builder, but its coroutine is bound to the thread, so its behavior is different from async, launch and produce. Is there a name for coroutine builders except for runBlocking?

[Erik]

In a classic Gang of Four design patterns sense, the name 'builder' isn't ideal (it might be confused with the builder pattern, which is not applicable here). They're just functions that create a coroutine with some (optional) arguments. The difference is that the CoroutineScope is inferred from the current thread in runBlocking, while the other functions have the scope as the receiver. That's the only difference I see. However, I'd still call them all coroutine builders, or maybe coroutine factory functions. It is what they do: they build a coroutine for you.

async, launch and produce do return some kind of handle to the coroutine: `Deferred<T>`/`Job`/`Channel<T>`, while runBlocking returns T (depending on the block). But that's just different signatures for different use cases.

[marcinmoskala]

The term "Coroutine builder" is quite well established now. It is referenced many times in documentation. IMHO it is a good name, as it is used to build a coroutine. Just like sequance is a sequance builder, and List is called a list builder.
https://kotlinlang.org/docs/coroutines-basics.html#your-first-coroutine

runBlocking has actually very little in common with async, launch and produce. In nearly all use cases it behaves differently. It needs to be at the top of hierarchy, its body is called in place (place one runBlocking after another and they will will be called sequentially instead of concurrently). It behaves much more like coroutineScope, and no wonder I hear people confusing them and asking about the differences between those two.

[Joffrey]

I agree with @marcinmoskala here, runBlocking does behave more like coroutineScope than other coroutine builders.
I would tend to call other coroutine builders "regular coroutine builders" as opposed to the special runBlocking

[marcinmoskala]

I consider describing runBlocking as atypical off the beat.

[Joffrey]

Yeah I guess that would be best. It really is particular and deserves its own section I guess. It feels like midway between coroutine builders and "coroutine scoping functions", and yet it shouldn't be used inside coroutines - unlike any of the others.

[Erik]

My point was twofold: about the name and about the use cases. The use cases and behaviour of runBlocking are very specific. But note that also with the other builders you can build blocking coroutines that run sequentially if called one after the other: just use a single-threaded blocking context.

Also, they all build coroutines. Coroutines don't specify concurrency or asynchronous behaviour. Their context does. In that sense the name 'coroutine builders' is good.

[Erik]

Regarding an optional alternative name for runBlocking vs the others: implicit vs. explicit coroutine builders? Meh, maybe that's not a good name. I mean that the others are extensions on a coroutine scope, while runBlocking implicitly uses a scope bound to the current thread.