CKTIS / C++
std::coroutine_handle: nicht besitzender Zugriff auf einen Koroutinenrahmen
std::coroutine_handle ist eine kopierbare zeigerartige Referenz auf einen Koroutinenrahmen und verwaltet dessen Lebensdauer nicht selbst.
Version: 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> aus <coroutine> verweist auf den Rahmen einer angehaltenen Koroutine und kann deren promise() liefern. Ein standardkonstruierter oder zurückgesetzter Handle ist null; die Umwandlung in bool prüft nur eine gespeicherte Adresse. Kopien verweisen auf denselben Rahmen und teilen kein Eigentum.
Das Template std::coroutine_handle besitzt den Rahmen nicht. Bei einem typisierten Handle verlangt std::coroutine_handle::from_promise eine Referenz auf das Promise-Objekt einer Koroutine und gewinnt daraus deren Handle; std::coroutine_handle::promise liefert eine Referenz auf dieses Promise. std::coroutine_handle::done verlangt eine angehaltene Koroutine und prüft auf den letzten Suspend-Punkt; std::coroutine_handle::resume verlangt eine nicht endgültige Suspendierung, und std::coroutine_handle::destroy verlangt eine gültig angehaltene Koroutine und zerstört den Rahmen.
resume() darf nur bei einer vor dem letzten Suspend-Punkt angehaltenen Koroutine aufgerufen werden. done() verlangt einen gültigen angehaltenen Rahmen und meldet das Erreichen des letzten Suspend-Punkts. Aufruf über einen nullen, hängenden oder unpassend angehaltenen Handle ist undefiniertes Verhalten.
destroy() zerstört einen angehaltenen Rahmen und gibt seinen Speicher frei; wenn er sich nicht selbst zerstört, muss dies genau einmal geschehen. Danach hängen alle Handle-Kopien. Das Beispiel nutzt anfangs und am Ende suspend_always sowie einen nur verschiebbaren RAII-Besitzer, dessen Destruktor destroy() aufruft.
Beispiele
#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';
}
Ergebnis
0 body 1
std::coroutine_handle → 0 body 1