kotlinx.coroutines.experimental

Interface CancellableContinuation<T>

All Superinterfaces:

Job

public CancellableContinuation<T>
extends Job

Cancellable continuation. Its job is completed when it is resumed or cancelled. When CancellableContinuation.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 interface Job states):

| State | CancellableContinuation.isActive | CancellableContinuation.isCompleted | CancellableContinuation.isCancelled | | ----------------------------------- | ---------- | ------------- | ------------- | | Active (initial state) | true | false | false | | Resumed (final completed state) | false | true | false | | Canceled (final completed state)| false | true | true |

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

A CancellableContinuation.isCancelled continuation implies that it is CancellableContinuation.isCompleted.

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

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

See Also:

CancellableContinuation.cancel, interface Job, CancellableContinuation.isActive, CancellableContinuation.isCompleted, CancellableContinuation.isCancelled, CancellableContinuation.cancel, resume, resumeWithException, CancellableContinuation.isCancelled, CancellableContinuation.isCompleted, resume, resumeWithException, IllegalStateException

Nested Class Summary

Nested classes/interfaces inherited from interface kotlinx.coroutines.experimental.Job

Job.DefaultImpls, Job.Key

Field Summary

Fields inherited from interface kotlinx.coroutines.experimental.Job

Key

Method Summary

Modifier and Type	Method and Description
boolean	cancel(java.lang.Throwable cause) 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.
void	initCancellability() Makes this continuation cancellable. Use it with holdCancellability optional parameter to suspendCancellableCoroutine function. It throws IllegalStateException if invoked more than once.
DisposableHandle	invokeOnCompletion(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler) 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.
boolean	isActive() Returns true when this continuation is active -- it has not completed or cancelled yet.
boolean	isCancelled() Returns true if this continuation was CancellableContinuation.cancel.
boolean	isCompleted() Returns true when this continuation has completed for any reason. A continuation that was cancelled is also considered complete.
void	resumeUndispatched(CoroutineDispatcher $receiver, T value) Resumes this continuation with a given value in the invoker thread without going though CoroutineDispatcher.dispatch function of the class CoroutineDispatcher in the context. This function is designed to be used only by the class CoroutineDispatcher implementations themselves. It should not be used in general code.
void	resumeUndispatchedWithException(CoroutineDispatcher $receiver, java.lang.Throwable exception) Resumes this continuation with a given exception in the invoker thread without going though CoroutineDispatcher.dispatch function of the class CoroutineDispatcher in the context. This function is designed to be used only by the class CoroutineDispatcher implementations themselves. It should not be used in general code.

Methods inherited from interface kotlinx.coroutines.experimental.Job

cancel, getCancellationException, getChildren, getOnJoin, invokeOnCompletion, invokeOnCompletion, isActive, isCancelled, isCompleted, join, start

Method Detail

isActive

boolean isActive()

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

isCompleted

boolean isCompleted()

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

isCancelled

boolean isCancelled()

Returns true if this continuation was CancellableContinuation.cancel.

It implies that CancellableContinuation.isActive is false and CancellableContinuation.isCompleted is true.

See Also:

CancellableContinuation.cancel, CancellableContinuation.isActive, CancellableContinuation.isCompleted

initCancellability

void initCancellability()

Makes this continuation cancellable. Use it with holdCancellability optional parameter to suspendCancellableCoroutine function. It throws IllegalStateException if invoked more than once.

See Also:

IllegalStateException

cancel

boolean cancel(java.lang.Throwable cause)

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.

invokeOnCompletion

DisposableHandle invokeOnCompletion(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)

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.

The resulting interface DisposableHandle can be used to DisposableHandle.dispose the registration of this handler and release its memory if its invocation is no longer needed. There is no need to dispose the handler after completion of this continuation. The references to all the handlers are released when this continuation completes.

Installed handler should not throw any exceptions. If it does, they will get caught, wrapped into exception CompletionHandlerException, and rethrown, potentially causing crash of unrelated code.

See Also:

interface DisposableHandle, DisposableHandle.dispose, exception CompletionHandlerException

resumeUndispatched

void resumeUndispatched(CoroutineDispatcher $receiver,
                        T value)

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

See Also:

CoroutineDispatcher.dispatch, class CoroutineDispatcher, context, class CoroutineDispatcher

resumeUndispatchedWithException

void resumeUndispatchedWithException(CoroutineDispatcher $receiver,
                                     java.lang.Throwable exception)

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

See Also:

CoroutineDispatcher.dispatch, class CoroutineDispatcher, context, class CoroutineDispatcher