CoroutineScope

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.

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 on entities with 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 {
    lateinit var job: Job
    override val coroutineContext: CoroutineContext
        get() = Dispatchers.Main + job

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        job = Job()
    }

    override fun onDestroy() {
        super.onDestroy()
        job.cancel() // Cancel job on activity destroy. After destroy all children jobs will be cancelled automatically
    }

    /*
     * 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 loadDataFromUI() = launch { // <- extension on current activity, launched in the main thread
           val ioData = async(Dispatchers.IO) { // <- extension on launch scope, launched in IO dispatcher
               // blocking I/O operation
           }
           // do something else concurrently with I/O
           val data = ioData.await() // wait for result of I/O
           draw(data) // can draw in the main thread
        }
    }

Properties

coroutineContext

abstract val coroutineContext: CoroutineContext Context of this scope.

Extension Properties

isActive

val CoroutineScope.isActive: Boolean Returns true when 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 new coroutine and returns its future result as an implementation of Deferred. The running coroutine is cancelled when the resulting deferred is cancelled.
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.
launch	fun CoroutineScope.launch(     context: CoroutineContext = EmptyCoroutineContext,     start: CoroutineStart = CoroutineStart.DEFAULT,     block: suspend CoroutineScope.() -> Unit ): Job Launches new coroutine without blocking 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
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.

Inheritors

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.