Расширенная шпаргалка по корутинам Kotlin

Предположим, что вы уже какое-то время работаете с Kotlin-корутинами и знакомы с базовыми концепциями, такими как приостанавливаемые (suspend) функции и билдер launch. Однако по мере усложнения проектов вы всё чаще сталкиваетесь с необходимостью искать решения для более продвинутых задач и обращаетесь к поисковым системам или искусственному интеллекту за помощью.

Эта шпаргалка создана как удобный справочник для сложных сценариев работы с корутинами и содержит ключевые идеи, накопленные мной за всё время работы.

Словарь корутин

Контекст корутины (из документации Kotlin): «Набор различных элементов. Основными элементами являются Job корутины и её диспетчер». 

Job (из документации Kotlin): «Отменяемая сущность с жизненным циклом, который завершается по завершении корутины. Каждая корутина создаёт свой собственный Job (это единственный элемент контекста корутины, который не наследуется от родительской корутины). 

Dispatcher: Позволяет выбрать, на каком потоке (или пуле потоков) должна выполняться корутина (как на старте, так и при возобновлении).

Coroutine scope (область видимости корутины): Определяет время жизни и контекст корутины. Она отвечает за управление жизненным циклом корутин, включая их отмену и обработку ошибок.

Coroutine builder (билдеры корутин): это функции-расширения для CoroutineScope, которые позволяют запускать асинхронные корутины (например, launch, async и другие).

Основные правила работы с корутинами

• Для запуска корутины необходим CoroutineScope (например, с помощью launch или async). Чаще всего в Android используется viewModelScope, но можно создать и свою область видимости.

• Дочерняя корутина (корутина, запущенная из другой корутины) наследует контекст корутины-родителя (кроме Job).

• Job корутины-родителя используется в качестве родительского Job для новой корутины. Это создаёт иерархию задач.

• Корутина-родитель приостанавливается до тех пор, пока все её дочерние корутины не завершатся.

• Если корутина-родитель отменяется, то отменяются и все её дочерние корутины.

• Если дочерняя корутина завершилась с необработанным исключением, это исключение приведёт к отмене корутины-родителя (если не используется SupervisorJob, см. ниже).

• Не следует использовать GlobalScope, так как это может привести к утечкам памяти и оставит корутину «живой», даже если активность или фрагмент, из которых она была запущена, уже завершили своё выполнение.

• Не передавайте область видимости корутины в качестве аргумента — вместо этого используйте функцию coroutineScope (пример ниже).

Функции для работы с областью видимости корутин:

• coroutineScope: приостанавливаемая функция, которая запускает область видимости и возвращает значение, произведённое переданной функцией.

• supervisorScope: похожа на coroutineScope, но переопределяет Job контекста, поэтому функция не будет отменена, если дочерняя корутина выбросит исключение.

• withContext: похожа на coroutineScope, но позволяет вносить некоторые изменения в область видимости (обычно используется для того, чтобы задать Dispatcher).

• withTimeout: похожа на coroutineScope, но устанавливает ограничение по времени на выполнение тела, и если оно превышено, функция будет отменена. Выбрасывает TimeoutCancellationException.

• withTimeoutOrNull: аналогична withTimeout, но вернёт null вместо выброса исключения при превышении времени.

Диспетчеры (Dispatchers) 

Запуск корутины в конкретном диспетчере требует ресурсов. При вызове withContext корутина приостанавливается и может ожидать в очереди перед возобновлением (см. ниже, как избежать ненужных повторных запусков).

Dispatchers.Default

• Используется по умолчанию, если диспетчер не задан. 

• Предназначен для выполнения операций, требующих высокой нагрузки на процессор (CPU). 

• Размер пула потоков соответствует количеству ядер на устройстве. 

• Можно ограничить количество потоков, доступных операции, с помощью Dispatchers.Default.limitedParallelism(3).

Dispatchers.Main

• Для Android запускает корутины в основном потоке (UI thread). 

• Важно избегать блокировки этого потока. 

• Не существует в юнит-тестах (при необходимости можно создать собственный Main-диспетчер).

Dispatchers.IO

• Предназначен для выполнения блокирующих операций (ввода-вывода, чтение/запись файлов, доступ к Shared Preferences и т.д.). 

• Размер пула потоков составляет 64 (или соответствует числу ядер, если их больше 64). 

