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 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 Job.getChildren.

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

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 (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 Job.start or Job.join.

A job can be cancelled at any time with Job.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 Job.getChildren becomes cancelled on Job.cancel immediately. Otherwise, job becomes cancelled when it finishes executing its code and when all its children Job.isCompleted.

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

A job in the CoroutineScope.getCoroutineContext 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.

See Also:

Job.getChildren, interface Job, interface Deferred, interface Job, Job.isActive, Job.isCompleted, Job.isCancelled, Job.start, Job.join, Job.cancel, Job.getChildren, Job.cancel, Job.isCompleted, CoroutineScope.getCoroutineContext

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)