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 ->
try {
awaitCancellation() // Suspends to keep getting updates until cancellation.
} finally {

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.