Deferred
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 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
Returns completed result or throws IllegalStateException if this deferred value has not completed yet. It throws the corresponding exception if this deferred was cancelled.
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.