kotlinx.coroutines.experimental

Class Unconfined

CoroutineDispatcher

kotlinx.coroutines.experimental.Unconfined

public class Unconfined
extends CoroutineDispatcher

A coroutine dispatcher that is not confined to any specific thread. It executes initial continuation of the coroutine right here in the current call-frame and let the coroutine resume in whatever thread that is used by the corresponding suspending function, without mandating any specific threading policy.

Note, that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption, but still want to execute it in the current call-frame until its first suspension, then you can use an optional enum CoroutineStart parameter in coroutine builders like launch and async setting it to the the value of CoroutineStart.UNDISPATCHED.

See Also:

enum CoroutineStart

Field Summary

Fields

Modifier and Type	Field and Description
static Unconfined	INSTANCE A coroutine dispatcher that is not confined to any specific thread. It executes initial continuation of the coroutine right here in the current call-frame and let the coroutine resume in whatever thread that is used by the corresponding suspending function, without mandating any specific threading policy.

Method Summary

Modifier and Type	Method and Description
void	dispatch(kotlin.coroutines.experimental.CoroutineContext context, java.lang.Runnable block) Dispatches execution of a runnable block onto another thread in the given context.
boolean	isDispatchNeeded(kotlin.coroutines.experimental.CoroutineContext context) Returns true if execution shall be dispatched onto another thread. The default behaviour for most dispatchers is to return true.
java.lang.String	toString()

Methods inherited from class kotlinx.coroutines.experimental.CoroutineDispatcher

dispatch, interceptContinuation, isDispatchNeeded, toString

Field Detail

INSTANCE

public static Unconfined INSTANCE

A coroutine dispatcher that is not confined to any specific thread. It executes initial continuation of the coroutine right here in the current call-frame and let the coroutine resume in whatever thread that is used by the corresponding suspending function, without mandating any specific threading policy.

Note, that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption, but still want to execute it in the current call-frame until its first suspension, then you can use an optional enum CoroutineStart parameter in coroutine builders like launch and async setting it to the the value of CoroutineStart.UNDISPATCHED.

See Also:

enum CoroutineStart

Method Detail

isDispatchNeeded

public boolean isDispatchNeeded(kotlin.coroutines.experimental.CoroutineContext context)

Returns true if execution shall be dispatched onto another thread. The default behaviour for most dispatchers is to return true.

UI dispatchers should not override isDispatchNeeded, but leave a default implementation that returns true. To understand the rationale beyond this recommendation, consider the following code:

fun asyncUpdateUI() = async(MainThread) {
    // do something here that updates something in UI
}

When you invoke asyncUpdateUI in some background thread, it immediately continues to the next line, while UI update happens asynchronously in the UI thread. However, if you invoke it in the UI thread itself, it updates UI synchronously if your isDispatchNeeded is overridden with a thread check. Checking if we are already in the UI thread seems more efficient (and it might indeed save a few CPU cycles), but this subtle and context-sensitive difference in behavior makes the resulting async code harder to debug.

Basically, the choice here is between "JS-style" asynchronous approach (async actions are always postponed to be executed later in the even dispatch thread) and "C#-style" approach (async actions are executed in the invoker thread until the first suspension point). While, C# approach seems to be more efficient, it ends up with recommendations like "use yield if you need to ....". This is error-prone. JS-style approach is more consistent and does not require programmers to think about whether they need to yield or not.

However, coroutine builders like launch and async accept an optional enum CoroutineStart parameter that allows one to optionally choose C#-style CoroutineStart.UNDISPATCHED behaviour whenever it is needed for efficiency.

See Also:

enum CoroutineStart

dispatch

public void dispatch(kotlin.coroutines.experimental.CoroutineContext context,
                     java.lang.Runnable block)

Dispatches execution of a runnable block onto another thread in the given context.

toString

public java.lang.String toString()