C++ Coroutine Function

A coroutine in C++ is a function that can suspend execution to be resumed later, maintaining its local state across suspensions. A function becomes a coroutine implicitly if its body contains at least one of three specific keywords: co_await, co_yield, or co_return. Unlike standard functions, coroutines do not use the standard return statement and rely on a compiler-generated state machine to manage execution flow.

Coroutine Keywords

co_await <expr>: Evaluates an awaiter object. Suspends the coroutine’s execution only if the awaiter’s await_ready() method returns false. If it returns true, the coroutine continues execution synchronously without suspending.
co_yield <expr>: Syntactic sugar for co_await promise.yield_value(<expr>). Suspends the coroutine and returns a value to the caller, provided the resulting awaiter’s await_ready() method returns false.
co_return <expr>: Terminates the coroutine and provides a final return value (or void).

Architectural Components

C++ coroutines are stackless and rely on a tripartite architecture consisting of the Coroutine State, the Promise Object, and the Coroutine Handle.

1. Coroutine State

A compiler-generated, typically heap-allocated frame that persists across suspensions. It contains:

The promise object.
Copied parameters passed to the coroutine.
Local variables with a lifetime spanning a suspension point.
The current execution state (instruction pointer).

2. The Promise Type

The promise object is manipulated from inside the coroutine. It dictates the coroutine’s behavior, such as initialization, termination, and exception handling. The return type of a coroutine must define a nested promise_type (or specialize std::coroutine_traits).

3. The Coroutine Handle

The std::coroutine_handle<promise_type> is a non-owning pointer manipulated from outside the coroutine. The caller uses it to interact with the suspended coroutine state.

#include <coroutine>
#include <iostream>
#include <exception>

// 1. The Return Type containing the promise_type
struct MyCoroutineType {
    struct promise_type {
        int current_value;
        
        // Creates the object returned to the caller
        MyCoroutineType get_return_object() { 
            return MyCoroutineType{std::coroutine_handle<promise_type>::from_promise(*this)}; 
        }
        
        // Dictates behavior immediately after invocation
        std::suspend_always initial_suspend() { return {}; }
        
        // Dictates behavior just before destruction
        std::suspend_always final_suspend() noexcept { return {}; }
        
        // Handles co_return
        void return_void() {} 
        
        // Handles co_yield
        std::suspend_always yield_value(int val) { 
            current_value = val;
            return {}; 
        }
        
        // Catches unhandled exceptions inside the coroutine body
        void unhandled_exception() { std::terminate(); }
    };

    std::coroutine_handle<promise_type> handle;
    
    MyCoroutineType(std::coroutine_handle<promise_type> h) : handle(h) {}
    MyCoroutineType(const MyCoroutineType&) = delete;
    MyCoroutineType(MyCoroutineType&& other) noexcept : handle(other.handle) {
        other.handle = nullptr;
    }
    ~MyCoroutineType() { if (handle) handle.destroy(); }
};

// 2. The Coroutine Function
MyCoroutineType example_coroutine(int param) {
    co_await std::suspend_always{}; 
    co_yield param * 2;             
    co_return;                      
}

// 3. The Caller
int main() {
    MyCoroutineType coro = example_coroutine(10);
    
    // Resumes from initial_suspend, executes until co_await
    coro.handle.resume(); 
    
    // Resumes from co_await, executes until co_yield
    coro.handle.resume(); 
    
    std::cout << "Yielded: " << coro.handle.promise().current_value << '\n';
    
    // Resumes from co_yield, executes until co_return and final_suspend
    coro.handle.resume(); 
    
    return 0;
}

The Awaiter Interface

When co_await <expr> is evaluated, <expr> must resolve to an Awaitable object. The compiler interacts with this object via the Awaiter interface to determine exactly how the suspension occurs.

#include <coroutine>
#include <iostream>
#include <exception>

struct CustomAwaiter {
    // 1. If true, suspension is skipped entirely.
    bool await_ready() const noexcept { 
        return false; 
    }

    // 2. Called immediately after suspension. 
    // Returning void unconditionally suspends the coroutine and returns control to the caller.
    // (Can also return bool to conditionally suspend, or a coroutine_handle to perform a symmetric transfer).
    void await_suspend(std::coroutine_handle<>) const noexcept {
        std::cout << "Coroutine suspended.\n";
    }

    // 3. Called when the coroutine resumes. 
    // The return value becomes the result of the co_await expression.
    int await_resume() const noexcept { 
        return 42; 
    }
};

struct DummyTask {
    struct promise_type {
        DummyTask get_return_object() { 
            return DummyTask{std::coroutine_handle<promise_type>::from_promise(*this)}; 
        }
        std::suspend_never initial_suspend() { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() {}
        void unhandled_exception() { std::terminate(); }
    };

    std::coroutine_handle<promise_type> handle;

    DummyTask(std::coroutine_handle<promise_type> h) : handle(h) {}
    DummyTask(const DummyTask&) = delete;
    DummyTask(DummyTask&& other) noexcept : handle(other.handle) {
        other.handle = nullptr;
    }
    ~DummyTask() { if (handle) handle.destroy(); }
};

DummyTask awaiter_example() {
    // Suspends execution here and returns control to main.
    int result = co_await CustomAwaiter{};
    
    // Executes after main calls task.handle.resume().
    std::cout << "Awaiter result: " << result << '\n';
    co_return;
}

int main() {
    DummyTask task = awaiter_example();
    
    // Resume the coroutine from the CustomAwaiter suspension point.
    task.handle.resume();
    
    return 0;
}

Note: The standard library provides two trivial awaiters: std::suspend_always (always suspends) and std::suspend_never (never suspends).

Compiler Execution Flow

When a coroutine is invoked, the compiler injects boilerplate to manage the state machine:

Allocates the coroutine state using operator new.
Copies function parameters into the coroutine state.
Constructs the promise_type object.
Calls promise.get_return_object(). The result is kept as a local variable to be returned to the caller.
Begins an implicit try-catch block.
Executes co_await promise.initial_suspend() inside the try-catch block.
Executes the actual body of the coroutine.
If an exception escapes the body or the resume phase of initial_suspend, it is caught and routed to promise.unhandled_exception().
Upon reaching co_return or the end of the body, calls promise.return_void() or promise.return_value().
Destroys local variables in reverse order of creation.
Exits the try-catch block.
Executes co_await promise.final_suspend().
State destruction depends on the behavior of final_suspend:
- If final_suspend suspends the coroutine (e.g., returns std::suspend_always), the caller or resumer is responsible for calling .destroy() on the handle to deallocate the state.
- If final_suspend does not suspend (e.g., returns std::suspend_never), the coroutine state is destroyed automatically upon completion. Manually calling .destroy() in this scenario results in undefined behavior (a double-free).

Restrictions

A function cannot be a coroutine if it is:

A constexpr function.
A constructor or destructor.
The main function.
A function using standard return statements (a coroutine must exclusively use co_return if it returns).
A function with variadic arguments (varargs), such as void foo(int, ...).
A function with a placeholder return type (auto or decltype(auto)).