C++20 Coroutines Explained: Internals, Pitfalls and Real-World Patterns

#include <coroutine>
#include <iostream>
#include <memory>

// ---------------------------------------------------------------------------
// A minimal coroutine that lets us inspect exactly when each lifecycle hook
// fires.  Nothing is hidden — every promise hook prints its name.
// ---------------------------------------------------------------------------

struct InspectableTask {
    // Every coroutine return type must have a nested promise_type.
    struct promise_type {
        // Called first: produces the object returned to the caller.
        InspectableTask get_return_object() {
            std::cout << "[promise] get_return_object()\n";
            return InspectableTask{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        // Returning suspend_always means: don't run any of the body yet.
        // The caller gets control back immediately after construction.
        std::suspend_always initial_suspend() noexcept {
            std::cout << "[promise] initial_suspend() — coroutine is lazy\n";
            return {};
        }

        // Returning suspend_always at the end keeps the frame alive so the
        // caller can inspect results.  Returning suspend_never destroys it.
        std::suspend_always final_suspend() noexcept {
            std::cout << "[promise] final_suspend() — frame still alive\n";
            return {};
        }

        // co_return with no value lands here.
        void return_void() {
            std::cout << "[promise] return_void()\n";
        }

        // Any exception that escapes the coroutine body arrives here.
        void unhandled_exception() {
            std::cout << "[promise] unhandled_exception() — rethrowing\n";
            std::rethrow_exception(std::current_exception());
        }
    };

    // The coroutine handle is the only data member — pointer-sized.
    std::coroutine_handle<promise_type> handle;

    explicit InspectableTask(std::coroutine_handle<promise_type> h)
        : handle(h) {}

    // We own the frame, so we destroy it in the destructor.
    ~InspectableTask() {
        if (handle && handle.done()) {
            std::cout << "[task] destroying completed frame\n";
            handle.destroy();
        }
    }

    // Let the caller drive execution one step at a time.
    void resume() {
        if (handle && !handle.done()) {
            handle.resume();
        }
    }

    bool is_done() const { return handle.done(); }
};

// ---------------------------------------------------------------------------
// The coroutine itself — looks like a normal function, but the compiler
// rewrites it completely because it contains co_return.
// ---------------------------------------------------------------------------
InspectableTask demonstrate_lifecycle() {
    std::cout << "[body] coroutine body — step 1\n";
    // co_await suspend_always suspends right here; caller gets control back.
    co_await std::suspend_always{};
    std::cout << "[body] coroutine body — step 2 (resumed)\n";
    co_return;  // triggers return_void(), then final_suspend()
}

int main() {
    std::cout << "--- calling coroutine ---\n";
    // Because initial_suspend returns suspend_always, the body hasn't run yet.
    InspectableTask task = demonstrate_lifecycle();

    std::cout << "--- first resume ---\n";
    task.resume();  // runs until the co_await suspend_always inside the body

    std::cout << "--- second resume ---\n";
    task.resume();  // runs to co_return, then final_suspend

    std::cout << "--- done: " << std::boolalpha << task.is_done() << " ---\n";
    return 0;
}

#include <coroutine>
#include <iostream>
#include <optional>
#include <cstdint>

// ---------------------------------------------------------------------------
// A reusable Generator<T> type.  Produces values lazily on demand.
// Ownership model: the Generator object owns the coroutine frame.
// ---------------------------------------------------------------------------
template<typename ValueType>
class Generator {
public:
    struct promise_type {
        std::optional<ValueType> current_value;

        Generator get_return_object() {
            return Generator{std::coroutine_handle<promise_type>::from_promise(*this)};
        }

        // Suspend immediately — don't produce anything until the caller asks.
        std::suspend_always initial_suspend() noexcept { return {}; }

        // Suspend at the end so the caller can detect completion via done().
        std::suspend_always final_suspend() noexcept { return {}; }

        // co_yield value  →  promise.yield_value(value)  →  suspend
        std::suspend_always yield_value(ValueType value) noexcept {
            current_value = std::move(value);
            return {};  // suspending here passes control back to the caller
        }

        void return_void() noexcept { current_value = std::nullopt; }
        void unhandled_exception() { std::rethrow_exception(std::current_exception()); }
    };

    // -----------------------------------------------------------------------
    // A minimal forward iterator so range-for works: for (auto v : gen) {...}
    // -----------------------------------------------------------------------
    struct iterator {
        std::coroutine_handle<promise_type> handle;

        iterator& operator++() {
            handle.resume();  // ask the coroutine for the next value
            return *this;
        }

        const ValueType& operator*() const {
            return *handle.promise().current_value;
        }

        bool operator==(std::default_sentinel_t) const {
            return handle.done();
        }
    };

    iterator begin() {
        handle_.resume();  // prime the generator: run to the first co_yield
        return iterator{handle_};
    }

    std::default_sentinel_t end() { return {}; }

