Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Deployment and Coroutines

Coroutines in Ktor - Concurrency, Dispatchers and Timeouts

Understand how Ktor handles requests with coroutines. Run calls in parallel with async, move blocking work to Dispatchers.IO, add timeouts, handle cancellation, and run background jobs safely.

Ktor is built on Kotlin coroutines from the ground up. Every request handler is a suspend function: when it waits for a database, an HTTP call or a client, it suspends instead of blocking a thread, and the thread goes off to serve another request. That is why a Ktor server can handle thousands of concurrent requests with a handful of threads. It is also why the biggest performance mistakes in Ktor are about accidentally blocking a thread.

This lesson assumes you know the basics from the Kotlin course (coroutine builders, structured concurrency and dispatchers). Here we apply them to servers: parallel calls inside a handler, blocking code, timeouts, cancellation, and background work.

What a handler really is

Kotlin
get("/dashboard") {
    val user = userService.load(call.userId())      // suspend: may wait for a database
    val orders = orderService.recent(user.id)       // suspend
    call.respond(Dashboard(user, orders))
}

The route lambda runs in a coroutine belonging to the call. If the client disconnects, or the call fails, the coroutine is cancelled, and every child coroutine started inside it is cancelled with it (structured concurrency). You get cleanup for free, as long as you start work as children of the call and not on GlobalScope.

Parallel calls with async

The handler above calls two services one after the other. If each takes 100 ms, the page takes 200 ms. Those two calls are independent, so start them together with coroutineScope and async:

Kotlin
get("/dashboard") {
    val id = call.userId()
    val (user, orders) = coroutineScope {
        val u = async { userService.load(id) }
        val o = async { orderService.recent(id) }
        u.await() to o.await()
    }
    call.respond(Dashboard(user, orders))
}

Total time becomes the slower of the two. If either fails, coroutineScope cancels the other and rethrows, so you never leave an orphaned call running.

Kotlin Sequential vs parallel calls inside a handler

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Three 300 ms calls take about 900 ms one after another and about 300 ms together. Only parallelize independent calls; if the second call needs the result of the first, keep them in order.

The thread-blocking trap

Ktor's engine (Netty by default) uses a small pool of threads, roughly the number of CPU cores. A coroutine that calls a blocking function, such as a JDBC query, Thread.sleep, a blocking file read or heavy CPU work, holds a thread the whole time. With four threads and four blocked requests, the server answers nobody else, even though CPU use is near zero.

The fix is to move blocking work to Dispatchers.IO, a larger pool meant for it, with withContext:

Kotlin
suspend fun <T> dbQuery(block: () -> T): T =
    withContext(Dispatchers.IO) { transaction { block() } }

get("/tasks") {
    val tasks = dbQuery { Tasks.selectAll().map { it.toTask() } }
    call.respond(tasks)
}

For heavy CPU work (image resizing, hashing a large file) use Dispatchers.Default, which is sized to the CPU. A rule of thumb: suspend means waiting without a thread; blocking means waiting with one. If a library has both, choose the suspend version (the Ktor client, R2DBC, kotlinx.coroutines timeouts).

Kotlin Blocking vs suspending: why threads run out

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Six blocking requests on two threads need three rounds (about 600 ms). The suspending version overlaps them and takes about 200 ms on the same two threads. Moving the blocking call to Dispatchers.IO frees the engine threads again.

Timeouts

Never wait forever for something you do not control. withTimeout throws TimeoutCancellationException; withTimeoutOrNull returns null instead. Use them around calls to other services and turn the result into a clear HTTP response:

Kotlin
get("/weather") {
    val report = withTimeoutOrNull(2.seconds) { weatherClient.fetch(call.parameters["city"]!!) }
    if (report == null) call.respond(HttpStatusCode.GatewayTimeout, "Weather service is slow")
    else call.respond(report)
}

For the Ktor HTTP client, install the HttpTimeout plugin to set requestTimeoutMillis, connectTimeoutMillis and socketTimeoutMillis globally.

Kotlin Timeouts, fallbacks and cancellation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Note the finally block running when the slow service is cancelled. Cancellation is cooperative: it is delivered at suspension points like delay, and cleanup code in finally still runs. If you must suspend inside finally, wrap it in withContext(NonCancellable).

Cancellation and client disconnects

When a client closes the connection, Ktor cancels the call's coroutine. Long computations should check ensureActive() or isActive periodically, otherwise a cancelled request keeps burning CPU. Standard suspending functions (delay, channel operations, the Ktor client) already check for cancellation.

Be careful with catch (e: Exception): it also catches CancellationException, and swallowing it breaks cancellation. Rethrow it:

Kotlin
try { work() } catch (e: CancellationException) { throw e } catch (e: Exception) { log.warn("failed", e) }

Background work that outlives a request

Sometimes a request should start work that finishes later, such as sending an email or generating a report. Do not launch it in the call's scope (it would be cancelled when the response ends) and avoid GlobalScope (nothing owns it). Create an application-level scope tied to the application lifecycle:

Kotlin
fun Application.module() {
    val backgroundScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    monitor.subscribe(ApplicationStopping) { backgroundScope.cancel() }

    routing {
        post("/reports") {
            val id = UUID.randomUUID().toString()
            backgroundScope.launch { reportService.generate(id) }
            call.respond(HttpStatusCode.Accepted, mapOf("id" to id))
        }
    }
}

SupervisorJob keeps one failed job from cancelling its siblings. Respond 202 Accepted with an id, and offer GET /reports/{id} so the client can poll. For work that must not be lost when the server restarts, use a durable queue instead of in-memory coroutines.

Shared mutable state

Coroutines run on multiple threads. A plain mutableMapOf or an Int counter that several requests modify is a data race. Options: ConcurrentHashMap, AtomicInteger, a Mutex around a critical section (mutex.withLock { }), or confine the state to one coroutine and talk to it through a channel (an actor).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does calling Thread.sleep or a blocking JDBC query directly in a handler hurt?

    Blocking keeps a thread occupied; suspending releases it.
  2. 2. Three independent 300 ms calls inside coroutineScope with async take about:

    They run concurrently, so the total is the slowest call.
  3. 3. What is the problem with catch (e: Exception) around suspending code?

    Swallowing CancellationException stops a coroutine from cancelling properly.
  4. 4. Where should a long-running job that outlives the request be launched?

    An owned application scope survives the request and is cancelled when the app stops.

Summary

  • Handlers are coroutines; suspend instead of block, and use async inside coroutineScope for independent calls.
  • Move blocking code to Dispatchers.IO and heavy CPU to Dispatchers.Default.
  • Always add timeouts to calls you do not control; turn them into clear responses.
  • Cancellation is cooperative; rethrow CancellationException and clean up in finally.
  • Use an application scope with SupervisorJob for background work and protect shared state.

Next: Configuration and Environments