Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C++

std::coroutine_handle: a non-owning handle to a coroutine frame

std::coroutine_handle is a copyable pointer-like reference to a coroutine frame and does not manage that frame’s lifetime by itself.

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> from <coroutine> refers to a suspended coroutine frame and can expose its promise(). A default-constructed or reset handle is null, and conversion to bool only tests whether an address is stored. Handle copies refer to the same frame and do not share ownership.

The std::coroutine_handle template does not own the frame. For a typed handle, std::coroutine_handle::from_promise requires a reference to a coroutine’s promise object and obtains a handle to that coroutine, while std::coroutine_handle::promise returns a reference to its promise. std::coroutine_handle::done requires a suspended coroutine and tests for final suspension; std::coroutine_handle::resume requires a non-final suspension, and std::coroutine_handle::destroy requires a valid suspended coroutine and destroys the frame.

resume() may be called only for a coroutine suspended before its final suspend point; done() requires a valid suspended frame and reports whether final suspend has been reached. Calling these operations through a null, dangling, or improperly suspended handle causes undefined behavior.

destroy() destroys a suspended frame and releases its storage; it must happen exactly once when the frame does not destroy itself. All copied handles dangle afterward. The example uses suspend_always initially and finally and a move-only RAII owner whose destructor calls destroy().

Examples

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

Result

0
body
1

std::coroutine_handle → 0 body 1

Sources