public enum CoroutineStart
Defines start options for coroutines builders.
It is used in start
parameter of BuildersKt.launch
, BuildersKt.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.
BuildersKt.launch
,
BuildersKt.async
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.getUnconfined . However, when coroutine is resumed from suspension
it is dispatched according to the class CoroutineDispatcher in its context. |
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.getUnconfined
always returns false
from its CoroutineDispatcher.isDispatchNeeded
function, so starting coroutine with Dispatchers.getUnconfined
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.
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 BuildersKt.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.
BuildersKt.launch
,
BuildersKt.async
,
interface Job
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.
public static CoroutineStart UNDISPATCHED
Immediately executes coroutine until its first suspension point in the current thread as if the
coroutine was started using Dispatchers.getUnconfined
. 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.
Note: This is an experimental api. Execution semantics of coroutines may change in the future when this mode is used.