Job.md

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

Job

interface Job : Element (source)

A background job. A job can be cancelled at any time with cancel function that forces it to become completed immediately.

It has two states:

• Active (initial state) -- isActive true, getCompletionException throws IllegalStateException.
• Completed (final state) -- isActive false.

A job in the coroutine context 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 or the cancellation cause inside the coroutine.

A job can have a parent. A job with a parent is cancelled when its parent completes.

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

| Registration | interface Registration
Registration object for onCompletion. It can be used to unregister if needed. There is no need to unregister after completion. |

Properties

| isActive | abstract val isActive: Boolean
Returns true when job is still active. |

Functions

| cancel | abstract fun cancel(cause: Throwable? = null): Boolean
Cancel this activity 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. | | getCompletionException | abstract fun getCompletionException(): Throwable
Returns the exception that signals the completion of this job -- it returns the original cancel cause or an instance of CancellationException if this job had completed normally or was cancelled without a cause. This function throws IllegalStateException when invoked for an active job. | | onCompletion | abstract fun onCompletion(handler: CompletionHandler): Registration
Registers completion handler. The action depends on the state of this job. When job is cancelled with cancel, then the handler is immediately invoked with a cancellation cause or with a fresh CancellationException. Otherwise, handler will be invoked once when this job is complete (cancellation also is a form of completion). | | plus | open operator fun ~~plus~~(other: Job): Job |

Companion Object Functions

| invoke | operator fun invoke(parent: Job? = null): Job
Creates new job object. It is optionally a child of a parent job. |

Extension Functions

| cancelFutureOnCompletion | fun Job.cancelFutureOnCompletion(future: Future<*>): Registration
Cancels a specified [future](../cancel-future-on-completion.md#kotlinx.coroutines.experimental$cancelFutureOnCompletion(kotlinx.coroutines.experimental.Job, java.util.concurrent.Future((kotlin.Any)))/future) when this job is complete. This is a shortcut for the following code with slightly more efficient implementation (one fewer object created). | | join | suspend fun Job.join(): Unit
Suspends coroutine until this job is complete. This invocation resumes normally (without exception) when the job is complete for any reason. | | unregisterOnCompletion | fun Job.unregisterOnCompletion(registration: Registration): Registration
Unregisters a specified [registration](../unregister-on-completion.md#kotlinx.coroutines.experimental$unregisterOnCompletion(kotlinx.coroutines.experimental.Job, kotlinx.coroutines.experimental.Job.Registration)/registration) when this job is complete. This is a shortcut for the following code with slightly more efficient implementation (one fewer object created). |

Inheritors

| 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 resumes with CancellationException or with the specified cancel cause. | | ChannelJob | interface ChannelJob<out E> : Job, ReceiveChannel<E>
Return type for buildChannel. | | Deferred | interface Deferred<out T> : Job
Deferred value is conceptually a non-blocking cancellable future. It is created with defer coroutine builder. It is in active state while the value is being computed. | | NonCancellable | object NonCancellable : AbstractCoroutineContextElement, Job
A non-cancelable job that is always active. It is designed to be used with run builder to prevent cancellation of code blocks that need to run without cancellation. |