MutatorMutex

Mutual exclusion for UI state mutation over time.

mutate permits interruptible state mutation over time using a standard MutatePriority. A MutatorMutex enforces that only a single writer can be active at a time for a particular state resource. Instead of queueing callers that would acquire the lock like a traditional Mutex, new attempts to mutate the guarded state will either cancel the current mutator or if the current mutator has a higher priority, the new caller will throw CancellationException.

MutatorMutex should be used for implementing hoisted state objects that many mutators may want to manipulate over time such that those mutators can coordinate with one another. The MutatorMutex instance should be hidden as an implementation detail. For example:

import androidx.compose.foundation.MutatorMutex
import androidx.compose.foundation.layout.Row
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.Stable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.rememberCoroutineScope

@Stable
class ScrollState(position: Int = 0) {
    private var _position by mutableStateOf(position)
    var position: Int
        get() = _position.coerceAtMost(range)
        set(value) {
            _position = value.coerceIn(0, range)
        }

    private var _range by mutableStateOf(0)
    var range: Int
        get() = _range
        set(value) {
            _range = value.coerceAtLeast(0)
        }

    var isScrolling by mutableStateOf(false)
        private set

    private val mutatorMutex = MutatorMutex()

    /** Only one caller to [scroll] can be in progress at a time. */
    suspend fun <R> scroll(block: suspend () -> R): R =
        mutatorMutex.mutate {
            isScrolling = true
            try {
                block()
            } finally {
                // MutatorMutex.mutate ensures mutual exclusion between blocks.
                // By setting back to false in the finally block inside mutate, we ensure that
                // we
                // reset the state upon cancellation before the next block starts to run (if
                // any).
                isScrolling = false
            }
        }
}

/** Arbitrary animations can be defined as extensions using only public API */
suspend fun ScrollState.animateTo(target: Int) {
    scroll { animate(from = position, to = target) { newPosition -> position = newPosition } }
}

/**
 * Presents two buttons for animating a scroll to the beginning or end of content. Pressing one
 * will cancel any current animation in progress.
 */
@Composable
fun ScrollControls(scrollState: ScrollState) {
    Row {
        val scope = rememberCoroutineScope()
        Button(onClick = { scope.launch { scrollState.animateTo(0) } }) {
            Text("Scroll to beginning")
        }
        Button(onClick = { scope.launch { scrollState.animateTo(scrollState.range) } }) {
            Text("Scroll to end")
        }
    }
}

Summary

MutatorMutex()

suspend fun <R : Any?> mutate(
    priority: MutatePriority = MutatePriority.Default,
    block: suspend () -> R
): R

suspend fun <T : Any?, R : Any?> mutateWith(
    receiver: T,
    priority: MutatePriority = MutatePriority.Default,
    block: suspend T.() -> R
): R

import androidx.compose.foundation.MutatorMutex
import androidx.compose.runtime.MutableState
import androidx.compose.runtime.Stable
import androidx.compose.runtime.mutableStateOf

@Stable
class ScrollState(position: Int = 0) {
    private var _position = mutableStateOf(position)
    val position: Int by _position

    private val mutatorMutex = MutatorMutex()

    /** Only [block] in a call to [scroll] may change the value of [position]. */
    suspend fun <R> scroll(block: suspend MutableState<Int>.() -> R): R =
        mutatorMutex.mutateWith(_position, block = block)
}

inline fun tryMutate(block: () -> Unit): Boolean