CancellableContinuation

interface CancellableContinuation<in T> : Continuation<T>

Cancellable continuation. It is completed when resumed or cancelled. When the cancel function is explicitly invoked, this continuation immediately resumes with a CancellationException or the specified cancel cause.

An instance of CancellableContinuation is created by the suspendCancellableCoroutine function.

Cancellable continuation has three states (as subset of Job states):

StateisActiveisCompletedisCancelled
Active (initial state)truefalsefalse
Resumed (final completed state)falsetruefalse
Canceled (final completed state)falsetruetrue

Invocation of cancel transitions this continuation from active to cancelled state, while invocation of Continuation.resume or Continuation.resumeWithException transitions it from active to resumed state.

A cancelled continuation implies that it is completed.

Invocation of Continuation.resume or Continuation.resumeWithException in resumed state produces an IllegalStateException, but is ignored in cancelled state.

    +-----------+   resume    +---------+
| Active | ----------> | Resumed |
+-----------+ +---------+
|
| cancel
V
+-----------+
| Cancelled |
+-----------+

Functions

cancel
Link copied to clipboard
abstract fun cancel(cause: Throwable? = null): Boolean

Cancels this continuation with an optional cancellation cause. The result is true if this continuation was cancelled as a result of this invocation, and false otherwise.

invokeOnCancellation
Link copied to clipboard
abstract fun invokeOnCancellation(handler: CompletionHandler)

Registers a handler to be synchronously invoked on cancellation (regular or exceptional) of this continuation. When the continuation is already cancelled, the handler is immediately invoked with the cancellation exception. Otherwise, the handler will be invoked as soon as this continuation is cancelled.

resume
Link copied to clipboard
abstract fun resume(value: T, onCancellation: (cause: Throwable) -> Unit?)

Resumes this continuation with the specified value and calls the specified onCancellation handler when either resumed too late (when continuation was already cancelled) or, although resumed successfully (before cancellation), the coroutine's job was cancelled before it had a chance to run in its dispatcher, so that the suspended function threw an exception instead of returning this value.

resumeUndispatched
Link copied to clipboard
abstract fun CoroutineDispatcher.resumeUndispatched(value: T)

Resumes this continuation with the specified value in the invoker thread without going through the dispatch function of the CoroutineDispatcher in the context. This function is designed to only be used by CoroutineDispatcher implementations. It should not be used in general code.

resumeUndispatchedWithException
Link copied to clipboard

Resumes this continuation with the specified exception in the invoker thread without going through the dispatch function of the CoroutineDispatcher in the context. This function is designed to only be used by CoroutineDispatcher implementations. It should not be used in general code.

Properties

isActive
Link copied to clipboard
abstract val isActive: Boolean

Returns true when this continuation is active -- it has not completed or cancelled yet.

isCancelled
Link copied to clipboard
abstract val isCancelled: Boolean

Returns true if this continuation was cancelled.

isCompleted
Link copied to clipboard
abstract val isCompleted: Boolean

Returns true when this continuation has completed for any reason. A cancelled continuation is also considered complete.

Extensions

cancelFutureOnCancellation
Link copied to clipboard
fun CancellableContinuation<*>.cancelFutureOnCancellation(future: Future<*>)

Cancels a specified future when this job is cancelled. This is a shortcut for the following code with slightly more efficient implementation (one fewer object created).

Sources

common source
Link copied to clipboard