kotlinx.coroutines

Class CoroutineScopeKt

kotlinx.coroutines.CoroutineScopeKt

public class CoroutineScopeKt

Method Summary

Modifier and Type	Method and Description
static CoroutineScope	CoroutineScope(NonExistentClass context) Creates interface CoroutineScope that wraps the given coroutine context.
static CoroutineScope	MainScope() Creates the main interface CoroutineScope for UI components.
static void	cancel(CoroutineScope $receiver) Cancels this scope, including its job and all its children. Throws IllegalStateException if the scope does not have a job in it.
static <R> java.lang.Object	coroutineScope(kotlin.jvm.functions.Function2<? super kotlinx.coroutines.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super R>,? extends java.lang.Object> block, kotlin.coroutines.experimental.Continuation<? super R> p) Creates new interface CoroutineScope and calls the specified suspend block with this scope. The provided scope inherits its CoroutineScope.getCoroutineContext from the outer scope, but overrides context's interface Job.
static boolean	isActive(CoroutineScope $receiver) Returns true when current interface Job is still active (has not completed and was not cancelled yet).
static CoroutineScope	plus(CoroutineScope $receiver, NonExistentClass context) Adds the specified coroutine context to this scope, overriding existing elements in the current scope's context with the corresponding keys.

Method Detail

plus

public static CoroutineScope plus(CoroutineScope $receiver,
                                  NonExistentClass context)

Adds the specified coroutine context to this scope, overriding existing elements in the current scope's context with the corresponding keys.

This is a shorthand for CoroutineScope(thisScope + context).

MainScope

public static CoroutineScope MainScope()

Creates the main interface CoroutineScope for UI components.

Example of use:

class MyAndroidActivity {
  private val scope = MainScope()

  override fun onDestroy() {
    super.onDestroy()
    scope.cancel()
  }
}

The resulting scope has SupervisorKt.SupervisorJob and Dispatchers.getMain context elements. If you want to append additional elements to the main scope, use CoroutineScopeKt.plus operator: val scope = MainScope() + CoroutineName("MyActivity").

See Also:

interface CoroutineScope, SupervisorKt.SupervisorJob, Dispatchers.getMain, CoroutineScopeKt.plus

isActive

public static boolean isActive(CoroutineScope $receiver)

Returns true when current interface Job is still active (has not completed and was not cancelled yet).

Check this property in long-running computation loops to support cancellation:

while (isActive) {
    // do some computation
}

This property is a shortcut for coroutineContext.isActive in the scope when interface CoroutineScope is available. See coroutineContext, CoroutineScopeKt.isActive and Job.isActive.

See Also:

interface Job, interface CoroutineScope, coroutineContext, CoroutineScopeKt.isActive, Job.isActive

coroutineScope

public static <R> java.lang.Object coroutineScope(kotlin.jvm.functions.Function2<? super kotlinx.coroutines.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super R>,? extends java.lang.Object> block,
                                                  kotlin.coroutines.experimental.Continuation<? super R> p)

Creates new interface CoroutineScope and calls the specified suspend block with this scope. The provided scope inherits its CoroutineScope.getCoroutineContext from the outer scope, but overrides context's interface Job.

This function is designed for a parallel decomposition of work. When any child coroutine in this scope fails, this scope fails and all the rest of the children are cancelled (for a different behavior see SupervisorKt.supervisorScope). This function returns as soon as given block and all its children coroutines are completed. Example of the scope usages looks like this:

suspend fun loadDataForUI() = coroutineScope {

  val data = async { // <- extension on current scope
     ... load some UI data ...
  }

  withContext(UI) {
    doSomeWork()
    val result = data.await()
    display(result)
  }
}

Semantics of the scope in this example:

1. loadDataForUI returns as soon as data is loaded and UI is updated.

2. If doSomeWork throws an exception, then async task is cancelled and loadDataForUI rethrows that exception.

3. If outer scope of loadDataForUI is cancelled, both started async and withContext are cancelled.

Method may throw CancellationException if the current job was cancelled externally or may throw the corresponding unhandled Throwable if there is any unhandled exception in this scope (for example, from a crashed coroutine that was started with BuildersKt.launch in this scope).

See Also:

interface CoroutineScope, CoroutineScope.getCoroutineContext, interface Job, SupervisorKt.supervisorScope, Throwable, BuildersKt.launch

CoroutineScope

public static CoroutineScope CoroutineScope(NonExistentClass context)

Creates interface CoroutineScope that wraps the given coroutine context.

If the given context does not contain a interface Job element, then a default Job() is created. This way, cancellation or failure or any child coroutine in this scope cancels all the other children, just like inside CoroutineScopeKt.coroutineScope block.

See Also:

interface CoroutineScope, interface Job, CoroutineScopeKt.coroutineScope

cancel

public static void cancel(CoroutineScope $receiver)

Cancels this scope, including its job and all its children. Throws IllegalStateException if the scope does not have a job in it.

This API is experimental in order to investigate possible clashes with other cancellation mechanisms.

See Also:

IllegalStateException