Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / C++

co_await — attendre dans une coroutine

L’expression co_await utilise le protocole d’awaiter pour éventuellement suspendre une coroutine, puis obtenir un résultat. Elle ne démarre pas elle-même de thread et ne fournit pas de mécanisme de planification ; la reprise doit être organisée par l’implémentation utilisée.

Version : C++23; repository compiler flag, production runtime not attested

Syntaxe

co_await cast-expression

co_await expression marque un point de suspension possible d’une coroutine, et non une attente bloquante d’un thread. La présence d’une telle expression dans le corps d’une fonction en fait une coroutine. Le type de son objet promise est déterminé par std::coroutine_traits, qui doit fournir un promise_type approprié pour le type de retour et les types des paramètres de la coroutine (y compris le paramètre objet pour une fonction membre non statique). Le type de retour lui-même n’a pas besoin de contenir un promise_type imbriqué. L’opérateur ne crée à lui seul ni thread ni ordonnanceur.

Pour un co_await explicite, si la recherche du nom await_transform dans le type de l’objet promise trouve une déclaration, l’awaitable est le résultat de l’appel à await_transform sur cet objet avec l’opérande comme argument. Sinon, l’awaitable est l’opérande d’origine. Si la résolution de surcharge sélectionne un operator co_await pour l’awaitable, le résultat de l’appel sert d’awaiter. L’awaitable lui-même ne sert d’awaiter, après transformation le cas échéant, que si l’ensemble des candidats pour operator co_await est vide. Si cet ensemble n’est pas vide mais ne contient aucune fonction viable, l’expression co_await est mal formée. L’awaiter fournit await_ready(), await_suspend(h) et await_resume(). L’expression a le type et la catégorie de valeur du résultat de await_resume().

Le résultat de await_ready() fait l’objet d’une conversion contextuelle en bool. Si cette conversion donne true, la coroutine n’est pas suspendue. C’est notamment le cas si le résultat est un objet de type classe dont l’explicit operator bool() renvoie true. Si la conversion donne false, la coroutine est suspendue et await_suspend(h) est appelé. Si await_suspend a pour type de retour void, la fin de l’appel ne déclenche pas à elle seule la reprise de la coroutine par le mécanisme de co_await. Toutefois, await_suspend peut reprendre la coroutine directement ou faire en sorte qu’un autre thread la reprenne, même avant la fin de l’appel. Un résultat de type bool égal à false entraîne la reprise immédiate de la coroutine ; le renvoi d’un handle de coroutine transfère l’exécution à la coroutine indiquée. await_resume() fournit le résultat lorsque l’exécution reprend.

L’exemple utilise std::suspend_always : run() affiche start et rend le contrôle ; resume() lui permet d’afficher resumed. final_suspend() laisse le frame suspendu afin que le destructeur de Task puisse le libérer. Ne reprenez jamais une coroutine à son point de suspension final ; les objets utilisés après la reprise doivent toujours exister.

Cette entrée concerne C++23 ; le site fourni publie un brouillon en évolution, et non un texte C++23 figé. La compatibilité avec l’environnement d’exécution de production n’est pas attestée.

Exemples

#include <coroutine>
#include <exception>
#include <iostream>

struct Task {
    struct promise_type;
    using Handle = std::coroutine_handle<promise_type>;

    struct promise_type {
        Task get_return_object() {
            return Task{Handle::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept { std::terminate(); }
    };

    Handle handle;
    explicit Task(Handle h) noexcept : handle(h) {}
    Task(const Task&) = delete;
    Task& operator=(const Task&) = delete;
    ~Task() { handle.destroy(); }
};

Task run() {
    std::cout << "start\n";
    co_await std::suspend_always{};
    std::cout << "resumed\n";
}

int main() {
    auto task = run();
    std::cout << "caller\n";
    task.handle.resume();
}

Résultat

start
caller
resumed

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources