interface Deferred<out T> : Job(source)

Deferred value is a non-blocking cancellable future — 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 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.



Link copied to clipboard
abstract val onAwait: SelectClause1<T>

Clause for select expression of await suspending function that selects with the deferred value when it is resolved. The select invocation fails if the deferred value completes exceptionally (either fails or it cancelled).


Link copied to clipboard

Converts this deferred value to the instance of Promise.

Link copied to clipboard
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.

Link copied to clipboard

Returns completed result or throws IllegalStateException if this deferred value has not completed yet. It throws the corresponding exception if this deferred was cancelled.

Link copied to clipboard

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.