kotlinx-coroutines-core / kotlinx.coroutines.experimental / Job

Job

interface Job : Element (source)

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

attachChild	`abstract fun attachChild(child: Job): DisposableHandle`
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 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 complete.
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.
CancellableContinuation	`interface CancellableContinuation<in T> : Continuation<T>, Job` Cancellable continuation. Its job is completed when it is resumed or cancelled. When cancel function is explicitly invoked, this continuation immediately resumes with CancellationException or with the specified cancel cause.
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.