coroutines

Корутина — функция, тело которой содержит хотя бы одно из трёх новых ключевых слов: co_await (приостановиться в ожидании значения), co_yield (отдать значение наружу и приостановиться) или co_return (завершить корутину, вернув значение). Наличие любого из них меняет саму природу функции: компилятор трансформирует её тело в конечный автомат (state machine), а не в обычную последовательность инструкций со стековым кадром, который исчезает при возврате.A coroutine is a function whose body contains at least one of three new keywords: co_await (suspend while waiting for a value), co_yield (hand a value out and suspend), or co_return (finish the coroutine, optionally returning a value). Having any of them changes the very nature of the function: the compiler transforms its body into a state machine, rather than an ordinary sequence of instructions with a stack frame that disappears on return.

Важное разграничение сразу: coroutines — не про многопоточность. Корутина может (и часто исполняется) полностью в одном потоке, кооперативно передавая управление в точках приостановки. Это ортогональная концепция: многопоточность — про параллельное исполнение на нескольких ядрах, coroutines — про структуру приостановки/возобновления одной логической последовательности вычислений, независимо от того, сколько потоков в этом участвует (может быть один, может быть несколько — зависит от того, что делает конкретный awaiter). Подробности про сами потоки, mutex, atomic и memory model — в cpp_concurrency.md, здесь эта тема сознательно не пересекается.An important distinction up front: coroutines are not about multithreading. A coroutine can (and often does) run entirely on one thread, cooperatively handing control back and forth at suspension points. This is an orthogonal concept: multithreading is about parallel execution across multiple cores; coroutines are about the structure of suspending/resuming a single logical sequence of computation, regardless of how many threads are involved (it could be one, it could be several — depends on what the specific awaiter does). The details of threads themselves, mutex, atomic, and the memory model live in cpp_concurrency.md — that ground is deliberately not covered again here.

read_file_async("data.txt", [](std::string data) {
    parse(data, [](Parsed p) {
        save_to_db(p, []() {
            // "callback hell" — вложенность растёт// "callback hell" — nesting keeps growing
            // с каждым асинхронным шагом,// with every async step,
            // обработка ошибок расползается по коллбэкам// error handling is scattered across callbacks
        });
    });
});

Task<void> process() {
    auto data = co_await read_file_async("data.txt");
    auto parsed = co_await parse(data);
    co_await save_to_db(parsed);
    // читается как синхронный код,// reads like synchronous code,
    // но каждый co_await — точка приостановки// but every co_await is a suspension point
}  // Task<T> — НЕ из стандарта, нужна своя/сторонняя реализация// Task<T> is NOT from the standard — needs a custom/third-party implementation

Асинхронный код (сетевые запросы, файловый I/O, генераторы значений) до coroutines писался тремя способами, каждый — с собственной ценой:Asynchronous code (network requests, file I/O, value generators) before coroutines was written in three ways, each with its own cost:

Компилятор, встретив co_await/co_yield/co_return в теле функции, трансформирует её в конечный автомат. Всё, что нужно этому автомату для продолжения работы после приостановки — локальные переменные, точка возобновления, параметры функции — выносится из обычного стека в отдельно аллоцированный coroutine frame. Обычно эта аллокация происходит в куче (heap), потому что стековый кадр вызывающей функции может уже не существовать к моменту возобновления корутины.When the compiler encounters co_await/co_yield/co_return in a function body, it transforms it into a state machine. Everything that machine needs to keep going after a suspension — local variables, the resume point, function parameters — gets moved out of the ordinary stack into a separately allocated coroutine frame. That allocation is usually on the heap, because the calling function's stack frame may no longer exist by the time the coroutine resumes.

Протокол, который делает это возможным, состоит из двух частей, которые нужно реализовать самостоятельно (стандарт задаёт только интерфейс):The protocol that makes this possible has two parts you must implement yourself (the standard only defines the interface):

• promise_type — объект, живущий внутри coroutine frame, управляющий тем, что происходит при старте, при co_yield/co_return, и при необработанном исключении.promise_type — an object living inside the coroutine frame that controls what happens at start-up, at co_yield/co_return, and on an unhandled exception.
• Awaiter — тип с тремя методами (await_ready, await_suspend, await_resume), определяющий, что именно происходит в точке каждого co_await: нужно ли вообще приостанавливаться, что делать в момент приостановки (например, зарегистрировать callback у сетевого сокета), и что вернуть при возобновлении.An awaiter — a type with three methods (await_ready, await_suspend, await_resume) that defines exactly what happens at each co_await point: whether to suspend at all, what to do at the moment of suspension (say, register a callback with a network socket), and what to return upon resumption.

