kotlinx.coroutines

Enum CoroutineStart

public enum CoroutineStart

Defines start options for coroutines builders. It is used in start parameter of BuildersKt.launch, DeferredKt.async, and other coroutine builder functions.

The summary of coroutine start options is:

• DEFAULT -- immediately schedules coroutine for execution according to its context;

• LAZY -- starts coroutine lazily, only when it is needed;

• ATOMIC -- atomically (in a non-cancellable way) schedules coroutine for execution according to its context;

• UNDISPATCHED -- immediately executes coroutine until its first suspension point in the current thread.

See Also:

BuildersKt.launch, DeferredKt.async

Enum Constant Summary

Enum Constants

Enum Constant and Description
ATOMIC Atomically (i.e., in a non-cancellable way) schedules coroutine for execution according to its context. This is similar to DEFAULT, but the coroutine cannot be cancelled before it starts executing.
DEFAULT Default -- immediately schedules coroutine for execution according to its context.
LAZY Starts coroutine lazily, only when it is needed.
UNDISPATCHED Immediately executes coroutine until its first suspension point in the current thread as if the coroutine was started using Dispatchers.Unconfined. However, when coroutine is resumed from suspension it is dispatched according to the class CoroutineDispatcher in its context.

Method Summary

Modifier and Type	Method and Description
<T> void	invoke(kotlin.jvm.functions.Function1<? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block, NonExistentClass completion) Starts the corresponding block as a coroutine with this coroutine start strategy.
<R,T> void	invoke(kotlin.jvm.functions.Function2<? super R,? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block, R receiver, NonExistentClass completion) Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.
boolean	isLazy() Returns true when LAZY.

Enum Constant Detail

DEFAULT

public static CoroutineStart DEFAULT

Default -- immediately schedules coroutine for execution according to its context.

If the class CoroutineDispatcher of the coroutine context returns true from CoroutineDispatcher.isDispatchNeeded function as most dispatchers do, then the coroutine code is dispatched for execution later, while the code that invoked the coroutine builder continues execution.

Note, that Dispatchers.Unconfined always returns false from its CoroutineDispatcher.isDispatchNeeded function, so starting coroutine with Dispatchers.Unconfined by DEFAULT is the same as using UNDISPATCHED.

If coroutine interface Job is cancelled before it even had a chance to start executing, then it will not start its execution at all, but will complete with an exception.

Cancellability of coroutine at suspension points depends on the particular implementation details of suspending functions. Use suspendCancellableCoroutine to implement cancellable suspending functions.

See Also:

class CoroutineDispatcher, CoroutineDispatcher.isDispatchNeeded, CoroutineDispatcher.isDispatchNeeded, interface Job

LAZY

public static CoroutineStart LAZY

Starts coroutine lazily, only when it is needed.

See the documentation for the corresponding coroutine builders for details (like BuildersKt.launch and DeferredKt.async).

If coroutine interface Job is cancelled before it even had a chance to start executing, then it will not start its execution at all, but will complete with an exception.

See Also:

BuildersKt.launch, DeferredKt.async, interface Job

ATOMIC

public static CoroutineStart ATOMIC

Atomically (i.e., in a non-cancellable way) schedules coroutine for execution according to its context. This is similar to DEFAULT, but the coroutine cannot be cancelled before it starts executing.

Cancellability of coroutine at suspension points depends on the particular implementation details of suspending functions as in DEFAULT.

UNDISPATCHED

public static CoroutineStart UNDISPATCHED

Immediately executes coroutine until its first suspension point in the current thread as if the coroutine was started using Dispatchers.Unconfined. However, when coroutine is resumed from suspension it is dispatched according to the class CoroutineDispatcher in its context.

This is similar to ATOMIC in the sense that coroutine starts executing even if it was already cancelled, but the difference is that it starts executing in the same thread.

Cancellability of coroutine at suspension points depends on the particular implementation details of suspending functions as in DEFAULT.

See Also:

class CoroutineDispatcher

Method Detail

invoke

public <T> void invoke(kotlin.jvm.functions.Function1<? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block,
                       NonExistentClass completion)

Starts the corresponding block as a coroutine with this coroutine start strategy.

• DEFAULT uses CancellableKt.startCoroutineCancellable.

• ATOMIC uses startCoroutine.

• UNDISPATCHED uses UndispatchedKt.startCoroutineUndispatched.

• LAZY does nothing.

See Also:

CancellableKt.startCoroutineCancellable, UndispatchedKt.startCoroutineUndispatched

invoke

public <R,T> void invoke(kotlin.jvm.functions.Function2<? super R,? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block,
                         R receiver,
                         NonExistentClass completion)

Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.

• DEFAULT uses CancellableKt.startCoroutineCancellable.

• ATOMIC uses startCoroutine.

• UNDISPATCHED uses UndispatchedKt.startCoroutineUndispatched.

• LAZY does nothing.

See Also:

CancellableKt.startCoroutineCancellable, UndispatchedKt.startCoroutineUndispatched

isLazy

public boolean isLazy()

Returns true when LAZY.