kotlinx.coroutines.experimental

Interface CancellableContinuation<T>

public CancellableContinuation<T>

Cancellable continuation. It 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

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.
void	invokeOnCancellation(kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler) Registers handler that is synchronously invoked once on cancellation (both regular and exceptional) of this continuation. When the continuation is already cancelled, then the handler is immediately invoked with cancellation exception. Otherwise, the handler will be invoked once on cancellation if this continuation is cancelled.
DisposableHandle	invokeOnCompletion(boolean onCancelling, boolean invokeImmediately, kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler) Deprecated.
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.

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(boolean onCancelling,
                                    boolean invokeImmediately,
                                    kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)

Deprecated.

Registers handler that is synchronously invoked once on cancellation (both regular and exceptional) of this continuation. When the continuation is already cancelled, then the handler is immediately invoked with cancellation exception. Otherwise, the handler will be invoked once on cancellation if this continuation is cancelled.

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

At most one handler can be installed on one continuation

Parameters:

invokeImmediately - not used

onCancelling - not used

Returns:

not used

See Also:

exception CompletionHandlerException

invokeOnCancellation

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

Registers handler that is synchronously invoked once on cancellation (both regular and exceptional) of this continuation. When the continuation is already cancelled, then the handler is immediately invoked with cancellation exception. Otherwise, the handler will be invoked once on cancellation if this continuation is cancelled.

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

At most one handler can be installed on one continuation.

See Also:

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