What mechanism causes a Kotlin coroutine to suspend? - kotlin

Question

I'm trying to understand kotlin coroutines, I'm coming from C# and there's something I'm not understanding here in kotlin. In this scenario I'm writing a webapi using Kotlin in the Quarkus framework. From what I can tell if I label a controller (or resource) function as a suspend function quarkus will automatically launch it in a coroutine.
The issue i have is i don't know what the preferred method for suspending that coroutine is. The vast majority of examples I see on kotlin coroutines use the delay() function, which internally uses suspendCancellableCoroutine() to suspend the function. That makes sense, but i don't see a lot of example calling suspendCancellableCoroutine() explicitly. I've done some reading about the underlying code that gets generated in a suspend function, and some resources lead me to believe that by virtue of calling another suspend function i'll hit a suspend point and that will suspend my coroutine. In C# i'd usually just call await() from inside my async function to execute the long running code.
In my kotlin setup i have setup an instance of jmeter and i simulate 5 threads calling my API at the same time, while limiting my program to run on a single thread in quarkus. My API then makes a call to another API (i'll call that API, data API from now on), which could be a long running operation. For the purpose of my test my data API has a 1 second sleep in it.
Essentially:
web api controller -> web api processing -> web api calls data api through client -> data API does slow operation
I've tried calling async/await on the call to the data API, which seems to work, JMeter reports that 5 requests are all completed in roughly 1 second, and the logging i have indicates that all 5 requests are handled on a single thread. This feels clunky though. I'm already in a coroutine and now my coroutine is creating a new coroutine (async is a coroutine builder) to execute the long running function.
I've also removed the async/await and updated the call to the data API to be a suspend function as well (though this is a client generated from resteasy client). This also seems to work, but resteasy reactive could be generating something that's doing the suspend for me. I need to work with a simpler example, but in the mean time...
If i'm not using the delay() function in Kotlin, and i'm executing code in a coroutine, what is the preferred method to indicate that a section of code is potentially blocking and my coroutine should be suspended? Do i launch a new coroutine? Call suspendCancellableCoroutine()? Or something else? Probably overthinking this, but i want to make sure i understand this.

Answer 1

The coroutines library provides several suspend functions you can use to suspend in a coroutine or in another suspend function, among them:
withContext
delay
coroutineScope
supervisorScope
suspendCoroutine
suspendCancellableCoroutine
Job.join
Deferred.await
The typical way to convert blocking (long-running synchronous) code into something you can use in a coroutine is to wrap it in withContext(Dispatchers.Default) { } or withContext(Dispatchers.IO) { }. If it's something you use repeatedly, you can write a suspend function for it:
suspend fun foo() = withContext(Dispatchers.IO) {
blockingFoo()
}
but if it's some one-off blocking chunk of code, you can use withContext directly in a coroutine.
Note, using async { }.await() is basically never done. The compiler warns you against it. You should be using withContext instead. Calling await on a Deferred is used either when one coroutine needs a result from some other coroutine that has been passed to it, or when you're working with multiple parallel children coroutines inside a coroutineScope block.
The typical way to convert asynchronous callback-based code into a suspend function so you can use it synchronously in a coroutine is to use suspendCoroutine or suspendCancellableCoroutine. You can look up how to use those. They are pretty low level. Many libraries like Retrofit and Firebase already provide suspend functions you can use instead of the callbacks.
coroutineScope and supervisorScope are for creating a scope inside your coroutine to run multiple children coroutines in parallel and wait for them all.