kotlinx-coroutines-core/kotlinx.coroutines/awaitCancellation

awaitCancellation

suspend fun awaitCancellation(): Nothing(source)

Suspends until cancellation, in which case it will throw a CancellationException.

This function returns Nothing, so it can be used in any coroutine, regardless of the required return type.

Usage example in callback adapting code:

fun currentTemperature(): Flow<Temperature> = callbackFlow {
    val callback = SensorCallback { degreesCelsius: Double ->
        trySend(Temperature.celsius(degreesCelsius))
    }
    try {
        registerSensorCallback(callback)
        awaitCancellation() // Suspends to keep getting updates until cancellation.
    } finally {
        unregisterSensorCallback(callback)
    }
}

Usage example in (non declarative) UI code:

suspend fun showStuffUntilCancelled(content: Stuff): Nothing {
    someSubView.text = content.title
    anotherSubView.text = content.description
    someView.visibleInScope {
        awaitCancellation() // Suspends so the view stays visible.
    }
}