Coroutine Dispatchers: Telling Your Coroutines Which Thread to Use

Why it exists

Modern applications need to perform long-running tasks like complex calculations without freezing the main thread. Coroutines need a mechanism to switch between threads easily to handle this. Dispatchers are that mechanism, providing a structured way to assign work to an appropriate thread.

The mental model

A Dispatcher is like a work scheduler for your coroutines. It looks at the work a coroutine needs to do and assigns it to the right thread or pool of threads. Just as you wouldn't ask your UI designer to do heavy data processing, you use dispatchers to send CPU-intensive work to background threads, keeping the main thread free and responsive.

How it works

Every coroutine runs in a CoroutineContext, and the CoroutineDispatcher is a key part of it. When you launch a coroutine, you can explicitly provide a dispatcher. If you don't, it inherits the dispatcher from its parent CoroutineScope. Common choices include Dispatchers.Default, which uses a shared background pool of threads, or creating a new thread with newSingleThreadContext.

When to use it

You should explicitly specify a dispatcher when you need to ensure a task runs on a particular type of thread. Use Dispatchers.Default for sorting a large list, processing data, or any CPU-bound operation that shouldn't block the calling thread. If a coroutine's work must be confined to a single, dedicated thread, newSingleThreadContext is an option, but it's a resource-intensive one.

When not to use it

Avoid Dispatchers.Unconfined in general code. It starts the coroutine on the current thread but resumes on whatever thread the suspending function used, making its behavior unpredictable. This can lead to subtle bugs or crashes, especially if it attempts to modify state confined to a specific thread. Also, avoid creating threads with newSingleThreadContext unless you have a clear strategy for managing the created thread's lifecycle, as it's an expensive resource that must be closed or reused.

One canonical example

A coroutine launched with Dispatchers.Unconfined on the main thread will start on main. But after a suspending call like delay(), it might resume on a background thread from the default executor pool. In contrast, a coroutine launched in the same scope without a specific dispatcher will inherit the main thread context and resume on the main thread after its delay, ensuring predictable execution.