    explicit Generator(std::coroutine_handle<promise_type> h) : handle_(h) {}

    // Non-copyable: a coroutine frame must have exactly one owner.
    Generator(const Generator&) = delete;
    Generator& operator=(const Generator&) = delete;

    Generator(Generator&& other) noexcept
        : handle_(std::exchange(other.handle_, nullptr)) {}

    ~Generator() {
        if (handle_) handle_.destroy();
    }

private:
    std::coroutine_handle<promise_type> handle_;
};

// ---------------------------------------------------------------------------
// An infinite Fibonacci sequence — impossible to express as a plain vector.
// The coroutine frame keeps 'a' and 'b' alive across every suspension.
// ---------------------------------------------------------------------------
Generator<uint64_t> fibonacci_sequence() {
    uint64_t a = 0;
    uint64_t b = 1;
    while (true) {          // infinite loop is fine — we suspend each iteration
        co_yield a;
        uint64_t next = a + b;
        a = b;
        b = next;
    }
}

// ---------------------------------------------------------------------------
// A finite range generator for comparison — shows early termination works.
// ---------------------------------------------------------------------------
Generator<int> range(int start, int stop, int step = 1) {
    for (int i = start; i < stop; i += step) {
        co_yield i;
    }
    // co_return is implicit when execution falls off the end
}

int main() {
    std::cout << "First 10 Fibonacci numbers:\n";
    int count = 0;
    for (uint64_t fib : fibonacci_sequence()) {
        std::cout << fib << ' ';
        if (++count == 10) break;  // early exit destroys the generator safely
    }
    std::cout << '\n';

    std::cout << "\nEven numbers in [0, 20):\n";
    for (int v : range(0, 20, 2)) {
        std::cout << v << ' ';
    }
    std::cout << '\n';

    return 0;
}

#include <coroutine>
#include <iostream>
#include <thread>
#include <functional>
#include <queue>
#include <mutex>
#include <condition_variable>
#include <exception>
#include <optional>
#include <stdexcept>

// ---------------------------------------------------------------------------
// A minimal thread pool that accepts work items (std::function<void()>).
// In production you'd use a battle-tested library, but this makes the
// coroutine-scheduler interaction completely transparent.
// ---------------------------------------------------------------------------
class ThreadPool {
public:
    explicit ThreadPool(size_t thread_count) {
        for (size_t i = 0; i < thread_count; ++i) {
            workers_.emplace_back([this] { worker_loop(); });
        }
    }

    ~ThreadPool() {
        {
            std::unique_lock lock(mutex_);
            shutdown_ = true;
        }
        cv_.notify_all();
        for (auto& t : workers_) t.join();
    }

    void post(std::function<void()> task) {
        {
            std::unique_lock lock(mutex_);
            work_queue_.push(std::move(task));
        }
        cv_.notify_one();
    }

private:
    void worker_loop() {
        while (true) {
            std::function<void()> task;
            {
                std::unique_lock lock(mutex_);
                cv_.wait(lock, [this] { return !work_queue_.empty() || shutdown_; });
                if (shutdown_ && work_queue_.empty()) return;
                task = std::move(work_queue_.front());
                work_queue_.pop();
            }
            task();  // execute the work item — could be handle.resume()
        }
    }

    std::vector<std::thread>          workers_;
    std::queue<std::function<void()>> work_queue_;
    std::mutex                        mutex_;
    std::condition_variable           cv_;
    bool                              shutdown_ = false;
};

// Global pool — in real code inject this via a scheduler abstraction.
ThreadPool global_pool{2};

// ---------------------------------------------------------------------------
// A custom awaitable that transfers the coroutine to the thread pool.
// This is the key pattern: await_suspend posts handle.resume() as a task.
// ---------------------------------------------------------------------------
struct TransferToPool {
    ThreadPool& pool;

    // Never skip the suspension — we always want a thread-hop.
    bool await_ready() const noexcept { return false; }

    // Store the coroutine handle in the pool's work queue.
    // When a pool thread picks it up, it calls handle.resume().
    void await_suspend(std::coroutine_handle<> handle) const {
        pool.post([handle]() mutable { handle.resume(); });
    }

    // No value produced by this await expression — it's purely a scheduling op.
    void await_resume() const noexcept {}
};

// ---------------------------------------------------------------------------
// Task<T>: a coroutine return type that carries a result (or exception).
// The caller synchronises with a condition variable via .get().
// ---------------------------------------------------------------------------
template<typename ResultType>
class Task {
public:
    struct promise_type {
        std::optional<ResultType>    result;
        std::exception_ptr           exception;
        std::mutex                   completion_mutex;
        std::condition_variable      completion_cv;
        bool                         completed = false;

        Task get_return_object() {
            return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
        }

        // Run the body immediately — no lazy start for tasks.
        std::suspend_never initial_suspend() noexcept { return {}; }

