Recomposed
Coroutines

L'arbre des coroutines : ce que Scope, Job et l'annulation signifient réellement

Oct 21, 2026 · 12 min read

L'arbre des coroutines : ce que Scope, Job et l'annulation signifient réellement

Ce qu'est réellement une coroutine

Une coroutine est une unité de travail qui peut se mettre en pause en plein milieu et reprendre plus tard, sans bloquer le thread sur lequel elle s'exécute. La fonction qui peut se mettre en pause est marquée suspend.

Appeler une fonction suspend ne s'exécute pas de bout en bout comme un appel de fonction normal. Au moment où elle n'a rien à faire pour l'instant (en attente d'IO, d'un delay(), d'une autre coroutine), elle rend le contrôle au dispatcher. Elle reprend exactement à cet endroit une fois que le résultat est prêt.

L'intuition

launch { } et async { } se lisent comme « lance une tâche en arrière-plan et continue ». C'est l'image que construisent la plupart des tutoriels, et elle est fausse d'une manière bien précise : elle traite une coroutine comme flottant librement, de la même façon qu'on lancerait un thread puis qu'on oublierait son existence.

  • Chaque coroutine démarre à l'intérieur d'un CoroutineScope, et ce scope est une limite sur la durée pendant laquelle la coroutine a le droit de vivre.
  • Chaque coroutine a un Job, un objet qui suit son état et sa position dans un arbre de coroutines parentes et enfants.
  • Annulez un parent, et chaque descendant de cet arbre est annulé aussi. Pas à cause d'une boucle d'annulation récursive traitée comme un cas spécial, mais parce que c'est ce qu'est l'arbre.

Pensez à launch/async moins comme « lancer une tâche » et plus comme « ajouter une branche à cet arbre ». Une longue liste de règles mémorisées séparément (pourquoi l'annulation se propage en cascade, pourquoi le crash d'un enfant peut entraîner ses frères et sœurs, pourquoi GlobalScope est dangereux) se réduit à une seule image : l'arbre.

FIG. 01
launch et async ne lancent pas des tâches indépendantes, chacun ajoute un Job enfant comme nouvelle branche sous le Job qui les a appelés

Chaque case ici est un Job. launch et async sont simplement deux façons différentes d'en ajouter un, avec une vraie différence : launch ne vous rend rien d'autre qu'un handle vers la branche elle-même, async vous rend un Deferred qui porte aussi le résultat final de la branche. Annulez Root, et A, A1, B, et B1 sont tous annulés avec lui, parce que ce ne sont pas des choses séparées qu'il faudrait traquer individuellement, ce sont simplement la partie de cet arbre qui se trouve en dessous.

Comment fonctionne réellement la suspension : une machine à états

Le compilateur Kotlin n'a aucune magie d'exécution pour mettre en pause une fonction en plein appel. Il réécrit une fonction suspend en une machine à états : chaque point de suspension devient un état numéroté, et les variables locales de la fonction sont dans une qui se souvient d'où reprendre.

suspend fun loadUser(id: String): User {
    val token = fetchToken()          // state 0, suspends here
    val profile = fetchProfile(token) // state 1, suspends here
    return profile.toUser()           // state 2, returns
}

Appeler loadUser ne bloque rien en attendant fetchToken. Elle rend une Continuation et renvoie le contrôle au dispatcher. Quand le token arrive, le dispatcher invoque cette continuation, qui reprend loadUser à l'état 1 avec token déjà restauré depuis l'endroit où il avait été stocké.

FIG. 02
loadUser se suspend à fetchToken, libérant le thread, et reprend via sa Continuation une fois le token arrivé

C'est aussi pourquoi l'annulation est coopérative, pas immédiate (plus de détails ci-dessous) : une coroutine ne peut être interrompue qu'à un point de suspension, parce que c'est le seul moment où la machine à états rend le contrôle à un ordonnanceur capable de vérifier quoi que ce soit.

Relier les API à base de callbacks à l'arbre : suspendCancellableCoroutine

