Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C++

std::coroutine_handle: acesso não proprietário a uma frame de corrotina

std::coroutine_handle é uma referência copiável semelhante a um ponteiro para uma frame de corrotina e não gere sozinha o seu tempo de vida.

Versão: C++23

Sintaxe

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>, refere a frame de uma corrotina suspensa e pode expor a sua promise(). Um handle construído por predefinição ou reposto é nulo; a conversão para bool testa apenas se existe endereço. As cópias referem a mesma frame sem partilhar propriedade.

O template std::coroutine_handle não possui a frame. Para um handle tipado, std::coroutine_handle::from_promise exige uma referência ao objeto promise de uma corrotina e obtém um handle para essa corrotina, enquanto std::coroutine_handle::promise devolve uma referência à sua promise. std::coroutine_handle::done exige uma corrotina suspensa e testa a suspensão final; std::coroutine_handle::resume exige uma suspensão não final, e std::coroutine_handle::destroy exige uma corrotina validamente suspensa e destrói a frame.

resume() só pode ser chamado numa corrotina suspensa antes do ponto de suspensão final. done() exige uma frame suspensa válida e indica se a suspensão final foi atingida. Chamar estas operações por um handle nulo, pendente ou suspenso incorretamente causa comportamento indefinido.

destroy() destrói uma frame suspensa e liberta a sua memória; deve acontecer exatamente uma vez se a frame não se destruir sozinha. Depois, todas as cópias ficam pendentes. O exemplo usa suspend_always no início e fim e um proprietário RAII apenas movível cujo destrutor chama destroy().

Exemplos

#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

Fontes