Android Coroutines Expert Skill

This skill provides authoritative rules and patterns for writing production-quality Kotlin Coroutines code on Android. It enforces structured concurrency, lifecycle safety, and modern best practices (2025 standards).

Responsibilities

• Asynchronous Logic: Implementing suspend functions, Dispatcher management, and parallel execution.
• Reactive Streams: Implementing

  Flow

  ,

  StateFlow

  ,

  SharedFlow

  , and

  callbackFlow

  .
• Lifecycle Integration: Managing scopes (

  viewModelScope

  ,

  lifecycleScope

  ) and safe collection (

  repeatOnLifecycle

  ).
• Error Handling: Implementing

  CoroutineExceptionHandler

  ,

  SupervisorJob

  , and proper

  try-catch

  hierarchies.
• Cancellability: Ensuring long-running operations are cooperative using

  ensureActive()

  .
• Testing: Setting up

  TestDispatcher

  and

  runTest

  .

Applicability

Activate this skill when the user asks to:

• "Fetch data from an API/Database."
• "Perform background processing."
• "Fix a memory leak" related to threads/tasks.
• "Convert a listener/callback to Coroutines."
• "Implement a ViewModel."
• "Handle UI state updates."

Critical Rules & Constraints

1. Dispatcher Injection (Testability)

• NEVER hardcode Dispatchers (e.g.,

  Dispatchers.IO

  ,

  Dispatchers.Default

  ) inside classes.
• ALWAYS inject a

  CoroutineDispatcher

  via the constructor.
• DEFAULT to

  Dispatchers.IO

  in the constructor argument for convenience, but allow it to be overridden.

// CORRECT
class UserRepository(
    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) { ... }

// INCORRECT
class UserRepository {
    fun getData() = withContext(Dispatchers.IO) { ... }
}

2. Main-Safety

• All suspend functions defined in the Data or Domain layer must be main-safe.
• One-shot calls should be exposed as

  suspend

  functions.
• Data changes should be exposed as

  Flow

  .
• The caller (ViewModel) should be able to call them from

  Dispatchers.Main

  without blocking the UI.
• Use

  withContext(dispatcher)

  inside the repository implementation to move execution to the background.

3. Lifecycle-Aware Collection

• NEVER collect a flow directly in

  lifecycleScope.launch

  or

  launchWhenStarted

  (deprecated/unsafe).
• ALWAYS use

  repeatOnLifecycle(Lifecycle.State.STARTED)

  for collecting flows in Activities or Fragments.

// CORRECT
viewLifecycleOwner.lifecycleScope.launch {
    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState.collect { ... }
    }
}

4. ViewModel Scope Usage

• Use

  viewModelScope

  for initiating coroutines in ViewModels.
• Do not expose suspend functions from the ViewModel to the View. The ViewModel should expose

  StateFlow

  or

  SharedFlow

  that the View observes.

5. Mutable State Encapsulation

• NEVER expose

  MutableStateFlow

  or

  MutableSharedFlow

  publicly.
• Expose them as read-only

  StateFlow

  or

  Flow

  using

  .asStateFlow()

  or upcasting.

6. GlobalScope Prohibition

• NEVER use

  GlobalScope

  . It breaks structured concurrency and leads to leaks.
• If a task must survive the current scope, use an injected

  applicationScope

  (a custom scope tied to the Application lifecycle).

7. Exception Handling

• NEVER catch

  CancellationException

  in a generic

  catch (e: Exception)

  block without rethrowing it.
• Use

  runCatching

  only if you explicitly rethrow

  CancellationException

  .
• Use

  CoroutineExceptionHandler

  only for top-level coroutines (inside

  launch

  ). It has no effect inside

  async

  or child coroutines.

8. Cancellability

• Coroutines feature cooperative cancellation. They don't stop immediately unless they check for cancellation.
• ALWAYS call

  ensureActive()

  or

  yield()

  in tight loops (e.g., processing a large list, reading files) to check for cancellation.
• Standard functions like

  delay()

  and

  withContext()

  are already cancellable.

9. Callback Conversion

• Use

  callbackFlow

  to convert callback-based APIs to Flow.
• ALWAYS use

  awaitClose

  at the end of the

  callbackFlow

  block to unregister listeners.

Code Patterns

Repository Pattern with Flow

class NewsRepository(
    private val remoteDataSource: NewsRemoteDataSource,
    private val externalScope: CoroutineScope, // For app-wide events
    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) {
    val newsUpdates: Flow<List<News>> = flow {
        val news = remoteDataSource.fetchLatestNews()
        emit(news)
    }.flowOn(ioDispatcher) // Upstream executes on IO
}

Parallel Execution

suspend fun loadDashboardData() = coroutineScope {
    val userDeferred = async { userRepo.getUser() }
    val feedDeferred = async { feedRepo.getFeed() }
    
    // Wait for both
    DashboardData(
        user = userDeferred.await(),
        feed = feedDeferred.await()
    )
}

Testing with runTest

@Test
fun testViewModel() = runTest {
    val testDispatcher = StandardTestDispatcher(testScheduler)
    val viewModel = MyViewModel(testDispatcher)
    
    viewModel.loadData()
    advanceUntilIdle() // Process coroutines
    
    assertEquals(expectedState, viewModel.uiState.value)
}