Tous les points de suspension ne viennent pas de l'appel d'une autre fonction suspend. Android est plein d'API à base de callbacks (ActivityResultCaller, des SDK de type listener, tout ce qui se termine en invoquant un callback plutôt qu'en renvoyant une valeur) qui ne savent rien des coroutines. suspendCancellableCoroutine permet de transformer l'une d'elles en un vrai point de suspension plutôt qu'en un canal parallèle que l'arbre ne peut pas voir.

suspend fun awaitLocation(): Location = suspendCancellableCoroutine { continuation ->
    val listener = LocationListener { location -> continuation.resume(location) }
    locationProvider.requestLocation(listener)
 
    continuation.invokeOnCancellation {
        locationProvider.removeListener(listener)
    }
}

Là où la machine à états ci-dessus reçoit sa Continuation générée et câblée par le compilateur, suspendCancellableCoroutine vous remet cette Continuation directement. Vous la gardez à l'intérieur du lambda, vous déclenchez l'API à base de callback, et vous la reprenez manuellement une fois que le vrai callback s'exécute avec un résultat.

FIG. 03
Two ways awaitLocation can end: the listener fires first, or the parent cancels first and invokeOnCancellation tears the listener down instead

invokeOnCancellation est la partie qui relie vraiment tout cela à l'arbre. Supposons que le scope qui a appelé awaitLocation() soit annulé pendant qu'une demande de position est encore en attente. locationProvider n'en sait rien et continue d'appeler listener jusqu'à ce qu'on lui dise d'arrêter. Sans invokeOnCancellation, ce listener continue d'exister après que la coroutine qui l'a créé n'existe plus, une fuite de la même forme que la fuite GlobalScope plus loin dans cet article. Le gestionnaire d'annulation s'exécute exactement au moment où le parent s'annule, en retirant le listener avant qu'il puisse se déclencher à nouveau.

C'est ce qui fait qu'une API à base de callback ressemble à un nœud ordinaire de l'arbre plutôt qu'à une porte dérobée vers lui : l'annulation peut l'atteindre depuis un parent, de la même façon qu'elle atteint n'importe quel point de suspension généré par le compilateur.

Dispatchers : pourquoi un thread exécute plusieurs coroutines

Un Job dit quelle est la relation d'une coroutine avec les autres coroutines. Un CoroutineDispatcher dit quel thread, ou pool de threads, l'exécute réellement. Ce sont deux questions différentes, et les confondre est ce qui égare l'intuition « un thread ne peut faire qu'une chose à la fois ».

  • Une coroutine suspendue n'occupe aucun thread du tout. C'est une continuation posée sur le tas, en attente d'être reprise.
  • Un dispatcher n'a besoin d'un thread que pour les moments où une coroutine exécute activement du code, pas pour les moments où elle est suspendue.
  • Des milliers de coroutines peuvent être suspendues à la fois sur zéro thread. Seules celles qui s'exécutent activement ont chacune besoin d'un thread.

C'est pourquoi les coroutines sont peu coûteuses comparées aux threads. Un thread du système d'exploitation réserve sa propre pile d'appels à l'avance (généralement autour de 1 Mo sur la JVM), qu'il soit occupé ou inactif. Une coroutine suspendue n'est qu'un objet Continuation, généralement quelques dizaines d'octets, posé sur le tas jusqu'à ce que quelque chose le reprenne.

0 queued · 0 suspended · 1 thread
Speed
Dispatcher threadidle

Solid = holding the dispatcher thread. Faint = waiting its turn. Hollow = suspended, holding no thread at all. However many coroutines are running, only one is ever actually on the thread at once.

Ce n'est pas qu'un simple casse-tête d'ordonnancement abstrait. C'est ce même entrelacement sur un seul thread qui fait fonctionner une animation ordinaire de bouton pressé-maintenu :

val scope = rememberCoroutineScope()
val scale = remember { Animatable(1f) }
 
Modifier.pointerInput(Unit) {
    detectTapGestures(onPress = {
        scope.launch { scale.animateTo(1.2f) } // queued, doesn't run inline
        tryAwaitRelease()                      // suspends here, thread freed
        scope.launch { scale.animateTo(1f) }   // retargets the same Animatable
    })
}

