await

abstract suspend fun await(): T(source)

Awaits for completion of this value without blocking the thread and returns the resulting value or throws the exception if the deferred was cancelled.

Unless the calling coroutine is cancelled, await will return the same result on each invocation: if the Deferred completed successfully, await will return the same value every time; if the Deferred completed exceptionally, await will rethrow the same exception.

This suspending function is itself cancellable: if the Job of the current coroutine is cancelled or completed while this suspending function is waiting, this function immediately resumes with CancellationException.

This means that await can throw CancellationException in two cases:

In both cases, the CancellationException will cancel the coroutine calling await, unless it's caught. The following idiom may be helpful to avoid this:

try {
deferred.await()
} catch (e: CancellationException) {
currentCoroutineContext().ensureActive() // throws if the current coroutine was cancelled
processException(e) // if this line executes, the exception is the result of `await` itself
}

There is a prompt cancellation guarantee: even if this function is ready to return the result, but was cancelled while suspended, CancellationException will be thrown. See suspendCancellableCoroutine for low-level details.

This function can be used in select invocations with an onAwait clause. Use isCompleted to check for completion of this deferred value without waiting, and join to wait for completion without returning the result.