kotlinx-coroutines-core/kotlinx.coroutines/CompletableDeferred

CompletableDeferred

interface CompletableDeferred<T> : Deferred<T> (source)

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

Note that the complete function returns false when this deferred value is already complete or completing, while cancel returns true as long as the deferred is still cancelling and the corresponding exception is incorporated into the final completion exception.

An instance of completable deferred can be created by CompletableDeferred() function in active state.

All functions on this interface are thread-safe and can be safely invoked from concurrent coroutines without external synchronization.

The CompletableDeferred interface is not stable for inheritance in 3rd party libraries, as new methods might be added to this interface in the future, but is stable for use.

Functions

complete

abstract fun complete(value: T): Boolean

Completes this deferred value with a given value. The result is true if this deferred was completed as a result of this invocation and false otherwise (if it was already completed).

completeExceptionally

abstract fun completeExceptionally(exception: Throwable): Boolean

Completes this deferred value exceptionally with a given exception. The result is true if this deferred was completed as a result of this invocation and false otherwise (if it was already completed).

Extensions

asPromise

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

Converts this deferred value to the instance of Promise.

cancel

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

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.

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

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

cancelAndJoin

suspend fun Job.cancelAndJoin()

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

cancelChildren

fun Job.cancelChildren(cause: CancellationException? = null)

Cancels all children jobs of this coroutine using Job.cancel for all of them with an optional cancellation cause. Unlike Job.cancel on this job as a whole, the state of this job itself is not affected.

fun CoroutineContext.cancelChildren(cause: CancellationException? = null)

Cancels all children of the Job in this context, without touching the state of this job itself with an optional cancellation cause. See Job.cancel. It does not do anything if there is no job in the context or it has no children.

completeWith

fun <T> CompletableDeferred<T>.completeWith(result: Result<T>): Boolean

Completes this deferred value with the value or exception in the given result. Returns true if this deferred was completed as a result of this invocation and false otherwise (if it was already completed).

ensureActive

fun Job.ensureActive()

Ensures that current job is active. If the job is no longer active, throws CancellationException. If the job was cancelled, thrown exception contains the original cancellation cause.

fun CoroutineContext.ensureActive()

Ensures that job in the current context is active.

isActive

val CoroutineContext.isActive: Boolean

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

job

val CoroutineContext.job: Job

Retrieves the current Job instance from the given CoroutineContext or throws IllegalStateException if no job is present in the context.