kotlinx.coroutines.experimental

Interface Deferred<T>

All Superinterfaces:

Job

All Known Subinterfaces:

CompletableDeferred<T>

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 Job.isActive state while the value is being computed.

Deferred value has the following states:

| State | Job.isActive | Job.isCompleted | Deferred.isCompletedExceptionally | Job.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, Job.join, or Deferred.await.

A deferred can be cancelled at any time with Job.cancel function that forces it to transition to cancelling state immediately. Deferred that is not backed by a coroutine (see interface CompletableDeferred) and does not have Job.getChildren becomes cancelled on Job.cancel immediately. Otherwise, deferred becomes cancelled when it finishes executing its code and when all its children Job.isCompleted.

                                                       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 CoroutineScope.getCoroutineContext 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 Job.getChildren 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.

See Also:

interface CompletableDeferred, Job.isActive, Job.isActive, Job.isCompleted, Deferred.isCompletedExceptionally, Job.isCancelled, Job.start, Job.join, Deferred.await, Job.cancel, interface CompletableDeferred, Job.getChildren, Job.cancel, Job.isCompleted, interface Job, CoroutineScope.getCoroutineContext, Job.getChildren

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Deferred.DefaultImpls Deferred value is a non-blocking cancellable future.

Nested classes/interfaces inherited from interface kotlinx.coroutines.experimental.Job

Job.Key

Field Summary

Fields inherited from interface kotlinx.coroutines.experimental.Job

Key

Method Summary

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 had completed exceptionally.
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 has Deferred.isCompletedExceptionally.
java.lang.Throwable	getCompletionExceptionOrNull() Returns completion exception result if this deferred Deferred.isCompletedExceptionally, null if it is 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).
boolean	isCompletedExceptionally() Returns true if computation of this deferred value has completed exceptionally -- it had either failed with exception during computation or was Job.cancel.

Methods inherited from interface kotlinx.coroutines.experimental.Job

cancel, getCancellationException, getChildren, getOnJoin, invokeOnCompletion, invokeOnCompletion, isActive, isCancelled, isCompleted, join, start

Method Detail

isCompletedExceptionally

boolean isCompletedExceptionally()

Returns true if computation of this deferred value has completed exceptionally -- it had either failed with exception during computation or was Job.cancel.

It implies that Job.isActive is false and Job.isCompleted is true.

See Also:

Job.cancel, Job.isActive, Job.isCompleted

await

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 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 Deferred.getOnAwait clause. Use Job.isCompleted to check for completion of this deferred value without waiting.

See Also:

interface Job, Deferred.getOnAwait, Job.isCompleted

getOnAwait

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).

See Also:

Deferred.await

getCompleted

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 has Deferred.isCompletedExceptionally.

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.

See Also:

IllegalStateException, Job.isCompleted, Deferred.isCompletedExceptionally, Deferred.getCompletionExceptionOrNull

getCompletionExceptionOrNull

java.lang.Throwable getCompletionExceptionOrNull()

Returns completion exception result if this deferred Deferred.isCompletedExceptionally, null if it is completed normally, or throws IllegalStateException if this deferred value has not Job.isCompleted 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.

See Also:

Deferred.isCompletedExceptionally, IllegalStateException, Job.isCompleted, Deferred.getCompleted