public Deferred<T> extends Job
Deferred value is a non-blocking cancellable future — it is a interface Job that has a result.
It is created with BuildersKt.async coroutine builder or via constructor of interface CompletableDeferred class.
It is in Job.isActive state while the value is being computed.
Deferred value has the same state machine as the interface Job with additional convenience methods to retrieve
successful or failed result of the computation that was carried out. The result of the deferred is
available when it is Job.isCompleted and can be retrieved by Deferred.await method, which throws
exception if the deferred had failed.
Note, that a cancelled deferred is also considered to be completed.
The corresponding exception can be retrieved via Deferred.getCompletionExceptionOrNull from a completed instance of deferred.
Usually, a deferred value is created in active state (it is created and started).
However, BuildersKt.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 Job.start, Job.join, or Deferred.await.
A deferred value is a interface Job. A job in the
coroutineContext
of BuildersKt.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.
Job.DefaultImpls, Job.Key| Modifier and Type | Method and Description |
|---|---|
java.lang.Object |
await(kotlin.coroutines.experimental.Continuation<? super T> p)
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.
|
T |
getCompleted()
Returns completed result or throws IllegalStateException if this deferred value has not
Job.isCompleted yet. It throws the corresponding exception if this deferred was Job.isCancelled. |
java.lang.Throwable |
getCompletionExceptionOrNull()
Returns completion exception result if this deferred was
Job.isCancelled and has Job.isCompleted,
null if it had completed normally, or throws IllegalStateException if this deferred value has not
Job.isCompleted yet. |
SelectClause1<T> |
getOnAwait()
Clause for select expression of
Deferred.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). |
cancel, getChildren, getOnJoin, invokeOnCompletion, isActive, isCancelled, isCompleted, join, startjava.lang.Object await(kotlin.coroutines.experimental.Continuation<? super T> p)
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.
This suspending function is cancellable.
If the interface Job of the current coroutine is cancelled or completed while this suspending function is waiting, this function
immediately resumes with CancellationException.
This function can be used in select invocation with Deferred.getOnAwait clause.
Use Job.isCompleted to check for completion of this deferred value without waiting.
interface Job,
Deferred.getOnAwait,
Job.isCompletedSelectClause1<T> getOnAwait()
Clause for select expression of Deferred.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).
Deferred.awaitT getCompleted()
Returns completed result or throws IllegalStateException if this deferred value has not
Job.isCompleted yet. It throws the corresponding exception if this deferred was Job.isCancelled.
This function is designed to be used from Job.invokeOnCompletion handlers, when there is an absolute certainty that
the value is already complete. See also Deferred.getCompletionExceptionOrNull.
Note: This is an experimental api. This function may be removed or renamed in the future.
java.lang.Throwable getCompletionExceptionOrNull()
Returns completion exception result if this deferred was Job.isCancelled and has Job.isCompleted,
null if it had completed normally, or throws IllegalStateException if this deferred value has not
Job.isCompleted yet.
This function is designed to be used from Job.invokeOnCompletion handlers, when there is an absolute certainty that
the value is already complete. See also Deferred.getCompleted.
Note: This is an experimental api. This function may be removed or renamed in the future.