cpp-coroutines

C++20 coroutines

A coroutine is a function whose execution suspends and resumes while its frame survives on the heap. The language provides the keywords; the library author provides promise_type, which decides what suspension and return mean.

Contract

Field	Bound contract
Trigger	The task writes or reviews co_await, co_yield, or co_return code, implements a promise_type, explains the coroutine frame, or debugs a suspended coroutine.
Authority	Read-only. The skill explains mechanics and drafts coroutine types; edits land through the normal coding path. No remote mutation.
Side effect	None.
Done	The drafted coroutine type compiles against the project standard, or the coroutine under debug is located and its promise state read.

Inputs

• The coroutine code or the behavior wanted: required.
• The toolchain and standard level: required. C++20 keywords with a C++23 library where <generator> is wanted; current GCC and Clang ship both.
• A debugger session: required only for the debugging path.

Procedure

1. Recognize the three keywords and what they demand. A function containing any of them is a coroutine, and its return type must carry a promise_type. Done when: every coroutine in the source has a coroutine-shaped return type.

co_return value;               // return and finish
co_yield value;                // produce a value, suspend
auto r = co_await awaitable;   // suspend until awaitable completes

1. Draft a lazy Task when only the final result matters. initial_suspend returns suspend_always so the body runs only on resume(), and final_suspend is noexcept by rule. The owner destroys the handle exactly once. Done when: the type owns its handle, destroys it in the destructor, and propagates the exception.

#include <coroutine>
#include <exception>
#include <optional>
#include <utility>

template <typename T>
struct Task {
    struct promise_type {
        std::optional<T> value;
        std::exception_ptr exception;

        Task get_return_object() {
            return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_always initial_suspend() { return {}; }            // lazy start
        std::suspend_always final_suspend() noexcept { return {}; }     // must be noexcept
        void return_value(T v) { value = std::move(v); }
        void unhandled_exception() { exception = std::current_exception(); }
    };

    std::coroutine_handle<promise_type> handle;

    explicit Task(std::coroutine_handle<promise_type> h) : handle(h) {}
    Task(Task&&) = default;
    Task& operator=(Task&&) = default;
    ~Task() { if (handle) handle.destroy(); }

    T get() {
        handle.resume();
        if (handle.promise().exception)
            std::rethrow_exception(handle.promise().exception);
        return std::move(*handle.promise().value);
    }
};