coroutineScope y supervisorScope: elegir la propagación

Todo lo estudiado en este nivel converge en una pregunta de diseño que hay que responder cada vez que se escribe una función concurrente, y que es más de dominio que de programación: si una de estas tareas fracasa, las demás quedan sin sentido o siguen valiendo lo que valían. La respuesta no la puede dar la biblioteca porque depende de qué signifiquen las tareas; lo que la biblioteca hace es ofrecer dos constructores casi idénticos, uno para cada respuesta, y garantizar que la elección quede escrita en el código para siempre. Un ámbito construido con coroutineScope implementa la primera respuesta y trata al conjunto como una operación indivisible: si una pieza falla, la operación entera ha fallado y no tiene sentido gastar más. Un ámbito construido con supervisorScope implementa la segunda y trata a las hijas como intentos independientes bajo un mismo techo. Aprender a distinguirlas es lo que separa un sistema que se derrumba entero por un error periférico de otro que degrada con elegancia.

El ámbito local como unidad de composición

La función coroutineScope crea un ámbito hijo del contexto actual, ejecuta su bloque y no retorna hasta que ese bloque y todas las corrutinas lanzadas en él han terminado. Es el mecanismo que convierte una función suspend corriente en una operación internamente concurrente sin que sus llamadores tengan que enterarse: desde fuera se sigue viendo una llamada que empieza, tarda y acaba.

suspend fun informe(id: Id): Informe = coroutineScope {
    val ventas = async { repo.ventas(id) }
    val costes = async { repo.costes(id) }
    Informe(ventas.await(), costes.await())
}

Conviene enunciar sus dos garantías por separado porque se usan en momentos distintos. La primera es de terminación: al salir del bloque, ninguna corrutina creada dentro sigue viva, así que se pueden liberar recursos, cerrar transacciones y medir tiempos con la certeza de que no hay trabajo pendiente. La segunda es de cancelación: si quien llamó cancela la operación, la cancelación baja al ámbito y de ahí a todas sus hijas, sin que haya que propagarla a mano.

La diferencia está en el sentido del fallo

Ambos constructores propagan la cancelación hacia abajo de forma idéntica: cancelar el ámbito cancela a todas las hijas, con supervisor o sin él. La diferencia está exclusivamente en el sentido contrario. En un coroutineScope, el fallo de una hija sube al ámbito, que lo asume, cancela a las hermanas y relanza la excepción en el punto de la llamada. En un supervisorScope, el fallo de una hija se queda en esa hija: las hermanas no se enteran y el bloque sigue su curso.

flowchart TD
A[Hija falla] --> B{Tipo de ambito}
B -- coroutineScope --> C[El ambito asume el fallo]
C --> D[Cancela a las hermanas]
D --> E[Relanza en el punto de llamada]
B -- supervisorScope --> F[El ambito ignora el fallo]
F --> G[Las hermanas continuan]
G --> H[El error se atiende en la propia hija]

// Todo o nada: sin costes no hay informe
suspend fun informe(id: Id) = coroutineScope {
    val ventas = async { repo.ventas(id) }
    val costes = async { repo.costes(id) }
    Informe(ventas.await(), costes.await())
}

// Independientes: que fallen las que fallen, las demas valen
suspend fun refrescarTodo(ids: List<Id>) = supervisorScope {
    ids.forEach { id ->
        launch {
            runCatching { repo.refrescar(id) }
                .onFailure { registro.aviso(id, it) }
        }
    }
}

Hay tres precisiones sobre el supervisor que evitan la mayoría de los malentendidos. La primera es que el supervisor no atrapa el error: si la hija no lo trata, se pierde salvo que llegue a un manejador, y por eso bajo supervisor el tratamiento del error debe escribirse dentro de cada hija. La segunda es que la asimetría solo aplica a la relación directa con el ámbito supervisor; dentro de una hija que a su vez lanza nietas, el comportamiento vuelve a ser el corriente y un nieto que falle sí cancelará a sus hermanos. Y la tercera es que si el fallo ocurre en el propio bloque del supervisorScope, y no en una hija, el ámbito falla igual y cancela a todas, porque ese código es el ámbito mismo y no un subordinado.