• Использует тот же пул потоков, что и Dispatchers.Default, но с независимыми ограничениями. 

• Применяется для функций, выполняющих блокирующие операции. 

• Для запуска корутины с этим диспетчером: withContext(Dispatchers.IO) { // блокирующая функция }. 

• Можно ограничить количество потоков для операции с помощью Dispatchers.Default.limitedParallelism(3). 

• Использование limitedParallelism с Dispatchers.IO имеет особенность: создаётся новый диспетчер с независимым пулом потоков (лимит может превышать 64).

Dispatchers.Unconfined

• Корутина выполняется в том же потоке, в котором была запущена, без смены потоков. 

• Полезен для юнит-тестов. 

• По производительности это самый «лёгкий» диспетчер, так как не происходит переключения потоков.

• Опасен для использования в продакшене, так как случайное выполнение блокирующего вызова в основном потоке может вызвать проблемы.

Наблюдения по производительности

• Во время приостановки количество используемых потоков не имеет значительного значения.

• При блокировке выполнения, чем больше потоков задействовано, тем быстрее завершатся все корутины.

• При выполнении задач, требующих высокой нагрузки на процессор (CPU), оптимальным будет использование Dispatchers.Default.

• Для задач, требующих большой памяти, увеличение числа потоков может незначительно улучшить производительность.

Чтобы лучше понять, как работают конкурентность, параллелизм и порядок отмены, посмотрите отличное видео Дейва Лидса:

Запуск вызовов параллельно

Когда необходимо выполнить два действия одновременно и дождаться результата обоих перед тем, как вернуть итог:

Если у вас есть доступ к области (например, из ViewModel)

suspend fun getConfigFromAPI(): UserConfig {   // do API call here or any suspend functions }  suspend fun getSongsFromAPI(): List<Song> {   // do API call here or any suspend functions }  fun getConfigAndSongs() {   // scope can be any scope you'd want a typical case would be viewModelScope   scope.launch {     val userConfig = async { getConfigFromAPI() }     val songs = async { getSongsFromAPI()}     return Pair(userConfig.await(), songs.await())   } }

Предположим, у вас есть API с пагинацией, и вы хотите скачать все страницы до того, как показать их пользователю. При этом вы хотите загрузить все страницы параллельно:

suspend fun getSongsFromAPI(page: Int): List<Song> {   // do API call } const val totalNumberOfPages = 10  fun getAllSongs() {   // scope can be any scope you'd want a typical case would be viewModelScope   scope.launch {     val allNews = (0 until totalNumberOfPages)                   .map { page -> async { getSongsFromAPI(page) } }                   .awaitAll()   } }

Примечание по async / await. Корутина начнёт выполнение сразу после вызова. async возвращает объект типа Deferred<T> (в нашем случае Deferred<List<Song>>). Deferred имеет приостанавливаемую функцию await, которая возвращает значение, когда оно готово.

Если у вас нет доступа к области (например, из репозитория)

В вашем репозитории или случае использования (use case) необходимо определить корутину, которая запустит два (или более) вызова параллельно. Проблема в том, что для использования async вам нужна область, но вы находитесь вне ViewModel или Presenter и не имеете здесь доступа к области (не забывайте о том, что передавать область в качестве аргумента — не лучшее решение).

Пример, основанный на нашем сценарии выше:

suspend fun getConfigAndSongs(): Pair<UserConfig, List<Song> = coroutineScope {    val userConfig = async { getConfigFromAPI() }    val songs = async { getSongsFromAPI()}    Pair(userConfig.await(), songs.await()) }

Очистка при отмене корутины

Если корутина отменяется, она сначала переходит в состояние cancelling, прежде чем станет cancelled. В состоянии cancelling у нас есть время для выполнения необходимых действий по очистке, если это требуется (например, очистка локальной базы данных, поскольку операция не завершилась успешно, или выполнение API-запроса, чтобы уведомить сервер о неудаче операции).

Для этого можно использовать блок finally.

viewModelScope.launch {   try {     // call some suspend function here   } finally {     // execute clean up operation here   } }

Однако при очистке нельзя использовать функции приостановки. Если вам нужно выполнить функцию приостановки, следует сделать следующее

viewModelScope.launch {   try {     // call some suspend function here   } finally {     withContext(NonCancellable) {       // execute clean up suspend function here     }   } }

Примечание: Отмена произойдёт в первую точку приостановки. Следовательно, отмена не произойдет, если в функции нет точек приостановки.

Очистка корутины при её завершении

Аналогично очистке при отмене корутины вы можете захотеть выполнить операцию, когда корутина достигает конечного состояния (completed или cancelled).

suspend fun myFunction() = coroutineScope {   val job = launch { /* suspend call here */ }   job.invokeOnCompletion { exception: Throwable ->      // do something here   } }

Как избежать отмены корутины, если один из её дочерних элементов завершился с ошибкой

Вы можете использовать SupervisorJob, и он будет игнорировать все исключения в своих дочерних процессах.

Создание собственной области видимости корутины

val scope = CoroutineScope(SupervisorJob()) // if one throw an error the other coroutine will not be cancelled scope.launch { myFirstCoroutine() } scope.launch { mySecondCoroutine() }

Использование функции области видимости

suspend fun myFunction() = supervisorScope {   // if one throw an error the other coroutine will not be cancelled   launch { myFirstCoroutine() }   launch { mySecondCoroutine() } }

Обработка исключений

suspend fun myFunction() {   try {     coroutineScope {       launch { myFirstCoroutine() }     }   } catch (e: Exception) {     // handle error here   }   try {     coroutineScope {       launch { mySecondCoroutine() }     }   } catch (e: Exception) {     // handle error here   } }

CancellationException не распространяется на своего родителя, отменяется только текущая корутина. Можно расширить CancellationException, чтобы создать свой собственный тип исключения, который не будет распространяться на родителя.

Определите поведение по умолчанию в случае возникновения исключения

Используйте CoroutineExceptionHandler

Может быть использован, чтобы автоматически выйти из системы, когда сервер отвечает, например, с кодом 401.

val handler = CoroutineExceptionHandler { context, exception ->   // define default behaviour like showing a dialog or error message } val scope = CoroutineScope(SupervisorJob() + handler) scope. launch { /* suspend call here */ } scope. launch { /* suspend call here */ }

Запуск вспомогательной операции

Если вы хотите запустить функцию suspend, которая не должна влиять на другие (например, если она выбросит ошибку, то только она не отменит родительскую корутину, а другие отменят).

Пример: вызов аналитики

val nonEssentialOperationScope = CoroutineScope(SupervisorJob())  suspend fun getConfigAndSongs(): Pair<UserConfig, List<Song> = coroutineScope {    val userConfig = async { getConfigFromAPI() }    val songs = async { getSongsFromAPI()}    nonEssentialOperationScope.launch { /* non essential op here */ }    Pair(userConfig.await(), songs.await()) }

Идеально — внедрить nonEssentialOperationScope в класс (упрощает тестирование).

Запуск операции в одном потоке, чтобы избежать проблем с синхронизацией

suspend fun myFunction() = withContext(Dispatchers.Default.limitedParallelism(1)) {   // suspend call here } // Can also use Dispatchers.IO

Для предотвращения проблем синхронизации при многопоточности есть другие подходы:

Вы можете использовать AtomicReference (из Java).

private val myList = AtomicReference(listOf(/* add objects here */))  suspend fun fetchNewElement() {   val myNewElement = // fetch new element here   myList.getAndSet { it + myNewElement } }

Или Mutex

val mutex = Mutex() private var myList = listOf(/* add objects here */)  suspend fun fetchNewElement() {   mutex.withLock {     val myNewElement = // fetch new element here     myList = myList += myNewElement   } }

Избегайте повторного перенаправления корутины на тот же диспетчер

Избегайте ненужных затрат на переключение диспетчера, если мы уже используем Main диспетчер:

// this will only dispatch if it is needed suspend fun myFunction() = withContext(Dispatcher.Main.immediate) {   // suspend call here }

На данный момент только Dispatchers.Main поддерживает немедленное (immediate) выполнение.

Спасибо за прочтение, делитесь своими идеями и профессиональными советами о корутинах. Для глубокого изучения корутин рекомендую прочитать книгу Марцина Москаи (Marcin Moskała).

Научиться разрабатывать тесты для всех платформ, где используется Kotlin, можно на онлайн‑курсе «Kotlin QA Engineer» под руководством экспертов-практиков.