kotlin-coroutines

Kotlin Coroutines

Built on structured concurrency: every coroutine runs in a scope; cancellation and errors propagate through the parent–child hierarchy. This reference focuses on the two disciplines most often gotten wrong: who owns the scope, and exception handling that doesn't break cancellation.

Main-safety: the function doing blocking work owns the withContext(ioDispatcher); callers never switch dispatchers before calling a suspend function.

Scope ownership — prefer suspend fun, let the caller own the scope

A stored CoroutineScope on a non-UI class (repository, manager, use case, data source) is a strong review signal: the class would have to prove it owns cancellation, error reporting, restart, and lifecycle — most can't. The fix is almost always make the API suspend and let the caller own the scope.

// DO — suspend fun; the caller owns the scope, cancellation propagates, exceptions surface
class ArticlesRepository(private val dataSource: ArticlesDataSource, private val io: CoroutineDispatcher) {
    suspend fun bookmark(article: Article) = withContext(io) { dataSource.bookmark(article) }
}
class BookmarkViewModel(private val repo: ArticlesRepository) : ViewModel() {
    fun onBookmark(a: Article) { viewModelScope.launch { repo.bookmark(a) } }
}

// DO NOT — store a scope and launch inside the repository
class ArticlesRepository(private val externalScope: CoroutineScope, /* ... */) {
    suspend fun bookmark(a: Article) { externalScope.launch { dataSource.bookmark(a) }.join() }
}

Why stored scopes are dangerous: once that scope is cancelled, every future launch on it completes silently as cancelled — no exception, no log. If the cancellation came from process death or a misconfigured DI graph, the class keeps accepting calls and silently does nothing.

When work must outlive the caller

A write that must survive the user navigating away doesn't belong to the repository — it belongs to a WorkManager job, or a named application-scoped class that deliberately owns its scope (an OfflineBookmarkQueue with an injected applicationScope, cancelled only on process death). The named class makes the lifetime explicit, testable, and observable — unlike a buried externalScope.launch.