generator-стиль: co_yield (примерный синтаксис, требует своего promise_type)generator-style: co_yield (illustrative syntax, requires its own promise_type)

Generator<int> range(int n) {
    for (int i = 0; i < n; ++i) {
        co_yield i;   // отдать i наружу, приостановиться,// hand i out, suspend,
                    // возобновиться с этой же точки при следующем запросе// resume from this exact point on the next request
    }
}
// Generator<T> здесь условен — сам стандарт C++20 такого типа не даёт,// Generator<T> here is illustrative — C++20 itself provides no such type,
// std::generator появится только в C++23// std::generator only arrives in C++23

Ключевой факт, который стоит держать в голове: C++20 стандартизует только механизм — низкоуровневый протокол приостановки/возобновления. Он сознательно НЕ включает готовых высокоуровневых типов вроде Task<T> для асинхронных цепочек или Generator<T> для генераторов значений. std::generator появится только в C++23; полноценные асинхронные Task-абстракции по большей части остаются за пределами стандартной библиотеки вовсе, и на практике для них используют сторонние библиотеки (например, cppcoro).The key fact worth holding onto: C++20 standardizes only the mechanism — the low-level suspend/resume protocol. It deliberately does NOT include ready-made high-level types like Task<T> for async chains or Generator<T> for value generators. std::generator only shows up in C++23; full-blown async Task abstractions remain outside the standard library almost entirely, and in practice people reach for third-party libraries (cppcoro, for instance).

Второй кусок протокола, который стоит увидеть отдельно от promise_type — это awaiter, определяющий поведение конкретного co_await-выражения. Простейший возможный awaiter — тот, что никогда не приостанавливается на самом деле, потому что значение уже готово (например, обёртка над уже вычисленным результатом, синхронно доступным без реального ожидания):The second piece of the protocol worth seeing on its own, separate from promise_type, is the awaiter — it defines the behavior of a specific co_await expression. The simplest possible awaiter is one that never actually suspends, because the value is already available (say, a wrapper over an already-computed result that's synchronously available with no real waiting involved):

template <class T>
struct ReadyAwaiter {
    T value;

    bool await_ready() const noexcept {
        return true;   // значение уже есть — приостанавливаться незачем// the value is already there — no need to suspend
    }

    void await_suspend(std::coroutine_handle<>) const noexcept {
        // не вызывается вообще, раз await_ready() == true// never called at all, since await_ready() == true
    }

    T await_resume() noexcept {
        return std::move(value);   // именно это становится результатом co_await// this is exactly what co_await evaluates to
    }
};

// использование внутри корутины:// usage inside a coroutine:
// int x = co_await ReadyAwaiter<int>{42};  // x == 42, без единой реальной приостановки// int x = co_await ReadyAwaiter<int>{42};  // x == 42, with zero real suspensions

Три метода покрывают весь протокол ожидания: await_ready решает, нужно ли приостанавливаться вообще (возврат true — короткий путь без приостановки, как в примере выше); если await_ready вернул false, вызывается await_suspend, получающий handle текущей корутины — именно здесь реальный awaiter регистрирует callback у таймера/сокета/другого источника событий, который позже возобновит корутину через этот handle; наконец await_resume вызывается при возобновлении и его возвращаемое значение становится значением всего выражения co_await.The three methods cover the entire awaiting protocol: await_ready decides whether to suspend at all (returning true is the short path with no suspension, as in the example above); if await_ready returns false, await_suspend is called, receiving a handle to the current coroutine — this is exactly where a real awaiter registers a callback with a timer/socket/other event source that will later resume the coroutine through that handle; finally await_resume is called upon resumption, and its return value becomes the value of the entire co_await expression.

• cppreference — Coroutines
• WG21 P0912 — Merge Coroutines TS into C++20
• cppcoro — сторонняя библиотека готовых типов (Task, Generator и др.)a third-party library of ready-made types (Task, Generator, etc.)