Coroutines guide should highlight the dangers of runBlocking

[dkhalanskyjb]

Reported by @joffrey-bion in the Kotlinlang Slack.

Currently, the coroutines guide uses runBlocking freely to explain the concept of coroutines. However, in practice, runBlocking does not have such a prominent role and is often error-prone: #4242

At the top level, there is an alternative to runBlocking:

suspend fun main() {
    coroutineScope {
        // code goes here
    }
}

It's not without its issues, though: it silently introduces multithreading (because no dispatcher is specified, Dispatchers.Default is used).

I don't see a way around using the single-threaded runBlocking for some of the examples, but the issues with runBlocking should be highlighted.

[kevincianfarini]

I mentioned this in #4242, but it's worth noting that suspending main functions aren't supported on native targets yet, only on JVM iirc. runBlocking of course isn't offered on js, but that seems like a much smaller use case than the myriad of native targets.

Would something like this suffice in the guide if runBlocking gets marked as delicate?

// Opt-in to delicate behavior from runBlocking. 
// It should only ever be used when bridging the synchronous world 
// which is known to not be called from any coroutine. 
@OptIn(DelicateCoroutinesApi::class)  
fun main() = runBlocking {
  /* TODO */
}

It might also be good to include examples of bad behavior. Eg:

suspend fun foo() {
  bar()
  baz()
}

suspend fun bar() { /* TODO */ }

fun baz() = runBlocking { // BAD: This is called from a suspending function but invokes runBlocking. 

}