suspend function : définition, syntaxe et fonctionnement dans les coroutines

Qu'est-ce qu'une suspend function en Kotlin ?

Suspend function est une fonction déclarée avec le mot-clé suspend qui peut suspendre l'exécution à un ou plusieurs points sans bloquer le thread. Chaque appel à une fonction suspend à l'intérieur d'une autre fonction suspend est un point de suspension potentiel.

suspend fun fetchUserData(): User {
    val response = httpClient.get("/user")
    return parser.parse(response)
}

Le compilateur Kotlin traduit une telle fonction en machine d'état. Chaque point de suspension (un appel à une autre fonction suspend) devient un état (label). Le thread actuel est libéré entre les états, et une fois l'opération attendue terminée, l'exécution reprend à partir de l'état suivant.

Historique

Les fonctions suspend sont apparues dans Kotlin 1.3 (2018) avec les coroutines en tant que fonctionnalité expérimentale et sont devenues stables dans Kotlin 1.5 (2021). Avant cela, l'asynchronisme en Kotlin/Java était réalisé via des callbacks, RxJava et CompletableFuture. Les fonctions suspend ont offert une alternative avec une syntaxe linéaire et une gestion automatique des threads.

Comment fonctionnent les fonctions suspend : Continuation et machine d'état

Comprendre le fonctionnement interne des fonctions suspend est la clé pour travailler correctement avec les coroutines. Contrairement aux fonctions classiques, chaque fonction suspend est compilée en une classe avec l'interface Continuation.

Continuation — le paramètre caché

Le compilateur Kotlin ajoute un paramètre de type Continuation à la fin de chaque liste de paramètres d'une fonction suspend. Continuation contient :

• context — CoroutineContext (dispatcher, job, éléments de contexte)
• resumeWith — méthode pour reprendre l'exécution avec un résultat ou une exception
• label — index de l'état actuel dans la machine d'état

Exemple de machine d'état

Supposons que nous ayons une fonction suspend avec deux appels à d'autres fonctions suspend :

suspend fun process() {
    val a = stepOne()
    val b = stepTwo(a)
    println(b)
}

Le compilateur la transforme en une machine d'état avec des étiquettes :

