public Job
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 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 | 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 Job.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 and does not have
Job.attachChild 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 Job.attachChild 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.
| Modifier and Type | Interface and Description |
|---|---|
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 children.
|
static class |
Job.Key
Key for
interface Job instance in the coroutine context. |
| Modifier and Type | Field and Description |
|---|---|
static Job.Key |
Key
Key for
interface Job instance in the coroutine context. |
| Modifier and Type | Method and Description |
|---|---|
DisposableHandle |
attachChild(Job child)
Attaches child job so that this job becomes its parent and
returns a handle that should be used to detach it.
|
boolean |
cancel(java.lang.Throwable cause)
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 class NonCancellable).
Repeated invocations of this function have no effect and always produce false. |
void |
cancelChildren(java.lang.Throwable cause)
Cancels all
Job.attachChild jobs of this coroutine with the given cause. Unlike cancel,
the state of this job itself is not affected. |
java.util.concurrent.CancellationException |
getCancellationException()
Returns CancellationException that signals the completion of this job.
|
SelectClause0 |
getOnJoin()
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.
|
DisposableHandle |
invokeOnCompletion(boolean onCancelling,
kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)
Registers handler that is synchronously invoked once on cancellation or completion of this job.
When job is already complete, then the handler is immediately invoked
with a job's cancellation cause or
null. Otherwise, handler will be invoked once when this
job is cancelled or complete. |
boolean |
isActive()
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 Job.attachChild to complete is still considered to be active if it
was not cancelled. |
boolean |
isCancelled()
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). |
boolean |
isCompleted()
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 Job.attachChild complete. |
java.lang.Object |
join(kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> $continuation)
Suspends coroutine until this job is complete. This invocation resumes normally (without exception)
when the job is complete for any reason and the
interface Job of the invoking coroutine is still active.
This function also Job.start the corresponding coroutine if the interface Job was still in new state. |
boolean |
start()
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. |
static Job.Key Key
Key for interface Job instance in the coroutine context.
interface Jobboolean isActive()
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 Job.attachChild to complete is still considered to be active if it
was not cancelled.
Job.attachChildboolean isCompleted()
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 Job.attachChild complete.
Job.attachChildboolean isCancelled()
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).
java.util.concurrent.CancellationException getCancellationException()
Returns CancellationException that signals the completion of this job.
It returns the original cancel cause if it is an instance of CancellationException or
an instance of exception JobCancellationException if this job was cancelled with a cause of
different type, was cancelled without a cause or had completed normally.
This function throws IllegalStateException when invoked for an job that has not completed nor cancelled yet.
The cancellable suspending functions throw this exception when trying to suspend in the context of this job.
boolean start()
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.
boolean cancel(java.lang.Throwable cause)
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 class NonCancellable).
Repeated invocations of this function have no effect and always produce false.
When cancellation has a clear reason in the code, an instance of CancellationException should be created at the corresponding original cancellation site and passed into this method to aid in debugging by providing both the context of cancellation and text description of the reason.
class NonCancellableDisposableHandle attachChild(Job child)
Attaches child job so that this job becomes its parent and returns a handle that should be used to detach it.
A parent-child relation has the following effect:
Cancellation of parent with cancel or its exceptional completion (failure) immediately cancels all its children.
Parent cannot complete until all its children are complete. Parent waits for all its children to complete in completing or cancelling state.
A child must store the resulting interface DisposableHandle and DisposableHandle.dispose the attachment
to its parent on its own completion.
Coroutine builders and job factory functions that accept parent CoroutineContext parameter
lookup a interface Job instance in the parent context and use this function to attach themselves as a child.
They also store a reference to the resulting interface DisposableHandle and dispose a handle when they complete.
void cancelChildren(java.lang.Throwable cause)
Cancels all Job.attachChild jobs of this coroutine with the given cause. Unlike cancel,
the state of this job itself is not affected.
Job.attachChildjava.lang.Object join(kotlin.coroutines.experimental.Continuation<? super kotlin.Unit> $continuation)
Suspends coroutine until this job is complete. This invocation resumes normally (without exception)
when the job is complete for any reason and the interface Job of the invoking coroutine is still active.
This function also Job.start the corresponding coroutine if the interface Job was still in new state.
Note, that the job becomes complete only when all its Job.attachChild are complete.
This suspending function is cancellable and always checks for the cancellation of invoking coroutine's Job.
If the interface Job of the invoking coroutine is cancelled or completed when this
suspending function is invoked or while it is suspended, this function
throws CancellationException.
In particular, it means that a parent coroutine invoking join on a child coroutine that was started using
launch(coroutineContext) { ... } builder throws CancellationException if the child
had crashed, unless a non-standard interface CoroutineExceptionHandler if installed in the context.
This function can be used in select invocation with onJoin clause. Use isCompleted to check for completion of this job without waiting.
There is cancelAndJoin function that combines an invocation of cancel and join.
SelectClause0 getOnJoin()
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.
DisposableHandle invokeOnCompletion(boolean onCancelling, kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> handler)
Registers handler that is synchronously invoked once on cancellation or completion of this job.
When job is already complete, then the handler is immediately invoked
with a job's cancellation cause or null. Otherwise, handler will be invoked once when this
job is cancelled or complete.
Invocation of this handler on a transition to a transient cancelling state
is controlled by onCancelling boolean parameter.
The handler is invoked on invocation of cancel when
job becomes cancelling if onCancelling parameter is set to true. However,
when this interface Job is not backed by a coroutine, like interface CompletableDeferred or interface CancellableContinuation
(both of which do not posses a cancelling state), then the value of onCancelling parameter is ignored.
The resulting interface DisposableHandle can be used to DisposableHandle.dispose the
registration of this handler and release its memory if its invocation is no longer needed.
There is no need to dispose the handler after completion of this job. The references to
all the handlers are released when this job completes.
Installed handler should not throw any exceptions. If it does, they will get caught,
wrapped into exception CompletionHandlerException, and rethrown, potentially causing crash of unrelated code.
Note: This function is a part of internal machinery that supports parent-child hierarchies
and allows for implementation of suspending functions that wait on the Job's state.
This function should not be used in general application code.
Implementations of CompletionHandler must be fast and lock-free.