CKTIS / C++
std::coroutine_handle: accesso non proprietario a un frame di coroutine
std::coroutine_handle è un riferimento copiabile simile a un puntatore a un frame di coroutine e non ne gestisce autonomamente la durata.
Versione: C++23
Sintassi
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> di <coroutine> fa riferimento al frame di una coroutine sospesa e può esporne promise(). Un handle costruito per default o azzerato è nullo; la conversione a bool verifica soltanto la presenza di un indirizzo. Le copie indicano lo stesso frame senza proprietà condivisa.
Il template std::coroutine_handle non possiede il frame. Per un handle tipizzato, std::coroutine_handle::from_promise richiede un riferimento all’oggetto promise di una coroutine e ottiene un handle a quella coroutine, mentre std::coroutine_handle::promise restituisce un riferimento alla sua promise. std::coroutine_handle::done richiede una coroutine sospesa e verifica la sospensione finale; std::coroutine_handle::resume richiede una sospensione non finale, e std::coroutine_handle::destroy richiede una coroutine validamente sospesa e distrugge il frame.
resume() si può chiamare solo su una coroutine sospesa prima del punto finale di sospensione. done() richiede un frame sospeso valido e indica se è stata raggiunta la sospensione finale. Chiamare queste operazioni tramite un handle nullo, pendente o sospeso in modo errato causa comportamento indefinito.
destroy() distrugge un frame sospeso e ne libera la memoria; deve avvenire esattamente una volta se il frame non si autodistrugge. Dopo, tutte le copie pendono. L’esempio usa suspend_always all’inizio e alla fine e un proprietario RAII solo spostabile il cui distruttore chiama destroy().
Esempi
#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';
}
Risultato
0 body 1
std::coroutine_handle → 0 body 1