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

CKTIS / C++

std::coroutine_handle : accès non propriétaire à une trame de coroutine

std::coroutine_handle est une référence copiable semblable à un pointeur vers une trame de coroutine et n’en gère pas seul la durée de vie.

Version : C++23

Syntaxe

template<class Promise = void>
struct coroutine_handle {
    static coroutine_handle from_promise(Promise&);
    constexpr explicit operator bool() const noexcept;
    bool done() const;
    void resume() const;
    void destroy() const;
    Promise& promise() const;
};

std::coroutine_handle<Promise> de <coroutine> désigne la trame d’une coroutine suspendue et peut exposer son promise(). Un handle construit par défaut ou réinitialisé est nul ; la conversion en bool teste seulement la présence d’une adresse. Les copies désignent la même trame sans partager de propriété.

Le modèle std::coroutine_handle ne possède pas la trame. Pour un handle typé, std::coroutine_handle::from_promise exige une référence vers l’objet promise d’une coroutine et obtient le handle de cette coroutine, tandis que std::coroutine_handle::promise renvoie une référence vers sa promise. std::coroutine_handle::done exige une coroutine suspendue et teste la suspension finale ; std::coroutine_handle::resume exige une suspension non finale, et std::coroutine_handle::destroy exige une coroutine valablement suspendue et détruit la trame.

resume() ne peut être appelé que pour une coroutine suspendue avant son point de suspension final. done() exige une trame suspendue valide et indique si la suspension finale est atteinte. Appeler ces opérations via un handle nul, pendant ou incorrectement suspendu entraîne un comportement indéfini.

destroy() détruit une trame suspendue et libère son stockage ; il doit être exécuté exactement une fois si la trame ne se détruit pas elle-même. Toutes les copies pendent ensuite. L’exemple emploie suspend_always au début et à la fin et un propriétaire RAII déplaçable seulement, dont le destructeur appelle destroy().

Exemples

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

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_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() { std::terminate(); }
    };

    Handle handle;
    explicit Task(Handle value) : handle(value) {}
    Task(const Task&) = delete;
    Task(Task&& other) noexcept : handle(std::exchange(other.handle, {})) {}
    ~Task() { if (handle) handle.destroy(); }
};

Task make_task() {
    std::cout << "body\n";
    co_return;
}

int main() {
    Task task = make_task();
    std::cout << task.handle.done() << '\n';
    task.handle.resume();
    std::cout << task.handle.done() << '\n';
}

Résultat

0
body
1

std::coroutine_handle → 0 body 1

Sources