Hay además un patrón intermedio que resuelve muchos casos sin necesidad de supervisor y que conviene considerar antes de recurrir a él: mantener el ámbito corriente y hacer que cada tarea capture su propio fallo devolviendo un resultado que lo represente. Con eso el árbol sigue siendo estrictamente estructurado, ninguna excepción escapa y la decisión sobre qué hacer con los fallos parciales se toma en un único sitio, con todos los resultados a la vista.

suspend fun consultarTodos(ids: List<Id>): List<Result<Dato>> = coroutineScope {
    ids.map { id ->
        async { runCatching { repo.consultar(id) } }
    }.awaitAll()
}

La diferencia entre esta versión y el supervisor no es de comportamiento observable sino de dónde vive la política. Aquí el fallo deja de ser una excepción y pasa a ser un dato, de modo que el sistema de tipos obliga a quien reciba la lista a decidir qué hace con los elementos fallidos; con un supervisor, en cambio, el fallo sigue siendo una excepción atendida dentro de cada hija y quien llama no se entera de que hubo problemas. La primera forma es preferible cuando el llamador tiene algo que decidir; la segunda, cuando las tareas son efectos y no hay nada que devolver.

Dónde se atiende el error de verdad

El elemento de contexto CoroutineExceptionHandler es el último recurso del sistema: se invoca cuando una excepción llega al final del árbol sin que nadie la haya tratado. Su regla de activación es estricta y no coincide con lo que la mayoría supone al colocarlo, de ahí que sea frecuente encontrarlo instalado en sitios donde no se ejecutará jamás.

Se ejecuta únicamente en la corrutina raíz de un ámbito, es decir, en una creada directamente sobre un CoroutineScope con launch, y solo cuando el fallo no tiene ya otro destino. No se ejecuta en una corrutina hija de un coroutineScope, porque su fallo sube al padre y termina relanzándose en el punto de la llamada, que es donde corresponde tratarlo con un try. Tampoco se ejecuta para un async, porque su excepción pertenece al valor y se entrega en el await. Y en un supervisorScope, una hija lanzada con launch sí cuenta como raíz a estos efectos, porque su fallo no sube a ninguna parte.

val manejador = CoroutineExceptionHandler { _, e ->
    registro.error("fallo no tratado", e)
}

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default + manejador)

scope.launch { puedeFallar() }        // el manejador si actua aqui

suspend fun operacion() = coroutineScope {
    launch(manejador) { puedeFallar() }   // inutil: el fallo sube al padre
}

Un criterio de elección

La pregunta que decide es si las hermanas comparten destino, y tiene traducción directa desde el dominio. Si el resultado de la operación es una composición de todas las partes, de modo que la ausencia de una la invalida, el destino es común y corresponde coroutineScope; ahorrar el trabajo de las hermanas cuando ya se sabe que el conjunto ha fracasado no es solo una optimización, es la única semántica coherente. Si cada tarea produce un efecto o un valor que se entrega por separado, y el usuario del sistema aceptaría con naturalidad que tres de cinco funcionaran, entonces el destino es individual y corresponde supervisorScope.

Conviene distinguir también entre el constructor y el elemento de contexto, porque se confunden y no son intercambiables. La función supervisorScope crea un ámbito local que dura lo que dure su bloque y espera a sus hijas antes de retornar, igual que su hermano corriente; es la herramienta para una operación concreta. El elemento SupervisorJob se usa al construir un CoroutineScope que se guarda como propiedad y vive mientras viva el componente, sin esperar a nadie porque nunca retorna. Usar el segundo dentro de una función suspend para simular el primero es un error frecuente y sus consecuencias son las ya conocidas: se pierde la espera y las tareas quedan huérfanas.

// Correcto para una operacion: ambito local que espera
suspend fun sincronizar(ids: List<Id>) = supervisorScope {
    ids.forEach { id -> launch { intentar(id) } }
}

// Correcto para un componente: ambito de larga vida que se cancela a mano
class Sesion {
    private val ambito = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    fun cerrar() = ambito.cancel()
}

Hay dos señales fiables de que la elección se ha hecho mal. Si al usar un supervisor aparecen bloques try vacíos o registros que nadie lee, es probable que las tareas sí compartieran destino y que se esté ocultando un fallo real en lugar de tolerarlo. Y si con un ámbito corriente una tarea marginal, como enviar una métrica, derriba una operación entera de negocio, la respuesta correcta no es cambiar el ámbito sino sacar esa tarea de la operación y darle un ámbito propio, porque nunca perteneció al mismo destino.