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

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

Properties

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

Functions

Name	Summary
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

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

Extension Functions

Name	Summary
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

Name	Summary
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.