Job

interface Job : Element

A background job. Conceptually, a job is a cancellable thing with a simple life-cycle that culminates in its completion. Jobs can be arranged into parent-child hierarchies where cancellation or completion of parent immediately cancels all its children.

The most basic instances of Job are created with launch coroutine builder or with a Job() factory function. Other coroutine builders and primitives like Deferred also implement Job interface.

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 (optional transient state) true false false
Cancelling (optional 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 can be cancelled at any time with cancel function that forces it to transition to cancelling state immediately. Job that is not backed by a coroutine (see Job() function) and does not have children becomes cancelled on cancel immediately. Otherwise, job becomes cancelled when it finishes executing its code and when all its children complete.

                                                        wait children
      +-----+       start      +--------+   complete   +-------------+  finish  +-----------+
      | New | ---------------> | Active | -----------> | Completing  | -------> | Completed |
      +-----+                  +--------+              +-------------+          +-----------+
         |                         |                         |
         | cancel                  | cancel                  | cancel
         V                         V                         |
    +-----------+   finish   +------------+                  |
    | Cancelled | <--------- | Cancelling | <----------------+
    |(completed)|            +------------+
    +-----------+

A job in the coroutineContext represents the coroutine itself. A job is active while the coroutine is working and job’s cancellation aborts the coroutine when the coroutine is suspended on a cancellable suspension point by throwing CancellationException.

A job can have a parent job. A job with a parent is cancelled when its parent is cancelled or completes exceptionally. Parent job waits for all its children to complete in completing or cancelling state. 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.

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 or cancelled yet. The job that is waiting for its children to complete is still considered to be active if it was not cancelled.

isCancelled

abstract val isCancelled: Boolean

Returns true if this job was cancelled. In the general case, it does not imply that the job has already completed (it may still be cancelling whatever it was doing).

isCompleted

abstract val isCompleted: Boolean

Returns true when this job has completed for any reason. A job that was cancelled 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(cause: Throwable? = null): Boolean

Cancels this job with an optional cancellation cause. The result is true if this job was cancelled as a result of this invocation and false otherwise (if it was already completed or if it is NonCancellable). Repeated invocations of this function have no effect and always produce false.

getCancellationException

abstract fun getCancellationException(): CancellationException

Returns CancellationException that signals the completion of this job. This function is used by cancellable suspending functions. They throw exception returned by this function when they suspend in the context of this job and this job becomes complete.

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.

abstract fun invokeOnCompletion(
    onCancelling: Boolean = false,
    invokeImmediately: Boolean = true,
    handler: CompletionHandler
): DisposableHandle

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

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.

cancelFutureOnCompletion

fun Job.cancelFutureOnCompletion(
    future: Future<*>
): DisposableHandle

Cancels a specified future when this job is cancelled. This is a shortcut for the following code with slightly more efficient implementation (one fewer object created).

disposeOnCompletion

fun Job.disposeOnCompletion(
    handle: DisposableHandle
): DisposableHandle

Disposes a specified handle when this job is complete.

joinChildren

suspend fun Job.joinChildren(): Unit

Suspends coroutine until all children of this job are complete using Job.join for all of them. Unlike Job.join on this job as a whole, it does not wait until this job is complete.

Inheritors

AbstractCoroutine

abstract class AbstractCoroutine<in T> : 
    JobSupport,
    Job,
    Continuation<T>,
    CoroutineScope

Abstract base class for implementation of coroutines in coroutine builders.

Deferred

interface Deferred<out T> : Job

Deferred value is a non-blocking cancellable future.

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.