Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / C++

std::coroutine_handle: acceso no propietario a un marco de corrutina

std::coroutine_handle es una referencia copiable similar a un puntero hacia un marco de corrutina y no gestiona por sí sola su vida.

Versión: C++23

Sintaxis

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>, referencia el marco de una corrutina suspendida y puede exponer su promise(). Un handle construido por defecto o reiniciado es nulo; la conversión a bool solo prueba si guarda una dirección. Las copias apuntan al mismo marco sin compartir propiedad.

La plantilla std::coroutine_handle no posee el marco. Para un handle tipado, std::coroutine_handle::from_promise exige una referencia al objeto promise de una corrutina y obtiene un handle de esa corrutina, mientras std::coroutine_handle::promise devuelve una referencia a su promise. std::coroutine_handle::done exige una corrutina suspendida y comprueba la suspensión final; std::coroutine_handle::resume exige una suspensión no final, y std::coroutine_handle::destroy exige una corrutina suspendida válida y destruye el marco.

resume() solo puede llamarse para una corrutina suspendida antes de su punto de suspensión final. done() exige un marco suspendido válido e indica si se alcanzó la suspensión final. Llamar estas operaciones mediante un handle nulo, colgante o mal suspendido causa comportamiento indefinido.

destroy() destruye un marco suspendido y libera su almacenamiento; debe suceder exactamente una vez si el marco no se destruye solo. Después todas las copias quedan colgantes. El ejemplo usa suspend_always al inicio y al final y un propietario RAII solo movible cuyo destructor llama a destroy().

Ejemplos

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

Resultado

0
body
1

std::coroutine_handle → 0 body 1

Fuentes