kotlinx-coroutines-core / kotlinx.coroutines.experimental / CancellableContinuation

CancellableContinuation

interface CancellableContinuation<in T> : 
    Continuation<T>, 
    Job

(source)

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

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 resume or resumeWithException transitions it from active to resumed state.

A cancelled continuation implies that it is completed.

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

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

Properties

isActive	`abstract val isActive: Boolean` Returns `true` when this continuation is active – it has not completed or cancelled yet.
isCancelled	`abstract val isCancelled: Boolean` Returns `true` if this continuation was cancelled.
isCompleted	`abstract val isCompleted: Boolean` Returns `true` when this continuation has completed for any reason. A continuation that was cancelled is also considered complete.

Inherited Properties

children	`abstract val children: Sequence<Job>` Returns a sequence of this job’s children.
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

cancel	`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.
completeResume	`abstract fun completeResume(token: Any): Unit`
initCancellability	`abstract fun initCancellability(): Unit` Makes this continuation cancellable. Use it with `holdCancellability` optional parameter to suspendCancellableCoroutine function. It throws IllegalStateException if invoked more than once.
invokeOnCompletion	`abstract fun invokeOnCompletion( handler: CompletionHandler ): DisposableHandle` Registers handler that is synchronously invoked once on completion of this continuation. When continuation is already complete, then the handler is immediately invoked with continuation’s exception or `null`. Otherwise, handler will be invoked once when this continuation is complete.
resumeUndispatched	`abstract fun CoroutineDispatcher.resumeUndispatched( value: T ): Unit` Resumes this continuation with a given value in the invoker thread without going though dispatch function of the CoroutineDispatcher in the context. This function is designed to be used only by the CoroutineDispatcher implementations themselves. It should not be used in general code.
resumeUndispatchedWithException	`abstract fun CoroutineDispatcher.resumeUndispatchedWithException( exception: Throwable ): Unit` Resumes this continuation with a given exception in the invoker thread without going though dispatch function of the CoroutineDispatcher in the context. This function is designed to be used only by the CoroutineDispatcher implementations themselves. It should not be used in general code.
tryResume	`abstract fun tryResume( value: T, idempotent: Any? = null ): Any?`

Inherited Functions

attachChild	`abstract fun attachChild(child: Job): DisposableHandle`
getCancellationException	`abstract fun getCancellationException(): CancellationException` Returns CancellationException that signals the completion of this job. This function is used by cancellable suspending functions. They throw exception returned by this function when they suspend in the context of this job and this job becomes complete.
invokeOnCompletion	`abstract fun invokeOnCompletion( onCancelling: Boolean = false, invokeImmediately: Boolean = true, handler: CompletionHandler ): DisposableHandle` Registers handler that is synchronously invoked once on cancellation or completion of this job. When job is already cancelling or complete, then the handler is immediately invoked with a job’s cancellation cause or `null` unless invokeImmediately is set to false. Otherwise, handler will be invoked once when this job is cancelled or 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 Functions

cancel	`fun CoroutineContext.cancel( cause: Throwable? = null ): Boolean` Cancels Job of this context with an optional cancellation cause. The result is `true` if the job was cancelled as a result of this invocation and `false` if there is no job in the context or if it was already cancelled or completed. See Job.cancel for details.
cancelAndJoin	`suspend fun Job.cancelAndJoin(): Unit` Cancels the job and suspends invoking coroutine until the cancelled job is complete.
cancelFutureOnCompletion	`fun Job.cancelFutureOnCompletion( future: Future<*> ): DisposableHandle` Cancels a specified future when this job is complete.
disposeOnCompletion	`fun Job.disposeOnCompletion( handle: DisposableHandle ): DisposableHandle` Disposes a specified handle when this job is complete.
joinChildren	`suspend fun Job.joinChildren(): Unit` Suspends coroutine until all children of this job are complete using Job.join for all of them. Unlike Job.join on this job as a whole, it does not wait until this job is complete.