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.
Properties
Inheritors
Extensions
Cancels current job, including all its children with a specified diagnostic error message. A cause can be specified to provide additional details on a cancellation reason for debugging purposes.
Cancels Job of this context with an optional cancellation cause. See Job.cancel for details.
Cancels the job and suspends the invoking coroutine until the cancelled job is complete.
Cancels all children jobs of this coroutine using Job.cancel for all of them with an optional cancellation cause. Unlike Job.cancel on this job as a whole, the state of this job itself is not affected.
Cancels all children of the Job in this context, without touching the state of this job itself with an optional cancellation cause. See Job.cancel. It does not do anything if there is no job in the context or it has no children.
Ensures that current job is active. If the job is no longer active, throws CancellationException. If the job was cancelled, thrown exception contains the original cancellation cause.
Ensures that job in the current context is active.
Returns true when the Job of the coroutine in this context is still active (has not completed and was not cancelled yet).
Retrieves the current Job instance from the given CoroutineContext or throws IllegalStateException if no job is present in the context.