Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / C++

std::coroutine_handle: nevlastnící přístup k rámci korutiny

std::coroutine_handle je kopírovatelný ukazatelový odkaz na rámec korutiny a sám jeho životnost nespravuje.

Verze: 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> z <coroutine> odkazuje na rámec pozastavené korutiny a může zpřístupnit její promise(). Výchozí nebo vynulovaný handle je prázdný; převod na bool pouze testuje uloženou adresu. Kopie odkazují na stejný rámec bez sdíleného vlastnictví.

Šablona std::coroutine_handle rámec nevlastní. Pro typovaný handle vyžaduje std::coroutine_handle::from_promise odkaz na promise objekt korutiny a získá handle této korutiny, zatímco std::coroutine_handle::promise vrací odkaz na její promise. std::coroutine_handle::done vyžaduje pozastavenou korutinu a testuje konečné pozastavení; std::coroutine_handle::resume vyžaduje jiné než konečné pozastavení a std::coroutine_handle::destroy vyžaduje platně pozastavenou korutinu a zničí rámec.

resume() lze volat jen pro korutinu pozastavenou před konečným bodem pozastavení. done() vyžaduje platný pozastavený rámec a hlásí dosažení konečného pozastavení. Volání přes prázdný, visící nebo nesprávně pozastavený handle vede k nedefinovanému chování.

destroy() zničí pozastavený rámec a uvolní jeho paměť; pokud se rámec nezničí sám, musí se to stát právě jednou. Všechny kopie pak visí. Příklad používá suspend_always na začátku i konci a pouze přesunutelného vlastníka RAII, jehož destruktor volá destroy().

Příklady

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

Výsledek

0
body
1

std::coroutine_handle → 0 body 1

Zdroje