scope.launch n'exécute pas l'animation de grossissement en ligne, il planifie un nouveau Job sur le dispatcher de rememberCoroutineScope() (le thread UI) et retourne immédiatement. tryAwaitRelease() se suspend alors, rendant le thread, ce qui est exactement ce qui permet aux propres points de suspension de l'animation de grossissement (withFrameNanos, en attente de la prochaine frame) d'avoir leur tour. Rien ici ne s'exécute en parallèle : la coroutine onPress et la coroutine d'animation se partagent un seul thread à tour de rôle, le même entrelacement que la démo ci-dessus, simplement avec un doigt sur l'écran au lieu d'un bouton nommé « Lancer une coroutine ».

Où l'arbre fuit : GlobalScope

class UserViewModel : ViewModel() {
    fun loadUser(id: String) {
        // Leak: this coroutine's parent is GlobalScope, which never gets
        // cancelled. It keeps running after the ViewModel is cleared,
        // holding a reference to it the whole time.
        GlobalScope.launch {
            val user = repository.fetchUser(id)
            _uiState.value = UiState.Loaded(user)
        }
    }
}
class UserViewModel : ViewModel() {
    fun loadUser(id: String) {
        // Fixed: viewModelScope's Job is a child of this ViewModel's
        // lifecycle. onCleared() cancels it, which cancels this launch
        // too, because it's actually in the tree.
        viewModelScope.launch {
            val user = repository.fetchUser(id)
            _uiState.value = UiState.Loaded(user)
        }
    }
}

GlobalScope n'est scopé à rien, et c'est exactement le problème. Il n'a pas de parent, donc rien dans le cycle de vie de votre application ne peut remonter pour l'annuler.

launch vs async : le timing des exceptions que personne ne maîtrise vraiment

L'affirmation courante est « launch lance immédiatement, async attend que vous appeliez .await() ». Ce n'est vrai qu'à moitié, et la moitié manquante est celle qui compte.

coroutineScope {
    launch {
        throw IllegalStateException("boom")
        // Propagates immediately: cancels this scope's other children
        // and rethrows once they've wound down.
    }
}
coroutineScope {
    val deferred = async {
        throw IllegalStateException("boom")
        // Still propagates immediately through the parent job, same as
        // launch above, because this async has a structured parent.
        // await() is never even reached.
    }
    deferred.await()
}
val deferred = GlobalScope.async {
    throw IllegalStateException("boom")
    // Only deferred here: this async has no structured parent to
    // propagate to, so the exception just sits in the Deferred until
    // something calls await() on it. Forget to call await(), and the
    // exception disappears silently.
}

La règle n'est pas « launch contre async ». C'est « est-ce que cette coroutine a un parent dans l'arbre ». Imbriqués dans un scope, les deux se propagent de la même façon : immédiatement, à travers l'arbre. Ce n'est que pour un async nu, sans parent, que le comportement « attendre .await() » apparaît, et c'est exactement la même cause profonde que la fuite GlobalScope ci-dessus : pas de parent signifie que rien ne se propage automatiquement.

L'essentiel

Ceci est la concurrence structurée : chaque coroutine a un parent, scopé à un CoroutineScope qui définit sa durée de vie. Un Job n'est pas qu'un simple handle, c'est la position de la coroutine dans cet arbre. L'annulation descend l'arbre (annulez un parent, chaque descendant s'annule), et l'échec le remonte (un échec non géré d'un enfant annule ses frères et sœurs et se propage au parent), à moins que quelque chose ne coupe délibérément l'un de ces liens.

