:mega: :mega: :mega: Do you have ideas for improvi...

# coroutines

[Dmitry Khalanskiy [JB]]

📣 📣 📣 Do you have ideas for improving the coroutines guide? Now's the perfect time to share them!

Spotted a typo? Found something unclear? Noticed something missing? We're rewriting the guide and would love your feedback to make it better for everyone.

Open a new issue with the "Coroutines guide" template— or just drop your thoughts in this thread 🧵 and we'll take care of the rest!

[Joffrey]

It would be great to remove all occurrences of runBlocking. This should be considered an advanced / delicate API, and shouldn't appear in a beginner's guide IMO.

[Dmitry Khalanskiy [JB]]

This is challenging: I'm not sure how to arrive at starting (and waiting for) the first coroutine without runBlocking. The only alternatives I can think of are suspend fun main() { coroutineScope { ... } } and GlobalScope.launch { }; Thread.sleep(1000). Both of them have their own weaknesses. Do you maybe have something specific in mind?

[Joffrey]

I agree we shouldn't use GlobalScope either. suspend fun main (+ optionally coroutineScope { ... } when necessary) was what I had in mind. What weaknesses do you see for this approach? If we expect users to just accept runBlocking as an entrypoint, we may as well make them accept that version instead.

The problem with runBlocking is that it is transposable to many other places than main, and we clearly don't want users to do this unless they think really hard about what that means. With suspend fun main, they can't transpose it, which is good.

[phldavies]

I've seen codebases reach for runBlocking whenever they need to call something suspend from a non-suspend context (i.e. in a close for an AutoCloseable)

[Joffrey]

@phldavies exactly, and this is most of the time wrong. It's easy to get carried away with runBlocking, so we may as well avoid it in the guide.

I opened this issue a while back, and one of the pushbacks was that a lot of materials use runBlocking. Let's start by fixing the official learning materials.

[uli]

Do you have anything on resource handling and withContext? I think there must be tons of potential resource leaks out in the wild where code like this is written:

val socket = withContext(<http://Dispatchers.IO|Dispatchers.IO>) {
  Socket("localhost", 8080)
}
socket.use {
  // ...
}

Would be great if this issue was more widely known. And even more great, if it was clear how to do such allocations right.

[CLOVIS]

@uli see ResourceScope in #C5UPMM0A0

[uli]

Thanks @CLOVIS.
This was meant more as a request to make the issue known and keep developers from tripping into this trap.
At least a warning. Or better a solution.

[louiscad]

I just made a talk on "All coroutines pitfalls" yesterday at Android Makers in Paris, so I have a lot of ideas. I'll share them soon, hoping it's not too late

[Dmitry Khalanskiy [JB]]

It's not too late, please go ahead!

[louiscad]

I'd love to have the opportunity to write the official coroutines guide myself, actually.

I'd document why coroutines exist, what they are, conceptually, then what structured concurrency is, conceptually, and why it exists, then how it works in kotlinx.coroutines, helping people to know how to not break it.

I would also include a section on common pitfalls, and another one on common mistakes.

Is the goal to just make an incremental improvement over what's there, or is the current plan to revamp it somehow?

[louiscad]

I think some illustrations would also help a lot

[Dmitry Khalanskiy [JB]]

@louiscad, the current plan is indeed to revamp the coroutines guide. I've asked the team of writers, and they say that at this point, in terms of organization, it's too late to start such a collaboration, as the process has already begun on their side. Your strong expertise is recognized, and your suggestions would be of great help, including massive structural ones.
Would you be interested in being invited to review the proposed changes?

[louiscad]

Yes, I'd be interested, @Dmitry Khalanskiy [JB]!