Modules and Coroutines

Modules

Headers work, but they come with repeated parsing, macro leakage, and fragile include boundaries. Modules aim to improve that.

export module math;

export int add(int a, int b) {
    return a + b;
}

Consumers import the module instead of including a header:

import math;

That changes the dependency model from textual inclusion to a compiled interface boundary.

What changes in practice

• Macros do not leak across module boundaries the way headers can.
• Imports communicate dependency direction more cleanly than long include chains.
• Build-system support matters more than syntax here.

A realistic adoption pattern

Start with a small leaf library, export a narrow interface, and keep implementation details in non-exported units. That lets you test toolchain and CI support without forcing the whole repository to change at once.

Tiny module sketch

// math.cppm
export module math;

export int add(int a, int b);
export int square(int x);

// math.cpp
module math;

int add(int a, int b) {
    return a + b;
}

int square(int x) {
    return x * x;
}

// main.cpp
import math;
#include <iostream>

int main() {
    std::cout << add(2, 3) << ' ' << square(4) << '\n';
}

This is the smallest useful mental model: an exported interface unit, an implementation unit, and a consumer that imports the module instead of including a header.

Minimal build-system sketch

Syntax is only half the story. You also need the build to know which file is a module interface and which targets consume it.

cmake_minimum_required(VERSION 3.28)
project(mod_demo LANGUAGES CXX)

add_library(math)
target_sources(math
    PUBLIC
        FILE_SET CXX_MODULES FILES
            math.cppm
    PRIVATE
        math.cpp
)
target_compile_features(math PUBLIC cxx_std_23)

add_executable(app main.cpp)
target_link_libraries(app PRIVATE math)

You do not need this exact layout, but you do need a build that models module interfaces explicitly instead of treating them like ordinary .cpp files.

When modules help

• large codebases with expensive header graphs
• libraries that want clearer interfaces
• new components where build-system support is already available

When to be careful

• mixed toolchains
• older CI environments
• third-party dependencies that still assume header-only integration

Coroutines

Coroutines let a function suspend and resume, which is useful for async workflows and generators.

task<int> compute_answer() {
    co_return 42;
}

The language feature alone is low-level. In practice you use coroutines through an abstraction provided by a framework or library.

Awaiting another operation

task<int> compute_answer() {
    int base = co_await read_value_async();
    co_return base * 2;
}

This is the kind of flow coroutines improve most: asynchronous code that still reads from top to bottom.

Worked async-style example

task<std::string> load_name() {
    auto line = co_await read_line_async();
    if (line.empty()) {
        co_return "anonymous";
    }
    co_return line;
}

task<void> greet_user() {
    auto name = co_await load_name();
    std::cout << "Hello, " << name << '\n';
}

The important part is not the exact task type. The important part is that suspension and resumption happen without turning the code into nested callbacks.

Async result with explicit error flow

task<std::expected<std::string, std::string>> load_config() {
    auto text = co_await read_text_async();
    if (text.empty()) {
        co_return std::unexpected("config file was empty");
    }
    co_return text;
}

This is where coroutines become more believable in real code: you can keep the async flow readable while still returning structured success-or-error results.

Coroutine adoption checklist

• pick the concrete task or generator type first; do not start from raw language machinery
• confirm where cancellation, timeout, and executor or scheduler ownership live
• decide whether errors move as exceptions, std::expected, status objects, or some framework-specific result type
• keep one synchronous fallback implementation around until the async boundary is stable

End-to-end migration pattern

For modules, start with a leaf utility library that already has a stable public interface. For coroutines, start with code that is already callback-heavy or already models a sequence of asynchronous steps. In both cases, the best first win is removing friction from an existing pain point, not rewriting a simple part of the codebase just to exercise new syntax.

Generator-style coroutines

generator<int> countdown(int from) {
    while (from > 0) {
        co_yield from--;
    }
}

This is often the easiest coroutine shape to understand because each suspension point yields a sequence element.

Coroutine mental model

• the compiler builds a state machine
• suspension points save state for later resume
• the promise type and return type define how results and errors move through that state machine

You do not need to hand-write the promise type to benefit from coroutines, but it helps to know that the return type is part of the protocol, not just a normal function return annotation.

The three keywords

• co_await: suspend until another awaitable completes
• co_yield: produce the next value in a sequence
• co_return: finish with a result

Practical coroutine guidance

• use coroutines when the code already wants to suspend and resume
• prefer a real task or generator abstraction instead of experimenting with raw coroutine machinery in production code
• keep error handling explicit, for example with exceptions or std::expected, so suspension does not hide failure paths

Adoption advice

Adopt modules when your compiler and build system support them well. Adopt coroutines when you already have a real async or generator abstraction to build on. Both are powerful, but neither is a "turn it on everywhere" feature.

Quick decision guide

• Rebuild times and header hygiene are the pain point: look at modules.
• Callback-heavy or generator-style control flow is the pain point: look at coroutines.
• Neither pain is real yet: keep these features on the roadmap but do not force them into current code.

Tooling checklist

• verify compiler support for the module or coroutine features you actually plan to use
• confirm your build system and CI can compile the new units consistently
• test third-party library interaction before committing to wide adoption
• introduce the feature in one bounded area before using it across the repository

Exercises

• Move a tiny helper library interface into a module sketch.
• Identify a generator-style loop in existing code and rewrite it as a coroutine pseudocode example.
• List the toolchain requirements you would need before adopting modules in a real project.