CancellableContinuation
interface CancellableContinuation<in T> : Continuation<T>
(source)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):
State | isActive | isCompleted | isCancelled |
---|---|---|---|
Active (initial state) | true |
false |
false |
Resumed (final completed state) | false |
true |
false |
Canceled (final completed state) | false |
true |
true |
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 | +-----------+
Properties
abstract val isActive: Boolean Returns |
|
abstract val isCancelled: Boolean Returns |
|
abstract val isCompleted: Boolean Returns |
Functions
Cancels this continuation with an optional cancellation |
|
abstract fun invokeOnCancellation( 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. |
|
Resumes this continuation with the specified |
|
abstract fun CoroutineDispatcher.resumeUndispatched( 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. |
|
abstract fun CoroutineDispatcher.resumeUndispatchedWithException( 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. |
|
abstract fun tryResume( Same as tryResume but with onCancellation handler that called if and only if the value is not delivered to the caller because of the dispatch in the process, so that atomicity delivery guaranteed can be provided by having a cancellation fallback. |
Extension Functions
fun CancellableContinuation<*>.cancelFutureOnCancellation( 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). |