Job

interface Job : Element (source)

A background job. Conceptually, a job is a cancellable thing with a life-cycle that culminates in its completion.

Jobs can be arranged into parent-child hierarchies where cancellation of parent lead to an immediate cancellation of all its children. Failure or cancellation of a child with an exception other than CancellationException immediately cancels its parent. This way, parent can cancel its own children (including all their children recursively) without cancelling itself.

The most basic instances of Job are created with launch coroutine builder or with a Job() factory function. By default, a failure of a any of the job’s children leads to an immediately failure of its parent and cancellation of the rest of its children. This behavior can be customized using SupervisorJob.

Conceptually, an execution of the job does not produce a result value. Jobs are launched solely for their side-effects. See Deferred interface for a job that produces a result.

A job has the following states:

State isActive isCompleted isCancelled
New (optional initial state) false false false
Active (default initial state) true false false
Completing (transient state) true false false
Cancelling (transient state) false false true
Cancelled (final state) false true true
Completed (final state) false true false

Usually, a job is created in active state (it is created and started). However, coroutine builders that provide an optional start parameter create a coroutine in new state when this parameter is set to CoroutineStart.LAZY. Such a job can be made active by invoking start or join.

A job is active while the coroutine is working. Failure of the job with exception makes it cancelling. A job can be cancelled it at any time with cancel function that forces it to transition to cancelling state immediately. The job becomes cancelled when it finishes executing it work.

                                          wait children
    +-----+ start  +--------+ complete   +-------------+  finish  +-----------+
    | New | -----> | Active | ---------> | Completing  | -------> | Completed |
    +-----+        +--------+            +-------------+          +-----------+
                     |  cancel / fail       |
                     |     +----------------+
                     |     |
                     V     V
                 +------------+                           finish  +-----------+
                 | Cancelling | --------------------------------> | Cancelled |
                 +------------+                                   +-----------+

A Job instance in the coroutineContext represents the coroutine itself.

A job can have a parent job. A job with a parent is cancelled when its parent is cancelled. Parent job waits in completing or cancelling state for all its children to complete before finishing. Note, that completing state is purely internal to the job. For an outside observer a completing job is still active, while internally it is waiting for its children.

Normal cancellation of a job is distinguished from its failure by the type of its cancellation exception cause. If the cause of cancellation is CancellationException, then the job is considered to be cancelled normally. This usually happens when cancel is invoked without additional parameters. If the cause of cancellation is a different exception, then the job is considered to have failed. This usually happens when the code of the job encounters some problem and throws an exception.

All functions on this interface and on all interfaces derived from it are thread-safe and can be safely invoked from concurrent coroutines without external synchronization.

Types

Key

companion object Key : Key<Job>

Key for Job instance in the coroutine context.

Properties

children

abstract val children: Sequence<Job>

Returns a sequence of this job’s children.

isActive

abstract val isActive: Boolean

Returns true when this job is active – it was already started and has not completed nor was cancelled yet. The job that is waiting for its children to complete is still considered to be active if it was not cancelled nor failed.

isCancelled

abstract val isCancelled: Boolean

Returns true if this job was cancelled for any reason, either by explicit invocation of cancel or because it had failed or its child or parent was cancelled. In the general case, it does not imply that the job has already completed, because it may still be finishing whatever it was doing and waiting for its children to complete.

isCompleted

abstract val isCompleted: Boolean

Returns true when this job has completed for any reason. A job that was cancelled or failed and has finished its execution is also considered complete. Job becomes complete only after all its children complete.

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(): Boolean

Cancels this job. The result is true if this job was either cancelled as a result of this invocation or was already being cancelled. If job is already completed, method returns false.

abstract fun cancel(cause: Throwable? = null): Boolean

Cancels this job with an optional cancellation cause. The result is true if this job was either cancelled as a result of this invocation or it’s being cancelled and given cause was successfully received by the job and will be properly handled, false otherwise.

invokeOnCompletion

abstract fun invokeOnCompletion(
    handler: CompletionHandler
): DisposableHandle

Registers handler that is synchronously invoked once on completion of this job. When job is already complete, then the handler is immediately invoked with a job’s exception or cancellation cause or null. Otherwise, handler will be invoked once when this job is 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 Properties

isActive

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

Extension Functions

cancel

Cancels Job of this context. The result is true if the job was cancelled as a result of this invocation or was already being cancelled and false if there is no job in the context or if it was already completed. See Job.cancel for details.

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.

cancelChildren

fun Job.cancelChildren(cause: Throwable? = null): Unit

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

cancelChildren

fun CoroutineContext.cancelChildren(): Unit

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

Inheritors

Deferred

interface Deferred<out T> : Job

Deferred value is a non-blocking cancellable future — it is a Job that has a result.

NonCancellable

object NonCancellable : AbstractCoroutineContextElement, Job

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.