// Simplified generated code representation
fun process(cont: Continuation<Unit>): Any? {
    val cont = cont as ProcessContinuation
    when (cont.label) {
        0 -> {
            cont.label = 1
            if (stepOne(cont) == COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
        }
        1 -> {
            cont.label = 2
            val a = cont.result as TypeA
            if (stepTwo(a, cont) == COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
        }
        2 -> {
            println(cont.result)
            Unit
        }
    }
}

Observation clé : si la fonction retourne COROUTINE_SUSPENDED, le thread actuel est libéré. Lorsque l'opération asynchrone se termine, Continuation.resumeWith est appelé et la machine d'état continue à partir de l'étiquette suivante.

Syntaxe des fonctions suspend : déclaration et invocation

Déclarer une fonction suspend n'est pas différent d'une fonction classique, sauf pour le mot-clé suspend avant fun. Il y a seulement une restriction : une fonction suspend ne peut être appelée que depuis une coroutine ou une autre fonction suspend.

Déclaration de base

suspend fun delayAndReturn(ms: Long): String {
    delay(ms)
    return "Done after ${ms}ms"
}

Dans cet exemple, delay est aussi une fonction suspend qui suspend la coroutine pendant le nombre spécifié de millisecondes sans bloquer le thread. Après le délai, l'exécution reprend.

Appel depuis une coroutine

fun main() = runBlocking {
    val result = delayAndReturn(1000)
    println(result)
}

runBlocking crée un pont entre le monde classique et les coroutines. À l'intérieur du lambda, n'importe quelle fonction suspend peut être appelée.

Lambdas suspend et types fonctionnels

Kotlin prend en charge les versions suspend des types fonctionnels — suspend () -> T et suspend (A) -> B. Cela permet de passer des lambdas asynchrones aux fonctions d'ordre supérieur :

suspend fun  withRetry(
    retries: Int = 3,
    block: suspend () -> T
): T {
    repeat(retries - 1) {
        try { return block() }
        catch (_: Exception) { delay(100) }
    }
    return block()
}

La fonction withRetry prend un lambda suspend et réessaie son exécution en cas d'erreur. C'est un modèle typique pour les requêtes réseau avec tentatives.

Différences entre fonctions suspend et fonctions classiques

Les différences entre les fonctions suspend et classiques vont au-delà de la simple ajout d'un modificateur. Examinons les distinctions principales.

Pourquoi les fonctions suspend ne peuvent pas être appelées depuis des fonctions classiques

Une fonction classique n'a pas de Continuation — elle n'a nulle part où sauvegarder l'état et rien pour reprendre l'exécution. Si vous devez appeler une fonction suspend depuis une fonction classique, utilisez runBlocking (pour les tests) ou CoroutineScope.launch (pour la production avec conscience du cycle de vie).

Exemples de fonctions suspend sous Android

Examinons trois scénarios réels d'utilisation des fonctions suspend dans les applications Android avec Kotlin.

Exemple 1 : Room DAO avec requêtes suspend

Room prend en charge les fonctions suspend directement — la requête est exécutée automatiquement sur un thread d'arrière-plan :

@Dao
interface UserDao {
    @Query("SELECT * FROM users WHERE id = :id")
    suspend fun getUser(id: Int): User?

    @Insert
    suspend fun insertUser(user: User)
}

Room utilise en interne Dispatchers.IO pour exécuter la requête, et le résultat est retourné sur le dispatcher où la fonction suspend a été appelée.

Exemple 2 : Composition de fonctions suspend pour le chargement d'écran

class ProfileViewModel : ViewModel() {
    private val repo = ProfileRepository()

    fun loadProfile(id: String) {
        viewModelScope.launch {
            val profile = repo.getProfile(id)
            _profile.value = profile
        }
    }
}

ViewModelScope.launch crée une coroutine, à l'intérieur de laquelle la fonction suspend getProfile est appelée. Après avoir obtenu le résultat, l'interface utilisateur est mise à jour sur le thread principal.

Exemple 3 : Étapes asynchrones séquentielles

suspend fun placeOrder(cart: Cart): OrderResult {
    val validated = validateCart(cart)
    val payment = processPayment(validated)
    val receipt = sendReceipt(payment)
    return receipt
}

Trois fonctions suspend s'exécutent séquentiellement. À chaque étape, la coroutine peut se suspendre sans bloquer le thread. Si une étape lève une exception, les étapes restantes ne s'exécutent pas, protégeant contre des états de commande incorrects.

Erreurs courantes avec les fonctions suspend

Même les développeurs Kotlin expérimentés commettent des erreurs lors de la conception de fonctions suspend. Examinons les plus courantes.

Erreur 1 : Appels bloquants dans suspend

Une fonction suspend ne rend pas le code automatiquement asynchrone. Thread.sleep(), InputStream.read() et autres appels bloquants continueront de bloquer le thread. Utilisez withContext(Dispatchers.IO) pour encapsuler les opérations bloquantes.

Erreur 2 : Créer des fonctions suspend inutilement

Si une fonction n'appelle pas d'autres fonctions suspend et n'effectue pas d'opérations asynchrones — le modificateur suspend est redondant. Il ajoute une surcharge à la machine d'état et restreint le contexte d'appel. Ne rendez une fonction suspend que lorsqu'elle se suspend réellement.

Erreur 3 : Ignorer CancellationException

Lorsqu'une coroutine est annulée, les fonctions suspend lancent CancellationException. Ne l'attrapez pas sans réfléchir — vous privez le code appelant de la capacité à terminer correctement l'annulation. Si vous devez effectuer une opération de finalisation, utilisez un bloc finally et NonCancellable.

suspend fun safeOperation() {
    try {
        doWork()
    } finally {
        withContext(NonCancellable) {
            cleanup()
        }
    }
}

Le bloc finally s'exécute toujours, y compris lors de l'annulation, et NonCancellable garantit que le nettoyage ne sera pas interrompu.

Erreur 4 : Appeler des fonctions suspend depuis des callbacks

Vous ne pouvez pas appeler une fonction suspend directement depuis un callback sans créer une coroutine. Utilisez suspendCoroutine ou suspendCancellableCoroutine pour adapter le style callback aux coroutines.