CKTIS / C++
std::coroutine_handle: nieposiadający uchwyt do ramki korutyny
std::coroutine_handle jest kopiowalnym, wskaźnikopodobnym odwołaniem do ramki korutyny i sam nie zarządza jej czasem życia.
Wersja: C++23
Składnia
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> wskazuje ramkę zawieszonej korutyny i może udostępnić jej promise(). Domyślny lub wyzerowany uchwyt jest pusty, a konwersja do bool sprawdza jedynie, czy przechowuje adres. Kopie uchwytu odnoszą się do tej samej ramki i nie współdzielą własności.
Szablon std::coroutine_handle sam nie posiada ramki. Dla uchwytu typowanego std::coroutine_handle::from_promise wymaga referencji do obiektu promise należącego do korutyny i tworzy uchwyt do tej korutyny, a std::coroutine_handle::promise zwraca referencję do jej promise. std::coroutine_handle::done wymaga zawieszonej korutyny i sprawdza końcowe zawieszenie; std::coroutine_handle::resume wymaga zawieszenia innego niż końcowe, a std::coroutine_handle::destroy — prawidłowo zawieszonej korutyny — niszczy ramkę.
resume() wolno wywołać tylko dla korutyny zawieszonej przed końcowym punktem zawieszenia; done() wymaga prawidłowo zawieszonej ramki i informuje, czy osiągnięto końcowe zawieszenie. Wywołanie tych operacji na pustym, wiszącym lub niewłaściwie zawieszonym uchwycie prowadzi do niezdefiniowanego zachowania.
destroy() niszczy zawieszoną ramkę i zwalnia jej pamięć; trzeba wykonać je dokładnie raz, jeśli ramka nie niszczy się automatycznie. Po zniszczeniu wszystkie kopie uchwytu wiszą. Przykład używa suspend_always na początku i końcu oraz przenoszalnego właściciela RAII, który w destruktorze wywołuje destroy().
Przykłady
#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';
}
Wynik
0 body 1
std::coroutine_handle → 0 body 1