kotlinx.coroutines.experimental

Class Job.DefaultImpls

kotlinx.coroutines.experimental.Job.DefaultImpls

Enclosing interface:

Job

public static class Job.DefaultImpls

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 Job.getChildren. Failure or cancellation of a child with an exception other than CancellationException immediately cancels its parent. This way, parent can Job.cancel its own children (including all their children recursively) without cancelling itself.

The most basic instances of interface Job are created with BuildersKt.launch coroutine builder or with a Job() factory function. Conceptually, an execution of the job does not produce a result value. Jobs are launched solely for their side-effects. See interface Deferred interface for a job that produces a result.

A job has the following states:

| State | Job.isActive | Job.isCompleted | Job.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 Job.start or Job.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 Job.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 Job.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.

See Also:

Job.getChildren, Job.cancel, interface Job, BuildersKt.launch, interface Deferred, Job.isActive, Job.isCompleted, Job.isCancelled, Job.start, Job.join, Job.cancel, coroutineContext, Job.cancel

Method Summary

Modifier and Type	Method and Description
static <R> R	fold(Job $this, R initial, kotlin.jvm.functions.Function2<? super R,? super kotlin.coroutines.experimental.CoroutineContext.Element,? extends R> operation)
static <E extends Element> E	get(Job $this, kotlin.coroutines.experimental.CoroutineContext.Key<E> key)
static kotlin.coroutines.experimental.CoroutineContext	minusKey(Job $this, kotlin.coroutines.experimental.CoroutineContext.Key<?> key)
static kotlin.coroutines.experimental.CoroutineContext	plus(Job $this, kotlin.coroutines.experimental.CoroutineContext context)

Method Detail

plus

public static kotlin.coroutines.experimental.CoroutineContext plus(Job $this,
                                                                   kotlin.coroutines.experimental.CoroutineContext context)

fold

public static <R> R fold(Job $this,
                         R initial,
                         kotlin.jvm.functions.Function2<? super R,? super kotlin.coroutines.experimental.CoroutineContext.Element,? extends R> operation)

get

public static <E extends Element> E get(Job $this,
                                        kotlin.coroutines.experimental.CoroutineContext.Key<E> key)

minusKey

public static kotlin.coroutines.experimental.CoroutineContext minusKey(Job $this,
                                                                       kotlin.coroutines.experimental.CoroutineContext.Key<?> key)