updated async and coroutines chapters with mutex examples

Author: GreyLabsDev

08-coroutines-android.md

@@ -373,6 +373,116 @@ suspend fun <T, R> Iterable<T>.mapParallel(
 
 ## 4.3. Дедупликация одновременных запросов (single-flight)
 
+### Что делает `Mutex`
+
+`kotlinx.coroutines.sync.Mutex` защищает критическую секцию так, чтобы одновременно внутри неё
+находилась только одна корутина. Если mutex уже занят, следующая корутина **приостанавливается**,
+а не блокирует текущий поток. Поэтому `Mutex` подходит для coroutine-кода, в отличие от попытки
+удерживать `synchronized`/`ReentrantLock` через suspension point.
+
+Обычный шаблон:
+
+```kotlin
+private val mutex = Mutex()
+
+suspend fun updateSafely() {
+    mutex.withLock {
+        // Чтение и изменение общего mutable state.
+    }
+}
+```
+
+`withLock` освобождает mutex в `finally`, в том числе если код внутри бросил исключение или корутина
+была отменена. Ожидание свободного mutex cancellable: отменённая ожидающая корутина перестаёт
+претендовать на вход.
+
+Важные свойства:
+
+- `Mutex` защищает **инвариант**, а не отдельную строку кода;
+- он не привязан к потоку: корутина может приостановиться и продолжиться на другом;
+- он не реентерабельный — повторный `withLock` того же mutex из критической секции приводит к зависанию;
+- он сериализует работу, поэтому долгий network/disk вызов под общим mutex допустим только осознанно;
+- для нескольких одновременных разрешений нужен `Semaphore`, а для простой числовой операции часто
+  лучше atomic или `MutableStateFlow.update`.
+
+### Пример 1. Счётчик с составной операцией
+
+`counter++` — это чтение, вычисление и запись, а не одна атомарная операция:
+
+```kotlin
+class SafeCounter {
+    private val mutex = Mutex()
+    private var value = 0
+
+    suspend fun increment() {
+        mutex.withLock {
+            value += 1
+        }
+    }
+
+    suspend fun current(): Int =
+        mutex.withLock { value }
+}
+
+suspend fun countConcurrently(): Int = coroutineScope {
+    val counter = SafeCounter()
+
+    repeat(1_000) {
+        launch(Dispatchers.Default) {
+            counter.increment()
+        }
+    }
+
+    // coroutineScope дождётся всех launch перед возвратом.
+    counter
+}.current()
+```
+
+Для одного счётчика `AtomicInteger` проще и быстрее. Пример показывает базовую механику; `Mutex`
+становится особенно полезен, когда одним действием нужно согласованно изменить несколько значений.
+
+### Пример 2. Атомарный перевод между счетами
+
+Проверка баланса и обе записи составляют один инвариант, поэтому находятся в одной критической секции:
+
+```kotlin
+class Wallet {
+    private val mutex = Mutex()
+    private val balances = mutableMapOf<String, Long>()
+
+    suspend fun deposit(account: String, amount: Long) {
+        require(amount > 0)
+        mutex.withLock {
+            balances[account] = balances.getOrDefault(account, 0L) + amount
+        }
+    }
+
+    suspend fun transfer(
+        from: String,
+        to: String,
+        amount: Long,
+    ) {
+        require(amount > 0)
+
+        mutex.withLock {
+            val sourceBalance = balances.getOrDefault(from, 0L)
+            require(sourceBalance >= amount) { "Insufficient funds" }
+
+            balances[from] = sourceBalance - amount
+            balances[to] = balances.getOrDefault(to, 0L) + amount
+        }
+    }
+
+    suspend fun snapshot(): Map<String, Long> =
+        mutex.withLock { balances.toMap() }
+}
+```
+
+Если защищать списание и зачисление разными lock-вызовами, другая корутина сможет увидеть
+промежуточное состояние, в котором деньги уже списаны, но ещё не зачислены.
+
+### Продвинутый пример: single-flight
+
 ```kotlin
 class SingleFlight<K, V>(private val scope: CoroutineScope) {
     private val mutex = Mutex()

11-concurrency-deep.md

@@ -523,6 +523,135 @@ Kotlin, кстати, защищает от родственной ошибки
 И обязательная оговорка: корутины гонки **не устраняют**. Внутри одной корутины код последователен,
 но несколько дочерних корутин работают параллельно и на разных потоках.
 
+## 12.1. `Mutex`: семантика и правильное применение
+
+`kotlinx.coroutines.sync.Mutex` — coroutine-friendly взаимное исключение. Свободный mutex захватывается
+сразу, а при занятом mutex вызывающая корутина приостанавливается, освобождая поток для другой работы.
+Это главное отличие от `synchronized` и `ReentrantLock.lock()`, которые блокируют поток ожидания.
+
+Предпочтительный API — `withLock`:
+
+```kotlin
+private val mutex = Mutex()
+
+suspend fun changeState() {
+    mutex.withLock {
+        // Критическая секция.
+    }
+}
+```
+
+Ручная пара `lock()`/`unlock()` нужна редко: легко забыть `unlock()` на ветке ошибки. `withLock`
+гарантирует освобождение через `finally`. Ожидание `lock` cancellable, но после успешного входа
+защищённый код подчиняется обычным правилам cancellation.
+
+На JVM успешный `unlock` happens-before последующего успешного `lock` того же mutex. Это обеспечивает
+видимость записей между критическими секциями. Неуспешный `tryLock` такого memory effect не даёт.
+
+В отличие от `synchronized`, `Mutex` не реентерабельный. Правильная композиция — один раз взять mutex,
+а внутреннюю работу вынести в функцию, которая предполагает уже захваченный lock:
+
+```kotlin
+class Inventory {
+    private val mutex = Mutex()
+    private val quantities = mutableMapOf<String, Int>()
+
+    suspend fun add(
+        sku: String,
+        amount: Int,
+    ) {
+        require(amount > 0)
+        mutex.withLock {
+            addLocked(sku, amount)
+        }
+    }
+
+    suspend fun addAndGetTotal(
+        sku: String,
+        amount: Int,
+    ): Int {
+        require(amount > 0)
+        return mutex.withLock {
+            addLocked(sku, amount) // не пытается взять mutex повторно
+            quantities.values.sum()
+        }
+    }
+
+    // Вызывать только из mutex.withLock.
+    private fun addLocked(
+        sku: String,
+        amount: Int,
+    ) {
+        quantities[sku] =
+            quantities.getOrDefault(sku, 0) + amount
+    }
+}
+```
+
+### Пример 1. Ровно одно обновление токена
+
+Иногда suspend-вызов под mutex — осознанная часть инварианта. Пока один запрос обновляет токен,
+остальные должны дождаться того же результата, а не запустить параллельный refresh:
+
+```kotlin
+class TokenRepository(
+    private val api: AuthApi,
+    private val clock: Clock,
+) {
+    private val mutex = Mutex()
+    private var token: Token? = null
+
+    suspend fun validToken(): Token =
+        mutex.withLock {
+            token
+                ?.takeIf { it.expiresAt > clock.now() }
+                ?: api.refreshToken().also { refreshed ->
+                    token = refreshed
+                }
+        }
+}
+```
+
+Здесь network-вызов намеренно удерживает mutex: это гарантирует один refresh. Цена — все чтения токена
+сериализованы. Для независимых ключей или сложного lifecycle лучше keyed mutex/single-flight, чтобы
+одна медленная операция не останавливала несвязанные запросы.
+
+### Пример 2. Чужой код вызывается после критической секции
+
+Callback, listener или пользовательскую suspend-функцию не следует вызывать под mutex без строгой
+необходимости: неизвестный код может долго выполняться или попытаться войти в тот же объект.
+Под lock создают согласованный snapshot, а уведомляют снаружи:
+
+```kotlin
+class SettingsStore {
+    private val mutex = Mutex()
+    private val values = mutableMapOf<String, String>()
+
+    suspend fun update(
+        key: String,
+        value: String,
+        onChanged: suspend (Map<String, String>) -> Unit,
+    ) {
+        val snapshot = mutex.withLock {
+            values[key] = value
+            values.toMap()
+        }
+
+        // Mutex уже освобождён: callback не удерживает критическую секцию.
+        onChanged(snapshot)
+    }
+}
+```
+
+Такой код защищает mutable map, минимизирует время удержания mutex и не допускает утечки изменяемой
+коллекции наружу. При этом порядок завершения callbacks уже не сериализован — если он важен как часть
+контракта, нужна отдельная модель доставки событий (`Channel`, actor/confinement или явно
+спроектированная очередь).
+
+`Mutex` выбирают для составного mutable-инварианта в coroutine-коде. Для одной переменной часто лучше
+atomic/CAS, для ограничения параллелизма — `Semaphore`, для последовательного владельца состояния —
+confinement/actor, а для короткого несуспендящего Java-кода — `synchronized`.
+
 ---
 
 # 13. Android-специфика