Deferred

interface Deferred<out T> : Job (source)

Deferred value is a non-blocking cancellable future — it is a Job that has a result.

It is created with async coroutine builder or via constructor of CompletableDeferred class. It is in active state while the value is being computed.

Deferred value has the same state machine as the 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 completed and can be retrieved by 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 getCompletionExceptionOrNull from a completed instance of deferred.

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 start, join, or await.

A deferred value is a Job. A job in the coroutineContext of 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.

Properties

onAwait

abstract val onAwait: SelectClause1<T>

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

Inherited Properties

children

abstract val children: Sequence<Job>

Returns a sequence of this job’s children.

isActive

abstract val isActive: Boolean

Returns true when this job is active – it was already started and has not completed nor was cancelled yet. The job that is waiting for its children to complete is still considered to be active if it was not cancelled nor failed.

isCancelled

abstract val isCancelled: Boolean

Returns true if this job was cancelled for any reason, either by explicit invocation of cancel or because it had failed or its child or parent was cancelled. In the general case, it does not imply that the job has already completed, because it may still be finishing whatever it was doing and waiting for its children to complete.

isCompleted

abstract val isCompleted: Boolean

Returns true when this job has completed for any reason. A job that was cancelled or failed and has finished its execution is also considered complete. Job becomes complete only after all its children complete.

onJoin

abstract val onJoin: SelectClause0

Clause for select expression of join suspending function that selects when the job is complete. This clause never fails, even if the job completes exceptionally.

Functions

await

abstract suspend fun await(): T

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.

getCompleted

abstract fun getCompleted(): T

Returns completed result or throws IllegalStateException if this deferred value has not completed yet. It throws the corresponding exception if this deferred was cancelled.

getCompletionExceptionOrNull

abstract fun getCompletionExceptionOrNull(): Throwable?

Returns completion exception result if this deferred was cancelled and has completed, null if it had completed normally, or throws IllegalStateException if this deferred value has not completed yet.

Inherited Functions

cancel

abstract fun cancel(): Unit

Cancels this job. See Job documentation for full explanation of cancellation machinery.

invokeOnCompletion

abstract fun invokeOnCompletion(
    handler: CompletionHandler
): DisposableHandle

Registers handler that is synchronously invoked once on completion of this job. When job is already complete, then the handler is immediately invoked with a job’s exception or cancellation cause or null. Otherwise, handler will be invoked once when this job is complete.

join

abstract suspend fun join(): Unit

Suspends coroutine until this job is complete. This invocation resumes normally (without exception) when the job is complete for any reason and the Job of the invoking coroutine is still active. This function also starts the corresponding coroutine if the Job was still in new state.

start

abstract fun start(): Boolean

Starts coroutine related to this job (if any) if it was not started yet. The result true if this invocation actually started coroutine or false if it was already started or completed.

Extension Properties

isActive

Returns true when the Job of the coroutine in this context is still active (has not completed and was not cancelled yet).

Extension Functions

asPromise

fun <T> Deferred<T>.asPromise(): Promise<T>

Converts this deferred value to the instance of Promise.

cancel

fun CoroutineContext.cancel(): Unit

Cancels Job of this context. See Job.cancel for details.

cancelAndJoin

suspend fun Job.cancelAndJoin(): Unit

Cancels the job and suspends invoking coroutine until the cancelled job is complete.

Inheritors

CompletableDeferred

interface CompletableDeferred<T> : Deferred<T>

A Deferred that can be completed via public functions complete or cancel.