Baza znanjaIzpitno središče
SLSlovenščina
Izberi jezik13

CKTIS / C++

std::coroutine_handle: nelastniški dostop do okvira korutine

std::coroutine_handle je kopirljiva kazalcu podobna referenca na okvir korutine in sama ne upravlja njegove življenjske dobe.

Različica: C++23

Sintaksa

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> iz <coroutine> se nanaša na okvir ustavljene korutine in lahko izpostavi njen promise(). Privzeto ustvarjen ali ponastavljen handle je prazen; pretvorba v bool le preveri shranjeni naslov. Kopije kažejo na isti okvir brez skupnega lastništva.

Predloga std::coroutine_handle ni lastnica okvira. Za tipiziran handle std::coroutine_handle::from_promise zahteva referenco na promise objekt korutine in pridobi handle te korutine, std::coroutine_handle::promise pa vrne referenco na njen promise. std::coroutine_handle::done zahteva ustavljeno korutino in preveri končno ustavitev; std::coroutine_handle::resume zahteva nekončno ustavitev, std::coroutine_handle::destroy pa veljavno ustavljeno korutino in uniči okvir.

resume() se sme poklicati le za korutino, ustavljeno pred končno točko ustavitve. done() zahteva veljaven ustavljen okvir in pove, ali je končna ustavitev dosežena. Klic prek praznega, visečega ali napačno ustavljenega handle povzroči nedoločeno vedenje.

destroy() uniči ustavljen okvir in sprosti pomnilnik; če se okvir ne uniči sam, se mora to zgoditi natanko enkrat. Vse kopije nato obvisijo. Primer uporabi suspend_always na začetku in koncu ter samo premakljivega lastnika RAII, katerega destruktor pokliče destroy().

Primeri

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

Rezultat

0
body
1

std::coroutine_handle → 0 body 1

Viri