        // Suspend at the end so the promise (and its result) stays alive
        // until the Task wrapper reads the value in .get().
        std::suspend_always final_suspend() noexcept {
            {
                std::unique_lock lock(completion_mutex);
                completed = true;
            }
            completion_cv.notify_all();  // wake up anyone blocked in .get()
            return {};
        }

        void return_value(ResultType value) {
            result = std::move(value);
        }

        void unhandled_exception() {
            exception = std::current_exception();
        }
    };

    // Block the calling thread until the coroutine finishes, then return result.
    ResultType get() {
        auto& p = handle_.promise();
        std::unique_lock lock(p.completion_mutex);
        p.completion_cv.wait(lock, [&p] { return p.completed; });

        if (p.exception) std::rethrow_exception(p.exception);
        return std::move(*p.result);
    }

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

private:
    std::coroutine_handle<promise_type> handle_;
};

// ---------------------------------------------------------------------------
// A coroutine that hops to the thread pool, does 'heavy' work, hops back,
// then returns a computed result.  Notice it reads exactly like sync code.
// ---------------------------------------------------------------------------
Task<int> compute_on_pool(int input_value) {
    std::cout << "[coroutine] starting on thread "
              << std::this_thread::get_id() << '\n';

    // Hand off to the pool — execution resumes on a pool thread.
    co_await TransferToPool{global_pool};

    std::cout << "[coroutine] now running on pool thread "
              << std::this_thread::get_id() << '\n';

    // Simulate expensive computation (database query, file I/O, etc.)
    std::this_thread::sleep_for(std::chrono::milliseconds(50));
    int computed_result = input_value * input_value + 1;

    co_return computed_result;  // stored in promise.result, caller reads via .get()
}

int main() {
    std::cout << "[main] thread id: " << std::this_thread::get_id() << '\n';

    Task<int> task = compute_on_pool(7);

    std::cout << "[main] task launched, doing other work while we wait...\n";

    int result = task.get();  // blocks until coroutine finishes
    std::cout << "[main] result: " << result << '\n';  // 7*7+1 = 50

    return 0;
}

#include <coroutine>
#include <iostream>
#include <string>
#include <string_view>

// ---------------------------------------------------------------------------
// Demonstrating the most common coroutine UB in production code:
// passing a reference to a temporary into a coroutine that suspends.
// ---------------------------------------------------------------------------

struct SimpleTask {
    struct promise_type {
        SimpleTask get_return_object() {
            return SimpleTask{std::coroutine_handle<promise_type>::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::rethrow_exception(std::current_exception()); }
    };

    std::coroutine_handle<promise_type> handle;
    explicit SimpleTask(std::coroutine_handle<promise_type> h) : handle(h) {}
    ~SimpleTask() { if (handle) handle.destroy(); }
    void resume() { if (handle && !handle.done()) handle.resume(); }
};

// ---------------------------------------------------------------------------
// WRONG: accepts string_view — a non-owning reference.
// If the string it views is destroyed before this coroutine resumes, BOOM.
// ---------------------------------------------------------------------------
SimpleTask process_message_WRONG(std::string_view message) {
    // The coroutine suspends here at initial_suspend().
    // 'message' is a string_view — it points into memory we don't own.
    co_await std::suspend_always{};  // suspend point
    // By the time we resume, the caller's temporary std::string may be gone.
    std::cout << "[WRONG] message: " << message << '\n';  // potential UB!
    co_return;
}

// ---------------------------------------------------------------------------
// RIGHT: accept by value — the string is copied into the coroutine frame.
// The frame owns the data for its entire lifetime.
// ---------------------------------------------------------------------------
SimpleTask process_message_CORRECT(std::string message) {
    co_await std::suspend_always{};  // safe to suspend: frame owns 'message'
    std::cout << "[CORRECT] message: " << message << '\n';
    co_return;
}

void demonstrate_dangling_reference() {
    SimpleTask bad_task = [&] {
        std::string temporary_message = "hello from temporary";
        // string_view points into 'temporary_message' on this lambda's stack.
        return process_message_WRONG(temporary_message);
        // temporary_message is destroyed here — before the coroutine resumes!
    }();

    std::cout << "[caller] temporary_message is now out of scope\n";
    bad_task.resume();  // string_view now dangles — undefined behaviour
}

void demonstrate_safe_ownership() {
    SimpleTask good_task = [&] {
        std::string source_message = "hello, safely owned";
        // std::string is copied by value into the coroutine frame.
        return process_message_CORRECT(source_message);
        // source_message destroyed here — but frame has its own copy, so fine.
    }();

    std::cout << "[caller] source string is out of scope, frame copy is safe\n";
    good_task.resume();  // perfectly safe
}

int main() {
    // demonstrate_dangling_reference();  // DO NOT run — UB for illustration only
    std::cout << "Dangling reference demo skipped (undefined behaviour)\n";
    demonstrate_safe_ownership();
    return 0;
}