kotlinx.coroutines.experimental

Class Deferred.DefaultImpls

kotlinx.coroutines.experimental.Deferred.DefaultImpls

Enclosing interface:

Deferred<T>

public static class Deferred.DefaultImpls

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

Method Summary

Modifier and Type	Method and Description
static <T,R> R	fold(Deferred<? extends T> $this, R initial, kotlin.jvm.functions.Function2<? super R,? super kotlin.coroutines.experimental.CoroutineContext.Element,? extends R> operation)
static <T,E extends Element> E	get(Deferred<? extends T> $this, kotlin.coroutines.experimental.CoroutineContext.Key<E> key)
static <T> java.lang.Throwable	getCompletionException(Deferred<? extends T> $this) Deprecated.
static <T> kotlin.coroutines.experimental.CoroutineContext	minusKey(Deferred<? extends T> $this, kotlin.coroutines.experimental.CoroutineContext.Key<?> key)
static <T> Job	plus(Deferred<? extends T> $this, Job other) Deprecated.
static <T> kotlin.coroutines.experimental.CoroutineContext	plus(Deferred<? extends T> $this, kotlin.coroutines.experimental.CoroutineContext context)

Method Detail

getCompletionException

public static <T> java.lang.Throwable getCompletionException(Deferred<? extends T> $this)

Deprecated.

plus

public static <T> Job plus(Deferred<? extends T> $this,
                           Job other)

Deprecated.

plus

public static <T> kotlin.coroutines.experimental.CoroutineContext plus(Deferred<? extends T> $this,
                                                                       kotlin.coroutines.experimental.CoroutineContext context)

fold

public static <T,R> R fold(Deferred<? extends T> $this,
                           R initial,
                           kotlin.jvm.functions.Function2<? super R,? super kotlin.coroutines.experimental.CoroutineContext.Element,? extends R> operation)

get

public static <T,E extends Element> E get(Deferred<? extends T> $this,
                                          kotlin.coroutines.experimental.CoroutineContext.Key<E> key)

minusKey

public static <T> kotlin.coroutines.experimental.CoroutineContext minusKey(Deferred<? extends T> $this,
                                                                           kotlin.coroutines.experimental.CoroutineContext.Key<?> key)