Job

A background job. Conceptually, a job is a cancellable thing with a lifecycle that concludes in its completion.

Jobs can be arranged into parent-child hierarchies where the cancellation of a parent leads to the immediate cancellation of all its children recursively. Failure of a child with an exception other than CancellationException immediately cancels its parent and, consequently, all its other children. This behavior can be customized using SupervisorJob.

The most basic instances of the Job interface are created like this:

• A coroutine job is created with the launch coroutine builder. It runs a specified block of code and completes upon completion of this block.

• CompletableJob is created with a Job() factory function. It is completed by calling CompletableJob.complete.

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

Job states

A job has the following states:

Note that these states are mentioned in italics below to make them easier to distinguish.

Usually, a job is created in the active state (it is created and started). However, coroutine builders that provide an optional start parameter create a coroutine in the 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 in the active state while the coroutine is working or until the CompletableJob completes, fails, or is cancelled.

Failure of an active job with an exception transitions the state to the cancelling state. A job can be cancelled at any time with the cancel function that forces it to transition to the cancelling state immediately. The job becomes cancelled when it finishes executing its work and all its children complete.

Completion of an active coroutine's body or a call to CompletableJob.complete transitions the job to the completing state. It waits in the completing state for all its children to complete before transitioning to the completed state. 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.

                                          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.

Cancellation cause

A coroutine job is said to complete exceptionally when its body throws an exception; a CompletableJob is completed exceptionally by calling CompletableJob.completeExceptionally. An exceptionally completed job is cancelled, and the corresponding exception becomes the cancellation cause of the job.

Normal cancellation of a job is distinguished from its failure by the exception that caused its cancellation. A coroutine that throws a CancellationException is considered to be cancelled normally. If a different exception causes the cancellation, then the job has failed. When a job has failed, its parent gets cancelled with the same type of exception, thus ensuring transparency in delegating parts of the job to its children.

Note, that the cancel function on a job only accepts a CancellationException as a cancellation cause, thus calling cancel always results in a normal cancellation of a job, which does not lead to cancellation of its parent. This way, a parent can cancel his children (cancelling all their children recursively, too) without cancelling himself.

Concurrency and synchronization

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.

Inheritors