public Deferred<T> extends Job
Deferred value is a non-blocking cancellable future.
It is created with async coroutine builder or via constructor of interface CompletableDeferred class.
It is in active state while the value is being computed.
Deferred value has the following states:
| State | isActive | isCompleted | isCompletedExceptionally | isCancelled |
| --------------------------------------- | ---------- | ------------- | -------------------------- | ------------- |
| New (optional initial state) | false | false | false | false |
| Active (default initial state) | true | false | false | false |
| Completing (optional transient state) | true | false | false | false |
| Cancelling (optional transient state) | false | false | false | true |
| Cancelled (final state) | false | true | true | true |
| Resolved (final state) | false | true | false | false |
| Failed (final state) | false | true | true | false |
Usually, a deferred value is created in active state (it is created and started).
However, 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, join, or await.
A deferred can be cancelled at any time with cancel function that forces it to transition to
cancelling state immediately. A simple implementation of deferred -- interface CompletableDeferred,
that is not backed by a coroutine, does not have a cancelling state, but becomes cancelled
on cancel immediately. Coroutines, on the other hand, become cancelled only when they finish
executing their code and after all their children complete.
wait children
+-----+ start +--------+ complete +-------------+ finish +-----------+
| New | ---------------> | Active | ----------> | Completing | ---+-> | Resolved |
+-----+ +--------+ +-------------+ | |(completed)|
| | | | +-----------+
| cancel | cancel | cancel |
V V | | +-----------+
+-----------+ finish +------------+ | +-> | Failed |
| Cancelled | <--------- | Cancelling | <---------------+ |(completed)|
|(completed)| +------------+ +-----------+
+-----------+
A deferred value is a interface Job. A job in the coroutine context of async builder
represents the coroutine itself.
A deferred value is active while the coroutine is working and cancellation aborts the coroutine when
the coroutine is suspended on a cancellable suspension point by throwing CancellationException
or the cancellation cause inside the coroutine.
A deferred value can have a parent job. A deferred value with a parent is cancelled when its parent is cancelled or completes. Parent waits for all its children to complete in completing or cancelling state. Completing state is purely internal. For an outside observer a completing deferred is still active, while internally it is waiting for its children.
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.
| Modifier and Type | Interface and Description |
|---|---|
static class |
Deferred.DefaultImpls
Deferred value is a non-blocking cancellable future.
|
| Modifier and Type | Method and Description |
|---|---|
java.lang.Object |
await(kotlin.coroutines.experimental.Continuation<? super T> $continuation)
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 had completed exceptionally.
|
T |
getCompleted()
Returns completed result or throws IllegalStateException if this deferred value has not
completed yet. It throws the corresponding exception if this deferred has
completed exceptionally.
|
java.lang.Throwable |
getCompletionExceptionOrNull()
Returns completion exception result if this deferred completed exceptionally,
null if it is completed normally, or throws IllegalStateException if this deferred value has not
completed yet. |
SelectClause1<T> |
getOnAwait()
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).
|
boolean |
isCompletedExceptionally()
Returns
true if computation of this deferred value has completed exceptionally -- it had
either failed with exception during computation or was cancelled. |
cancel, getCancellationException, getChildren, getOnJoin, invokeOnCompletion, isActive, isCancelled, isCompleted, join, startboolean isCompletedExceptionally()
Returns true if computation of this deferred value has completed exceptionally -- it had
either failed with exception during computation or was cancelled.
It implies that isActive is false and isCompleted is true.
java.lang.Object await(kotlin.coroutines.experimental.Continuation<? super T> $continuation)
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 had completed exceptionally.
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 onAwait clause. Use isCompleted to check for completion of this deferred value without waiting.
interface JobSelectClause1<T> getOnAwait()
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).
T getCompleted()
Returns completed result or throws IllegalStateException if this deferred value has not completed yet. It throws the corresponding exception if this deferred has completed exceptionally.
This function is designed to be used from invokeOnCompletion handlers, when there is an absolute certainty that
the value is already complete. See also Deferred.getCompletionExceptionOrNull.
java.lang.Throwable getCompletionExceptionOrNull()
Returns completion exception result if this deferred completed exceptionally,
null if it is completed normally, or throws IllegalStateException if this deferred value has not
completed yet.
This function is designed to be used from invokeOnCompletion handlers, when there is an absolute certainty that
the value is already complete. See also Deferred.getCompleted.
Deferred.getCompleted