kotlinx-coroutines-core/kotlinx.coroutines/NonCancellable

NonCancellable

object NonCancellable : AbstractCoroutineContextElement, Job(source)

A non-cancelable job that is always active. It is designed for withContext function to prevent cancellation of code blocks that need to be executed without cancellation.

Use it like this:

withContext(NonCancellable) {
    // this code will not be cancelled
}

WARNING: This object is not designed to be used with launch, async, and other coroutine builders. if you write launch(NonCancellable) { ... } then not only the newly launched job will not be cancelled when the parent is cancelled, the whole parent-child relation between parent and child is severed. The parent will not wait for the child's completion, nor will be cancelled when the child crashed.

Extensions

cancel

fun CoroutineContext.cancel(cause: CancellationException? = null)

Cancels Job of this context with an optional cancellation cause. See Job.cancel for details.

fun Job.cancel(message: String, cause: Throwable? = null)

Cancels current job, including all its children with a specified diagnostic error message. A cause can be specified to provide additional details on a cancellation reason for debugging purposes.

cancelAndJoin

suspend fun Job.cancelAndJoin()

Cancels the job and suspends the invoking coroutine until the cancelled job is complete.

cancelChildren

fun CoroutineContext.cancelChildren(cause: CancellationException? = null)

Cancels all children of the Job in this context, without touching the state of this job itself with an optional cancellation cause. See Job.cancel. It does not do anything if there is no job in the context or it has no children.

fun Job.cancelChildren(cause: CancellationException? = null)

Cancels all children jobs of this coroutine using Job.cancel for all of them with an optional cancellation cause. Unlike Job.cancel on this job as a whole, the state of this job itself is not affected.

ensureActive

fun CoroutineContext.ensureActive()

Ensures that job in the current context is active.

fun Job.ensureActive()

Ensures that current job is active. If the job is no longer active, throws CancellationException. If the job was cancelled, thrown exception contains the original cancellation cause.

isActive

val CoroutineContext.isActive: Boolean

Returns true when the Job of the coroutine in this context is still active (has not completed and was not cancelled yet).

job

val CoroutineContext.job: Job

Retrieves the current Job instance from the given CoroutineContext or throws IllegalStateException if no job is present in the context.