There’s a widespread misunderstanding about how coroutines work, especially regarding context switching, that can lead to less-than-optimal app performance and even a big misunderstanding of their core principles.

Unnecessary calls

Consider a typical scenario involving a Retrofit API, perhaps for fetching user data. A UserRepository might include a function similar to this:

suspend fun getUser(id: String): Result<User> {
    return withContext(Dispatchers.IO) { // Is this really needed?
        try {
            val user = api.getUser(id)
            Result.success(user)
        } catch (e: Exception) {
            Result.failure(e)
        }
    }
}

A common belief among developers is the necessity to always switch the coroutine context using withContext(Dispatchers.IO) when invoking a suspend function, particularly for I/O operations. While this specific example does not introduce a bug or performance issue, it represents an extra, unnecessary line of code. The fundamental misunderstanding here lies in assuming explicit context management is required for every suspend call.

The reality is that functions like Retrofit’s getUser already handle switching the context to the appropriate dispatcher internally. Therefore, there is no need for external context switching in such cases.

Understanding Main Safety

Main Safety dictates that a suspend function should be safe to invoke from any thread, especially the main (UI) thread. This means it should not matter if the suspend function performs:

• An API request
• A database operation
• A long-running, CPU-intensive task

Regardless of the operation, a main-safe suspend function ensures that the calling thread is not blocked.

When is it essential?

A scenario where withContext is absolutely crucial involves a FileReader class designed to read a file from an app’s assets folder:

class FileReader {

    suspend fun readFileAsBytes(filename: String): ByteArray {
        // This is blocking code, but it's not a suspend function itself.
        // If we don't use withContext here, we violate main safety!
        val inputStream = assets.open(filename) // This can block!
        return inputStream.readBytes()
    }

}

If readFileAsBytes is implemented without withContext, the principle of main safety is violated. Developers might even observe that the suspend keyword is grayed out, indicating it effectively does nothing because there are no actual suspending calls within the function.

Even though assets.open() It is a blocking operation, it is not a suspending function. Consequently, if readFileAsBytes is called from the main dispatcher, it will block the actual main (UI) thread.

Witnessing the Lag

To illustrate this, consider an app with a smooth animation. If readFileAsBytes (without withContext) is called to read a large file (e.g., 100MB), a noticeable lag or freeze in the UI animation can be observed. Repeating this operation multiple times can lead to the app completely stalling.

The solution is to wrap the blocking, non-suspending code with withContext(Dispatchers.IO):

class FileReader {
    suspend fun readFileAsBytes(filename: String): ByteArray {
        return withContext(Dispatchers.IO) { // YES! This is needed here!
            val inputStream = assets.open(filename)
            inputStream.readBytes()
        }
    }
}

With withContext(Dispatchers.IO) in place, the suspend keyword is no longer grayed out. This ensures two critical outcomes:

1. The function truly suspends until the file reading completes, providing normal coroutine behavior.

2. It prevents blocking the underlying thread (like the UI thread). withContext ensures that only the corresponding coroutine is blocked, while the underlying thread remains free. This allows UI animations to remain fluid, even during large file reads.

Responsibility at the Lowest Level

To summarize the core principle:

• The responsibility of switching to the correct dispatcher always lies with the function that executes blocking, but not yet suspending code.

• If a suspend function only calls other suspend functions and does not contain any direct blocking code itself, then explicit context switching is not necessary. The nested suspend functions are responsible for their main safety. For instance, Retrofit itself would handle the withContext internally if its underlying network calls were blocking and non-suspending.

• However, if a suspend function contains blocking but non-suspending code (such as assets.open()), then it is absolutely necessary to surround that blocking code with withContext. Failure to do so risks the app’s performance by potentially blocking the main thread.

Understanding this distinction is crucial for developing high-performing, responsive applications with coroutines. It is a complex topic but profoundly important for app performance, architecture, and readability.