Ailleurs : même principe fondamental, framework différent

  • La concurrence structurée de Swift : une Task lancée dans un TaskGroup est un enfant de ce groupe de la même façon. Annulez la Task parente et Task.isCancelled passe à true dans tout l'arbre, et les enfants d'un groupe sont annulés quand l'un d'eux lève une exception, la même forme de propagation que ci-dessus.
  • Trio de Python : littéralement l'endroit où le terme « concurrence structurée » a été inventé. La de Trio est le scope. Vous ne pouvez pas lancer une tâche sans en avoir une, et le bloc nursery ne se termine pas avant que chaque enfant qu'il a ouvert ait terminé, la même idée de limite de durée de vie qu'un CoroutineScope.
  • asyncio.TaskGroup de Python (3.11+) : ajouté spécifiquement pour apporter le modèle structuré de Trio dans asyncio, qui permettait auparavant de lancer asyncio.create_task() sans aucun parent, exactement le problème GlobalScope ci-dessus.
  • Go, en revanche, n'a aucune primitive de concurrence structurée dans le langage. Un simple go func() {}() est un GlobalScope.launch par défaut : rien ne le suit, rien ne l'annule automatiquement. errgroup et context.Context existent précisément comme correctif rajouté pour ne pas avoir d'arbre intégré.
  • Node/TypeScript est dans la même catégorie que Go. Une Promise n'a aucune annulation intégrée du tout, et Promise.all rejette dès qu'une promesse rejette sans annuler les autres. Elles continuent de s'exécuter, sans surveillance. AbortController/AbortSignal est l'analogue le plus proche d'un Job, mais c'est manuel : vous créez un signal et le transmettez explicitement à ce qui choisit de le vérifier. Rien ne le propage ni ne construit un arbre à partir de lui automatiquement.

Types de Job

Job n'est pas un comportement fixe unique, c'est une interface avec des variantes qui changent chacune une règle sur la façon dont l'arbre propage l'échec ou expose un contrôle manuel. La forme de l'arbre (parent/enfant, l'annulation descend) reste la même à travers toutes ces variantes.

Type de JobCréé parAnnule les frères et sœurs en cas d'échec ?Usage typique
JobPar défaut pour launch/async, coroutineScope { }OuiConcurrence structurée par défaut : « si une partie échoue, arrêter toute l'opération »
SupervisorJobSupervisorJob(), supervisorScope { }, viewModelScopeNon, seulement pour les enfants directsTravail parallèle indépendant sous un seul scope : « si une partie échoue, le reste doit continuer »
CompletableJobCe que les fonctions factory Job()/SupervisorJob() retournent réellementIdentique à la base qu'elle enveloppeMarquer manuellement un job comme terminé via complete()/completeExceptionally(), orthogonal à la distinction supervisor

