Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / C++

std::coroutine_handle: accesso non proprietario a un frame di coroutine

std::coroutine_handle è un riferimento copiabile simile a un puntatore a un frame di coroutine e non ne gestisce autonomamente la durata.

Versione: C++23

Sintassi

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> di <coroutine> fa riferimento al frame di una coroutine sospesa e può esporne promise(). Un handle costruito per default o azzerato è nullo; la conversione a bool verifica soltanto la presenza di un indirizzo. Le copie indicano lo stesso frame senza proprietà condivisa.

Il template std::coroutine_handle non possiede il frame. Per un handle tipizzato, std::coroutine_handle::from_promise richiede un riferimento all’oggetto promise di una coroutine e ottiene un handle a quella coroutine, mentre std::coroutine_handle::promise restituisce un riferimento alla sua promise. std::coroutine_handle::done richiede una coroutine sospesa e verifica la sospensione finale; std::coroutine_handle::resume richiede una sospensione non finale, e std::coroutine_handle::destroy richiede una coroutine validamente sospesa e distrugge il frame.

resume() si può chiamare solo su una coroutine sospesa prima del punto finale di sospensione. done() richiede un frame sospeso valido e indica se è stata raggiunta la sospensione finale. Chiamare queste operazioni tramite un handle nullo, pendente o sospeso in modo errato causa comportamento indefinito.

destroy() distrugge un frame sospeso e ne libera la memoria; deve avvenire esattamente una volta se il frame non si autodistrugge. Dopo, tutte le copie pendono. L’esempio usa suspend_always all’inizio e alla fine e un proprietario RAII solo spostabile il cui distruttore chiama destroy().

Esempi

#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';
}

Risultato

0
body
1

std::coroutine_handle → 0 body 1

Fonti