kotlin-coroutines-structured-concurrency

Kotlin coroutines: structured concurrency

Core principle

A well-structured coroutine is a self-contained unit of asynchronous work — single entry, single exit, scoped to a lifecycle known at the call site.

Scopes should usually be tied to the caller's lifecycle, not stored as a property on the callee. A stored CoroutineScope is a strong review signal: the class must prove it owns cancellation, error reporting, restart behavior, and lifecycle. Most repositories, processors, and data sources cannot prove that, so they should expose suspend APIs instead. This project's canonical example is DataProcessor.kt, which injects a CoroutineDispatcher and exposes suspend/Flow APIs rather than owning a scope.

The fix is almost always the same: make the API suspend and let the caller own the scope.

When to use this skill

You're writing or reviewing Kotlin code and you see any of these:

• A class with private val scope: CoroutineScope (constructor param stored as a property)
• An init { scope.launch { ... } } block
• A non-suspending public function whose body is scope.launch { ... }
• runBlocking { ... } in suspend-capable application code, or in tests where runTest should apply
• runCatching { suspendCall() } or a catch on Exception / Throwable around a suspend call without rethrowing CancellationException
• A catch (e: CancellationException) (or equivalent) around suspension that does not rethrow

The silent-cancellation bug

The reason an unowned CoroutineScope property is so dangerous: once a scope is cancelled, every future launch on it silently completes as cancelled — no exception, no log, nothing. The work just doesn't happen. This is one of the hardest coroutine bugs to diagnose, and it appears when a class holds a long-lived reference to a lifecycle it does not own.

If APIs are suspend, this can't happen: the caller's scope is either alive (work runs) or the call site cancels (the caller knows).