CoroutineScope

interface CoroutineScope (source)

Defines a scope for new coroutines. Every coroutine builder is an extension on CoroutineScope and inherits its coroutineContext to automatically propagate both context elements and cancellation.

The best ways to obtain a standalone instance of the scope are CoroutineScope and MainScope factory functions. Additional context elements can be appended to the scope using the plus operator.

Manual implementation of this interface is not recommended, implementation by delegation should be preferred instead. By convention, the context of a scope should contain an instance of a job to enforce structured concurrency.

Every coroutine builder (like launch, async, etc) and every scoping function (like coroutineScope, withContext, etc) provides its own scope with its own Job instance into the inner block of code it runs. By convention, they all wait for all the coroutines inside their block to complete before completing themselves, thus enforcing the discipline of structured concurrency.

CoroutineScope should be implemented (or used as a field) on entities with a well-defined lifecycle that are responsible for launching children coroutines. Example of such entity on Android is Activity. Usage of this interface may look like this:

class MyActivity : AppCompatActivity(), CoroutineScope by MainScope() {
    override fun onDestroy() {
        cancel() // cancel is extension on CoroutineScope
    }

    /*
     * Note how coroutine builders are scoped: if activity is destroyed or any of the launched coroutines
     * in this method throws an exception, then all nested coroutines are cancelled.
     */
        fun showSomeData() = launch { // <- extension on current activity, launched in the main thread
           // ... here we can use suspending functions or coroutine builders with other dispatchers
           draw(data) // draw in the main thread
        }
    }

Properties

coroutineContext

abstract val coroutineContext: CoroutineContext

The context of this scope. Context is encapsulated by the scope and used for implementation of coroutine builders that are extensions on the scope. Accessing this property in general code is not recommended for any purposes except accessing the Job instance for advanced usages.

Extension Properties

isActive

val CoroutineScope.isActive: Boolean

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

Extension Functions

actor

fun <E> CoroutineScope.actor(
    context: CoroutineContext = EmptyCoroutineContext,
    capacity: Int = 0,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    onCompletion: CompletionHandler? = null,
    block: suspend ActorScope<E>.() -> Unit
): SendChannel<E>

Launches new coroutine that is receiving messages from its mailbox channel and returns a reference to its mailbox channel as a SendChannel. The resulting object can be used to send messages to this coroutine.

async

fun <T> CoroutineScope.async(
    context: CoroutineContext = EmptyCoroutineContext,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    block: suspend CoroutineScope.() -> T
): Deferred<T>

Creates a coroutine and returns its future result as an implementation of Deferred. The running coroutine is cancelled when the resulting deferred is cancelled. The resulting coroutine has a key difference compared with similar primitives in other languages and frameworks: it cancels the parent job (or outer scope) on failure to enforce structured concurrency paradigm. To change that behaviour, supervising parent (SupervisorJob or supervisorScope) can be used.

broadcast

fun <E> CoroutineScope.broadcast(
    context: CoroutineContext = EmptyCoroutineContext,
    capacity: Int = 1,
    start: CoroutineStart = CoroutineStart.LAZY,
    onCompletion: CompletionHandler? = null,
    block: suspend ProducerScope<E>.() -> Unit
): BroadcastChannel<E>

Launches new coroutine to produce a stream of values by sending them to a broadcast channel and returns a reference to the coroutine as a BroadcastChannel. The resulting object can be used to subscribe to elements produced by this coroutine.

cancel

fun CoroutineScope.cancel(
    cause: CancellationException? = null
): Unit

Cancels this scope, including its job and all its children with an optional cancellation cause. A cause can be used to specify an error message or to provide other details on a cancellation reason for debugging purposes. Throws IllegalStateException if the scope does not have a job in it.

fun CoroutineScope.cancel(
    message: String,
    cause: Throwable? = null
): Unit

Cancels this scope, including its job and all its children with a specified diagnostic error message. A cause can be specified to provide additional details on a cancellation reason for debugging purposes. Throws IllegalStateException if the scope does not have a job in it.

ensureActive

fun CoroutineScope.ensureActive(): Unit

Ensures that current scope is active. Throws IllegalStateException if the context does not have a job in it.

launch

fun CoroutineScope.launch(
    context: CoroutineContext = EmptyCoroutineContext,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    block: suspend CoroutineScope.() -> Unit
): Job

Launches a new coroutine without blocking the current thread and returns a reference to the coroutine as a Job. The coroutine is cancelled when the resulting job is cancelled.

newCoroutineContext

expect fun CoroutineScope.newCoroutineContext(
    context: CoroutineContext
): CoroutineContext

Creates context for the new coroutine. It installs Dispatchers.Default when no other dispatcher nor ContinuationInterceptor is specified, and adds optional support for debugging facilities (when turned on).

plus

operator fun CoroutineScope.plus(
    context: CoroutineContext
): CoroutineScope

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

produce

fun <E> CoroutineScope.produce(
    context: CoroutineContext = EmptyCoroutineContext,
    capacity: Int = 0,
    block: suspend ProducerScope<E>.() -> Unit
): ReceiveChannel<E>

Launches new coroutine to produce a stream of values by sending them to a channel and returns a reference to the coroutine as a ReceiveChannel. This resulting object can be used to receive elements produced by this coroutine.

promise

fun <T> CoroutineScope.promise(
    context: CoroutineContext = EmptyCoroutineContext,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    block: suspend CoroutineScope.() -> T
): Promise<T>

Starts new coroutine and returns its result as an implementation of Promise.

Inheritors

ActorScope

interface ActorScope<E> : CoroutineScope, ReceiveChannel<E>

Scope for actor coroutine builder.

GlobalScope

object GlobalScope : CoroutineScope

A global CoroutineScope not bound to any job.

ProducerScope

interface ProducerScope<in E> : 
    CoroutineScope,
    SendChannel<E>

Scope for produce coroutine builder.