Performance, leaks, and the mistakes that only show up under load

The first and most expensive misconception is that `suspend` means concurrent. It does not: a suspending function runs sequentially, exactly like a normal one, and `listOf(a, b, c).map { fetch(it) }` makes three calls one after another. Concurrency is opt-in and always visible — `async` + `awaitAll`, `launch` inside a `coroutineScope`, or `flatMapMerge` on a Flow. When a handler that should take 100 ms takes 300, the first thing to check is whether three independent awaits were written as three sequential statements.

The second is that a coroutine is not free. It is far cheaper than a thread — a suspended coroutine is a small object on the heap, so a hundred thousand of them are unremarkable where a hundred thousand threads are impossible — but each one still carries a `Job`, a context, and continuation objects. Launching one per element of a large collection to do trivial work is slower than a plain loop; the win comes from *waiting* cheaply, not from computing cheaply. Coroutines make I/O-bound work scale; they do nothing for CPU-bound work except let you distribute it explicitly.

The third, and the one that takes production down, is blocking the wrong dispatcher. `Dispatchers.Default` is sized to your CPU count, and Netty's event loop is roughly one thread per core: a single `Thread.sleep`, JDBC call, `RestTemplate` request or `File.readText` on one of those threads removes a meaningful fraction of your entire capacity for its duration. Under load it is not slow, it is a stall. The correct escape hatch is `withContext(Dispatchers.IO) { … }` — a large elastic pool built for exactly this — and the correct destination is a non-blocking driver so you do not need the escape hatch at all.

`Dispatchers.IO` is not unlimited, and treating it as a dumping ground is its own failure mode. It defaults to 64 threads (or the CPU count if larger), and one subsystem that saturates it starves every other blocking call in the process. `Dispatchers.IO.limitedParallelism(n)` carves a capped view for a subsystem — a legacy client, a report generator, an export job — so a slow dependency cannot consume the whole pool. That is a two-word change with the blast radius of a bulkhead.

Leaks in coroutine code are almost always one of two shapes. The first is `GlobalScope`: it has no `Job` that anyone owns, so nothing ever cancels its children, and a coroutine launched there outlives the request, the screen, or the object that started it. The second is a scope you created and never cancelled — a `CoroutineScope(...)` field on a component with no `close()`. Both are found the same way: every `launch` should be traceable to a scope whose lifetime you can name out loud, and if you cannot name it, it is a leak.

`runBlocking` deserves its own warning. It bridges blocking code to suspending code by parking the calling thread until the body completes — which is correct in a `main` function or a test, and a bug anywhere inside a server request. On an event-loop thread it blocks the loop; called from inside another coroutine it blocks a pooled thread and can deadlock outright if the body needs that same limited dispatcher to make progress. If you find `runBlocking` in a handler, the fix is not to tune it, it is to make the caller `suspend`.

Two smaller costs are worth knowing. **Unbounded fan-out**: `list.map { async { call(it) } }.awaitAll()` on a ten-thousand element list issues ten thousand simultaneous requests, which is a denial of service you wrote yourself — bound it with `Semaphore(k)` or `flatMapMerge(concurrency = k)`. And **unbounded buffering**: `Channel.UNLIMITED`, `buffer(Int.MAX_VALUE)` or an ever-growing `MutableSharedFlow` replay turn a producer/consumer mismatch from a slowdown into an out-of-memory error, which is strictly worse because back-pressure would have told you something was wrong.

Measure before you tune. `runTest`'s virtual clock turns "is this pipeline sequential?" into an exact number, so the sequential-versus-buffered question is answered in a test rather than in production. Add `-Dkotlinx.coroutines.debug` to get coroutine names in thread dumps, and name your coroutines so those dumps mean something. And when a handler is slow, check the three usual suspects in order: sequential awaits that should be concurrent, a blocking call on a small dispatcher, and an unbounded fan-out hitting a rate limit — in practice it is nearly always one of those three.