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 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 Job.attachChild 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 Job.attachChild 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.start, interface CompletableDeferred, Job.attachChild, interface Job, Job.attachChild

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)