interface Deferred<out T> : Job (source)

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

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

Deferred has the same state machine as the Job with additional convenience methods to retrieve the 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 an exception if the deferred had failed. Note that a cancelled deferred is also considered as 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, the 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.



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


abstract val children: Sequence<Job>

Returns a sequence of this job’s children.


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.


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.


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.


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.



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.


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.


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


abstract fun cancel(
    cause: CancellationException? = null
): Unit

Cancels this job with an optional cancellation cause. A cause can be used to specify an error message or to provide other details on the cancellation reason for debugging purposes. See Job documentation for full explanation of cancellation machinery.


abstract fun invokeOnCompletion(
    handler: CompletionHandler
): DisposableHandle

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


abstract suspend fun join(): Unit

Suspends the 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.


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


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

Extension Functions


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

Converts this deferred value to the instance of Promise.


fun CoroutineContext.cancel(
    cause: CancellationException? = null
): Unit

Cancels Job of this context with an optional cancellation cause. See Job.cancel for details.


fun Job.cancel(
    message: String,
    cause: Throwable? = null
): Unit

Cancels current job, including all its children with a specified diagnostic error message. A cause can be specified to provide additional details on a cancellation reason for debugging purposes.


suspend fun Job.cancelAndJoin(): Unit

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



interface CompletableDeferred<T> : Deferred<T>

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