Deferred

interface Deferred<out T> : Job

Deferred value is a non-blocking cancellable future &mdash; it is a Job with a result.

It is created with the async coroutine builder or via the constructor of CompletableDeferred class. It is in active state while the value is being computed.

Deferred has the same state machine as the Job with additional convenience methods to retrieve the successful or failed result of the computation that was carried out. The result of the deferred is available when it is completed and can be retrieved by await method, which throws an exception if the deferred had failed. Note that a cancelled deferred is also considered as completed. The corresponding exception can be retrieved via getCompletionExceptionOrNull from a completed instance of deferred.

Usually, a deferred value is created in active state (it is created and started). However, the async coroutine builder has an optional start parameter that creates a deferred value in new state when this parameter is set to CoroutineStart.LAZY. Such a deferred can be be made active by invoking start, join, or await.

A deferred value is a Job. A job in the coroutineContext of async builder represents the coroutine itself.

All functions on this interface and on all interfaces derived from it are thread-safe and can be safely invoked from concurrent coroutines without external synchronization.

Deferred interface and all its derived interfaces are not stable for inheritance in 3rd party libraries, as new methods might be added to this interface in the future, but is stable for use.

Functions

await
Link copied to clipboard
common
abstract suspend fun await(): T
Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete, returning the resulting value or throwing the corresponding exception if the deferred was cancelled.
getCompleted
Link copied to clipboard
common
abstract fun getCompleted(): T
Returns completed result or throws IllegalStateException if this deferred value has not completed yet.
getCompletionExceptionOrNull
Link copied to clipboard
common
abstract fun getCompletionExceptionOrNull(): Throwable?
Returns completion exception result if this deferred was cancelled and has completed, null if it had completed normally, or throws IllegalStateException if this deferred value has not completed yet.

Properties

onAwait
Link copied to clipboard
common
abstract val onAwait: SelectClause1<T>
Clause for select expression of await suspending function that selects with the deferred value when it is resolved.

Inheritors

CompletableDeferred
Link copied to clipboard

Extensions

asPromise
Link copied to clipboard
js
fun <T> Deferred<T>.asPromise(): Promise<T>
Converts this deferred value to the instance of Promise.

Sources

common source
Link copied to clipboard