CKTIS / C++
std::coroutine_handle: niet-bezittende toegang tot een coroutineframe
std::coroutine_handle is een kopieerbare pointerachtige verwijzing naar een coroutineframe en beheert de levensduur daarvan niet zelf.
Versie: C++23
Syntax
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> uit <coroutine> verwijst naar het frame van een gesuspendeerde coroutine en kan diens promise() tonen. Een standaardgeconstrueerde of gewiste handle is null; conversie naar bool test alleen of een adres is opgeslagen. Kopieën verwijzen naar hetzelfde frame zonder gedeeld eigendom.
De template std::coroutine_handle bezit het frame niet. Voor een getypeerde handle vereist std::coroutine_handle::from_promise een verwijzing naar het promise-object van een coroutine en verkrijgt daarmee een handle naar die coroutine; std::coroutine_handle::promise retourneert een verwijzing naar die promise. std::coroutine_handle::done vereist een gesuspendeerde coroutine en test op final suspend; std::coroutine_handle::resume vereist een niet-finale suspensie, en std::coroutine_handle::destroy vereist een geldig gesuspendeerde coroutine en vernietigt het frame.
resume() mag alleen worden aangeroepen voor een coroutine die vóór het laatste suspensiepunt is gesuspendeerd. done() vereist een geldig gesuspendeerd frame en meldt of final suspend is bereikt. Deze operaties via een null, hangende of verkeerd gesuspendeerde handle aanroepen veroorzaakt ongedefinieerd gedrag.
destroy() vernietigt een gesuspendeerd frame en geeft de opslag vrij; dit moet precies eenmaal gebeuren als het frame zichzelf niet vernietigt. Alle kopieën hangen daarna. Het voorbeeld gebruikt suspend_always aan begin en einde en een alleen-verplaatsbare RAII-eigenaar wiens destructor destroy() aanroept.
Voorbeelden
#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';
}
Resultaat
0 body 1
std::coroutine_handle → 0 body 1