La colonne « enfants directs seulement » est le détail qui piège les gens : la protection d'un SupervisorJob ne s'étend pas au-delà de ses enfants immédiats. Si l'un de ces enfants lance (launch) ses propres petits-enfants, l'échec d'un petit-enfant se propage toujours normalement jusqu'à son parent immédiat (l'enfant direct) et annule la propre sous-branche de cet enfant. Le supervisor empêche seulement l'échec de remonter au-delà de lui-même.

Cas limites

L'annulation est coopérative, pas immédiate

Appeler job.cancel() n'interrompt pas le code en plein milieu d'une instruction comme le fait tuer un thread. Cela active un drapeau qui est vérifié aux points de suspension, c'est pourquoi une boucle occupée sans delay(), sans yield(), sans aucun appel suspendant à l'intérieur, continue simplement de s'exécuter après avoir été « annulée » :

val job = launch {
    while (true) {
        // No suspension point in this loop: isActive never gets checked
        // automatically, so cancel() has nothing to interrupt.
        computeSomething()
    }
}
job.cancel() // the loop above keeps running forever

La solution est de vérifier isActive, ou d'appeler ensureActive(), à l'intérieur de la boucle. Cela donne à l'annulation un point où elle peut réellement prendre effet.

CancellationException ne se propage pas comme un échec

val job = launch {
    try {
        doWork()
    } catch (e: Exception) {
        log.error("doWork failed", e) // also catches CancellationException
    }
}
job.cancel()
// doWork() keeps running past the catch block: cancel() threw
// CancellationException to unwind the coroutine, but this catch
// swallowed it like any other Exception, so nothing actually stops.

Annuler une coroutine ne fait pas que lever un drapeau. Cela lève une CancellationException au point de suspension actuel de la coroutine, le même mécanisme qu'un véritable échec utilise pour dérouler la pile d'appels.

La différence est ce qui se passe une fois que cette exception atteint le Job :

  • Le mécanisme des coroutines vérifie spécifiquement la présence de CancellationException et la traite comme « cette branche s'est terminée parce qu'on lui a dit de le faire », pas comme un échec.
  • Elle n'est jamais signalée à un CoroutineExceptionHandler.
  • Contrairement aux échecs de la section launch/async ci-dessus, elle n'annule pas les frères et sœurs et ne se propage pas au parent comme une erreur.

C'est pourquoi intercepter Exception de façon large à l'intérieur d'une coroutine est un vrai bug, pas seulement du mauvais style. CancellationException est un sous-type d'Exception, donc une capture générale l'avale avec tout le reste, et la coroutine continue de s'exécuter après avoir été censément annulée.

La solution est d'intercepter un type plus restreint, ou de relever l'exception quand celle interceptée est une CancellationException :

val job = launch {
    try {
        doWork()
    } catch (e: CancellationException) {
        throw e // let cancellation keep propagating
    } catch (e: Exception) {
        log.error("doWork failed", e)
    }
}
job.cancel()
// The CancellationException branch rethrows immediately, so cancellation
// still unwinds the coroutine. A real failure from doWork() still falls
// through to the logging branch below it, same as before.

withContext n'ajoute pas de branche

withContext prend un lambda suspendant tout comme launch/async, ce qu'il est tentant de lire comme le lancement d'une nouvelle branche aussi. Ce n'est pas le cas.

suspend fun loadUser(id: String): User {
    val user = withContext(Dispatchers.IO) {
        repository.fetchUserBlocking(id) // runs on IO, caller suspends here
    }
    // Reached only once the block above finishes. Same coroutine, same
    // Job as loadUser itself, just back on the original dispatcher.
    log.info("loaded $user")
    return user
}

withContext ne renvoie ni Job, ni Deferred, rien à quoi se raccrocher. Il suspend la coroutine appelante, change de dispatcher (ou tout autre élément de contexte que vous avez passé) pendant la durée du bloc, puis reprend avec le résultat une fois ce bloc terminé. Rien ne s'exécute en parallèle du point d'appel, il n'y a pas de seconde branche à suivre, c'est le même nœud de l'arbre pendant toute la durée. Annulez le parent pendant qu'une coroutine se trouve à l'intérieur d'un bloc withContext, et ce bloc est annulé avec lui, comme n'importe quel autre point de suspension, parce qu'il n'a jamais été un nœud séparé pour commencer.

runBlocking est un pont, pas un membre de l'arbre

Comme withContext ci-dessus, runBlocking n'ajoute pas non plus de branche à un arbre existant, mais pour la raison opposée : il n'est pas censé correspondre à l'image habituelle. Il existe pour appeler du code suspendant depuis du code non suspendant (main(), un test JVM, un callback qui n'est pas lui-même une coroutine), et il le fait en bloquant le thread appelant jusqu'à ce que le corps de sa coroutine se termine. Imbriquez runBlocking quelque part en profondeur dans du code Android en production et vous avez réintroduit exactement le blocage de thread que le reste de ce système existe pour éviter.

Usage concret

  • viewModelScope / lifecycleScope : les scopes prêts à l'emploi d'Android liés à la durée de vie d'un ViewModel ou d'un LifecycleOwner, de sorte que vous obtenez l'arbre gratuitement au lieu de gérer un Job à la main.
  • Collecte de Flow : flow.collect { } s'exécute à l'intérieur du scope qui l'a appelé, donc annuler ce scope arrête aussi la collecte, le même arbre.
  • CoroutineWorker de WorkManager : la bibliothèque possède un scope par demande de travail et l'annule si le travail est annulé ou dépasse le délai, donc doWork() n'a pas besoin de gérer son propre Job.

Une coroutine ne flotte jamais librement. C'est toujours un nœud dans un arbre, et l'arbre, pas la coroutine elle-même, est la chose que vous gérez réellement.

Keep reading

Related reads

Recevez les nouveaux articles par e-mail