coroutineScope

suspend fun <R> coroutineScope(
    block: suspend CoroutineScope.() -> R
): R
(source)

Creates new CoroutineScope and calls the specified suspend block with this scope. The provided scope inherits its coroutineContext from the outer scope, but overrides context’s 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 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 showSomeData() = coroutineScope {

  val data = async(Dispatchers.IO) { // <- extension on current scope
     ... load some UI data for the Main thread ...
  }

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

Semantics of the scope in this example:

  1. showSomeData returns as soon as data is loaded and displayed in the UI.
  2. If doSomeWork throws an exception, then async task is cancelled and showSomeData rethrows that exception.
  3. If outer scope of showSomeData is cancelled, both started async and withContext blocks are cancelled.
  4. If async block fails, withContext will be 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 launch in this scope).