c++20 coroutines 翻译

翻译 https://en.cppreference.com/w/cpp/language/coroutines

个人总结

翻译目的是为了自己熟悉过程中更好的关注当前部分细节；
直接看翻译好的有些地方翻译很差，容易出错，
而且一次看到太多信息容易忽略细节内容。

有机会尝试画一个流程图出来吧？

格式：
中文
english

疑问：
1、疑问：co_await 是在函数开始的地方等待，还是执行完在返回的地方等待，目前理解是开始的地方
2、疑问：这里的 generator 是什么用法，什么作用？
3、疑问：这里的 lazy 是什么用法，什么作用？
4、疑问：这是一个非拥有句柄，什么意思？
5、疑问：post-copy 什么意思？
6、疑问：协程支持多线程并行吗？ 如果支持如何实现的？
7、疑问：这几种情况具体是什么情形
8、疑问：开始执行协程具体内容的时机：promise.initial_suspend() 后

c++20的协程要么好好看，要么就不要看了，简单看很容易搞不懂用法，这是一个编程框架，不是像vector那样一个边界明确和其他无关的类模版。我暂时也是理解内容，实际用还需再梳理一下才可以。好像不如有栈协程方便使用。

Coroutines (C++20)

一个 coroutine 是可以暂停和后续恢复执行的函数。Coroutines 无栈：暂停后回到调用者，上下文数据存储和栈无关。这就允许异步执行一系列操作（如没有明确回调函数的非阻塞IO），也支持没有严格顺序要求的延迟计算和其他用法。
A coroutine is a function that can suspend execution to be resumed later. Coroutines are stackless: they suspend execution by returning to the caller, and the data that is required to resume execution is stored separately from the stack. This allows for sequential code that executes asynchronously (e.g. to handle non-blocking I/O without explicit callbacks), and also supports algorithms on lazy-computed infinite sequences and other uses.

一个函数如果包含以下内容的一个就是 coroutine：
A function is a coroutine if its definition contains any of the following:

co_await - 暂停操作等待恢复
the co_await expression — to suspend execution until resumed

task<> tcp_echo_server()
{
    char data[1024];
    while (true)
    {
        std::size_t n = co_await socket.async_read_some(buffer(data));
        co_await async_write(socket, buffer(data, n));
    }
}

疑问：co_await 是在函数开始的地方等待，还是执行完在返回的地方等待，目前理解是开始的地方

co_yield — 暂停执行返回一个值
the co_yield expression — to suspend execution returning a value

generator<unsigned int> iota(unsigned int n = 0)
{
    while (true)
        co_yield n++;
}

疑问：这里的 generator 是什么用法，什么作用？

co_return — 完成计算过程，返回一个值
the co_return statement — to complete execution returning a value

lazy<int> f()
{
    co_return 7;
}

疑问：这里的 lazy 是什么用法，什么作用？

每个协程都必须有一个返回类型，满足一些要求，如下所述。
Every coroutine must have a return type that satisfies a number of requirements, noted below.

Restrictions 限制条件

协程不能使用可变参数、普通返回语句或占位符返回类型(auto或Concept)。
Coroutines cannot use variadic arguments, plain return statements, or placeholder return types (auto or Concept).

Consteval函数、constexpr函数、构造函数、析构函数和main函数不能是协程。
Consteval functions, constexpr functions, constructors, destructors, and the main function cannot be coroutines.

Execution

每个 coroutine 有如下假设
Each coroutine is associated with

promise对象，在协程内部操作。协程通过这个对象提交它的结果或异常。Promise对象与std:: Promise没有任何关系。
协程句柄，从协程外部操作。这是一个非拥有句柄，用于恢复协程执行或销毁协程帧。
协程状态，它是内部动态分配的存储空间(除非分配被优化)，包含对象：
- promise
- parameters （都是拷贝值）
- 当前挂起点的信息，这样resume就知道在哪里继续，而destroy就知道哪些局部变量在作用域中
- 生存期跨越当前暂停点的局部变量和临时变量。
the promise object, manipulated from inside the coroutine. The coroutine submits its result or exception through this object. Promise objects are in no way related to std::promise.
the coroutine handle, manipulated from outside the coroutine. This is a non-owning handle used to resume execution of the coroutine or to destroy the coroutine frame.
the coroutine state, which is internal, dynamically-allocated storage (unless the allocation is optimized out), object that contains
- the promise object
- the parameters (all copied by value)
- some representation of the current suspension point, so that a resume knows where to continue, and a destroy knows what local variables were in scope
- local variables and temporaries whose lifetime spans the current suspension point.

疑问：这是一个非拥有句柄，什么意思？

当协程开始执行时，它会执行以下操作:
When a coroutine begins execution, it performs the following:

new 协程状态
将所有函数参数复制到协程状态:按值参数被移动或复制，按引用参数保持引用(因此，如果协程在被引用对象的生命周期结束后恢复，则可能成为悬空(参见下面的示例)。
调用promise对象的构造函数。如果promise类型有一个带有所有协程参数的构造函数，则该构造函数将被调用，使用 post-copy 的参数。否则调用默认构造函数。
调用promise.get_return_object()并将结果保存在一个局部变量中。当协程第一次挂起时，调用的结果将返回给调用者。任何抛出的异常(包括此步骤)都会传播回调用者，而不是放在promise中。
调用promise.initial_suspend()， co_awaits 等待结果。典型的Promise类型要么返回std::suspend_always(对于延迟启动的协程)，要么返回std::suspend_never(对于提前启动的协程)。
当co_await promise.initial_suspend()恢复时，开始执行协程的主体。
allocates the coroutine state object using operator new.
copies all function parameters to the coroutine state: by-value parameters are moved or copied, by-reference parameters remain references (thus, may become dangling, if the coroutine is resumed after the lifetime of referred object ends — see below for examples).
calls the constructor for the promise object. If the promise type has a constructor that takes all coroutine parameters, that constructor is called, with post-copy coroutine arguments. Otherwise the default constructor is called.
calls promise.get_return_object() and keeps the result in a local variable. The result of that call will be returned to the caller when the coroutine first suspends. Any exceptions thrown up to and including this step propagate back to the caller, not placed in the promise.
calls promise.initial_suspend() and co_awaits its result. Typical Promise types either return a std::suspend_always, for lazily-started coroutines, or std::suspend_never, for eagerly-started coroutines.
when co_await promise.initial_suspend() resumes, starts executing the body of the coroutine.

参数变为悬空的一些例子:
Some examples of a parameter becoming dangling:

#include <coroutine>
#include <iostream>

struct promise;

struct coroutine : std::coroutine_handle<promise>
{
    using promise_type = ::promise;
};

struct promise
{
    coroutine get_return_object() { return {coroutine::from_promise(*this)}; }
    std::suspend_always initial_suspend() noexcept { return {}; }
    std::suspend_always final_suspend() noexcept { return {}; }
    void return_void() {}
    void unhandled_exception() {}
};

struct S
{
    int i;
    coroutine f()
    {
        std::cout << i;
        co_return;
    }
};

void bad1()
{
    coroutine h = S{0}.f();
    // S{0} destroyed
    h.resume(); // resumed coroutine executes std::cout << i, uses S::i after free
    h.destroy();
}

coroutine bad2()
{
    S s{0};
    return s.f(); // returned coroutine can't be resumed without committing use after free
}

void bad3()
{
    coroutine h = [i = 0]() -> coroutine // a lambda that's also a coroutine
    {
        std::cout << i;
        co_return;
    }(); // immediately invoked
    // lambda destroyed
    h.resume(); // uses (anonymous lambda type)::i after free
    h.destroy();
}

void good()
{
    coroutine h = [](int i) -> coroutine // make i a coroutine parameter
    {
        std::cout << i;
        co_return;
    }(0);
    // lambda destroyed
    h.resume(); // no problem, i has been copied to the coroutine
                // frame as a by-value parameter
    h.destroy();
}

当协程到达暂停点时
When a coroutine reaches a suspension point

返回值到caller或者resumer，如果需要会隐式转换为coroutine的返回类型。
the return object obtained earlier is returned to the caller/resumer, after implicit conversion to the return type of the coroutine, if necessary.

当协程到达co_return语句时，它执行以下操作:
When a coroutine reaches the co_return statement, it performs the following:

调用 promise.return_void()
- co_return;
- co_return expr; where expr has type void
或者调用 promise.return_value(expr) ，expr 为非void 类型
按与创建顺序相反的顺序销毁所有具有自动存储期的变量。
调用promise.final_suspend()， co_awaits 结果。
calls promise.return_void() for
- co_return;
- co_return expr; where expr has type void
or calls promise.return_value(expr) for co_return expr; where expr has non-void type
destroys all variables with automatic storage duration in reverse order they were created.
calls promise.final_suspend() and co_awaits the result.

coroutine 结束相当于co_return；如果没有 return_void 的定义是未知行为。
无论其返回类型如何，在函数体中没有定义关键字的函数都不是协程，如果返回类型不是(可能是cv限定的)void，则从end返回会导致未定义的行为。
Falling off the end of the coroutine is equivalent to co_return;, except that the behavior is undefined if no declarations of return_void can be found in the scope of Promise. A function with none of the defining keywords in its function body is not a coroutine, regardless of its return type, and falling off the end results in undefined behavior if the return type is not (possibly cv-qualified) void.

// assuming that task is some coroutine task type
task<void> f()
{
    // not a coroutine, undefined behavior
}

task<void> g()
{
    co_return;  // OK
}

task<void> h()
{
    co_await g();
    // OK, implicit co_return;
}

如果协程以未捕获异常结束，则执行以下操作:
If the coroutine ends with an uncaught exception, it performs the following:

捕获异常并从捕获块中调用promise.unhandled_exception()
调用promise.final_suspend()和co_await结果(例如恢复continuation或发布结果)。从这一点恢复协程是未定义的行为。
catches the exception and calls promise.unhandled_exception() from within the catch-block
calls promise.final_suspend() and co_awaits the result (e.g. to resume a continuation or publish a result). It's undefined behavior to resume a coroutine from this point.

When the coroutine state is destroyed either because it terminated via co_return or uncaught exception, or because it was destroyed via its handle, it does the following:
当协程状态被销毁时，要么因为它通过co_return或uncaught异常终止，要么因为它通过它的句柄被销毁，它会做以下操作:

调用 promise 的析构函数
调用参数的析构函数
调用delete释放 state的资源
回到caller/resumer.
calls the destructor of the promise object.
calls the destructors of the function parameter copies.
calls operator delete to free the memory used by the coroutine state.
transfers execution back to the caller/resumer.

Dynamic allocation 动态申请内存

通过new 获取动态内存存储state
Coroutine state is allocated dynamically via non-array operator new

如果Promise类型定义了类级别的替换，它将被使用，否则将使用全局new运算符。
If the Promise type defines a class-level replacement, it will be used, otherwise global operator new will be used.

如果Promise类型定义了一个放置形式的new运算符，它接受额外的参数，并且它们与参数列表匹配，其中第一个参数是请求的大小(类型为std::size_t)，其余的是协程函数参数，这些参数将被传递给new运算符(这使得在协程中使用前置分配器约定成为可能)。
If the Promise type defines a placement form of operator new that takes additional parameters, and they match an argument list where the first argument is the size requested (of type std::size_t) and the rest are the coroutine function arguments, those arguments will be passed to operator new (this makes it possible to use leading-allocator-convention for coroutines).

对new运算符的调用可以被优化掉(即使使用了自定义分配器)，需要满足如下条件
The call to operator new can be optimized out (even if custom allocator is used) if

协程状态的生命周期严格嵌套在调用者的生命周期内，并且
协程帧的大小在调用端是已知的。
The lifetime of the coroutine state is strictly nested within the lifetime of the caller, and
the size of coroutine frame is known at the call site.

在这种情况下，协程状态嵌入到调用者的栈帧(如果调用者是普通函数)或协程状态(如果调用者是协程)中。
In that case, coroutine state is embedded in the caller's stack frame (if the caller is an ordinary function) or coroutine state (if the caller is a coroutine).

如果分配失败，协程会抛出std::bad_alloc，除非Promise类型定义了成员函数Promise::get_return_object_on_allocation_failure()。如果定义了该成员函数，则分配使用new运算符的nothrow形式，并且在分配失败时，协程立即将从Promise::get_return_object_on_allocation_failure()获得的对象返回给调用者，例如:
If allocation fails, the coroutine throws std::bad_alloc, unless the Promise type defines the member function Promise::get_return_object_on_allocation_failure(). If that member function is defined, allocation uses the nothrow form of operator new and on allocation failure, the coroutine immediately returns the object obtained from Promise::get_return_object_on_allocation_failure() to the caller, e.g.:

struct Coroutine::promise_type
{
    /* ... */

    // ensure the use of non-throwing operator-new
    static Coroutine get_return_object_on_allocation_failure()
    {
        std::cerr << __func__ << '\n';
        throw std::bad_alloc(); // or, return Coroutine(nullptr);
    }

    // custom non-throwing overload of new
    void* operator new(std::size_t n) noexcept
    {
        if (void* mem = std::malloc(n))
            return mem;
        return nullptr; // allocation failure
    }
};

Promise

Promise的类型是由编译器使用std::coroutine_traits根据协程的返回类型确定的。
The Promise type is determined by the compiler from the return type of the coroutine using std::coroutine_traits.

Formally, let
正式的：

R和Args…分别表示协程的返回类型和参数类型列表，
如果协程定义为非静态成员函数，则classst表示协程所属的类类型，
CV表示函数声明中声明的CV -限定，如果定义为非静态成员函数，
R and Args... denote the return type and parameter type list of a coroutine respectively,
ClassT denote the class type to which the coroutine belongs if it is defined as a non-static member function,
cv denote the cv-qualification declared in the function declaration if it is defined as a non-static member function,

它的Promise类型由以下因素决定:
its Promise type is determined by:

std:: coroutine_traits < R, Args…>::promise_type，如果协程没有定义为隐式对象成员函数，
std:: coroutine_traits < R, cvClassT&, Args…>::promise_type，如果协程定义为非右值引用限定的隐式对象成员函数，
std:: coroutine_traits < R, cvClassT&&, Args…>::promise_type，如果协程定义为右值引用限定的隐式对象成员函数。
std::coroutine_traits<R, Args...>::promise_type, if the coroutine is not defined as an implicit object member function,
std::coroutine_traits<R,cvClassT&, Args...>::promise_type, if the coroutine is defined as an implicit object member function that is not rvalue-reference-qualified,
std::coroutine_traits<R,cvClassT&&, Args...>::promise_type, if the coroutine is defined as an implicit object member function that is rvalue-reference-qualified.

For example:

If the coroutine is defined as ...	then its `Promise` type is ...
task<void> foo(int x);	std::coroutine_traits<task<void>, int>::promise_type
task<void> Bar::foo(int x) const;	std::coroutine_traits<task<void>, const Bar&, int>::promise_type
task<void> Bar::foo(int x) &&;	std::coroutine_traits<task<void>, Bar&&, int>::promise_type

co_await

一元运算符co_await挂起一个协程并将控制权返回给调用者。它的操作数是一个表达式，要么(1)属于定义成员运算符co_await的类类型，要么可以传递给非成员运算符co_await，要么(2)可以通过当前协程的Promise::await_transform转换为这样的类类型。
The unary operator co_await suspends a coroutine and returns control to the caller. Its operand is an expression that either (1) is of a class type that defines a member operator co_await or may be passed to a non-member operator co_await, or (2) is convertible to such a class type by means of the current coroutine's Promise::await_transform.

co_await expr

co_await表达式只能出现在正则函数体(包括lambda表达式的函数体)中潜在求值的表达式中，不能出现
A co_await expression can only appear in a potentially-evaluated expression within a regular function body (including the function body of a lambda expression), and cannot appear

in a handler,
in a declaration statement, unless it appears in an initializer of that declaration statement,
in the simple declaration of an init-statement (see if, switch, for and range-for), unless it appears in an initializer of that init-statement,
in a default argument, or
in the initializer of a block-scope variable with static or thread storage duration.
疑问：这几种情况具体是什么情形

首先，将expr转换为awaitable对象:
First, expr is converted to an awaitable as follows:

如果expr是由 initial suspend、final suspend或yield表达式生成的，那么awaitable对象就是expr。
否则，如果当前协程的Promise类型具有成员函数await_transform，则awaitable为Promise .await_transform(expr)。
否则就是exptr。
if expr is produced by an initial suspend point, a final suspend point, or a yield expression, the awaitable is expr, as-is.
otherwise, if the current coroutine's Promise type has the member function await_transform, then the awaitable is promise.await_transform(expr).
otherwise, the awaitable is expr, as-is.

然后，像下面这样获得awaiter对象:
Then, the awaiter object is obtained, as follows:

如果运算符co_await的重载解析给出了一个最佳重载，则awaiter是该调用的结果:
- awaitable.operator co_await()
- operator co_await(static_cast<Awaitable&&>(awaitable)) for the non-member overload.
否则，如果重载解析没有找到co_await运算符，那么awaiter是可等待的。
否则，如果重载解析不明确，则程序是病态的。
if overload resolution for operator co_await gives a single best overload, the awaiter is the result of that call:
- awaitable.operator co_await() for member overload,
- operator co_await(static_cast<Awaitable&&>(awaitable)) for the non-member overload.
otherwise, if overload resolution finds no operator co_await, the awaiter is awaitable, as-is.
otherwise, if overload resolution is ambiguous, the program is ill-formed.

这句话待理解，暂时不翻译
If the expression above is a prvalue, the awaiter object is a temporary materialized from it. Otherwise, if the expression above is a glvalue, the awaiter object is the object to which it refers.

然后，调用await .await_ready()(如果知道结果已经准备好或者可以同步完成，这是避免暂停开销的快捷方式)。如果其结果根据上下文转换为bool，则为false
Then, awaiter.await_ready() is called (this is a short-cut to avoid the cost of suspension if it's known that the result is ready or can be completed synchronously). If its result, contextually-converted to bool is false then

协程被挂起(它的协程状态由局部变量和当前挂起点填充)。
The coroutine is suspended (its coroutine state is populated with local variables and current suspension point).

Awaiter.await_suspend (handle)被调用，其中handle是表示当前协程的协程句柄。在该函数内部，通过该句柄可以观察到暂停的协程状态，该函数负责将其调度到某些执行器上恢复，或将其销毁(返回false计数作为调度)。
awaiter.await_suspend(handle) is called, where handle is the coroutine handle representing the current coroutine. Inside that function, the suspended coroutine state is observable via that handle, and it's this function's responsibility to schedule it to resume on some executor, or to be destroyed (returning false counts as scheduling)

这段就看原文吧，更好理解

if await_suspend returns void, control is immediately returned to the caller/resumer of the current coroutine (this coroutine remains suspended), otherwise
if await_suspend returns bool,
- the value true returns control to the caller/resumer of the current coroutine
- the value false resumes the current coroutine.
if await_suspend returns a coroutine handle for some other coroutine, that handle is resumed (by a call to handle.resume()) (note this may chain to eventually cause the current coroutine to resume).
if await_suspend throws an exception, the exception is caught, the coroutine is resumed, and the exception is immediately re-thrown.

最后，调用await .await_resume()(无论协程是否被挂起)，其结果是整个co_await expr表达式的结果。
Finally, awaiter.await_resume() is called (whether the coroutine was suspended or not), and its result is the result of the whole co_await expr expression.

如果协程在co_await表达式中被挂起，并且稍后被恢复，那么恢复点就在调用await .await_resume()之前。
If the coroutine was suspended in the co_await expression, and is later resumed, the resume point is immediately before the call to awaiter.await_resume().

注意，因为协程在进入awaiter.await_suspend()之前被完全挂起，所以该函数可以自由地跨线程传输协程句柄，而不需要额外的同步。例如，它可以把它放在回调函数中，计划在异步I/O操作完成时在线程池上运行。在这种情况下，由于当前协程可能已经恢复并因此执行了awaiter对象的析构函数，所有的并发执行都是由于await_suspend()在当前线程上继续执行，await_suspend()应该将*this视为已销毁，并且在句柄发布到其他线程后不再访问它。
Note that because the coroutine is fully suspended before entering awaiter.await_suspend(), that function is free to transfer the coroutine handle across threads, with no additional synchronization. For example, it can put it inside a callback, scheduled to run on a threadpool when async I/O operation completes. In that case, since the current coroutine may have been resumed and thus executed the awaiter object's destructor, all concurrently as await_suspend() continues its execution on the current thread, await_suspend() should treat *this as destroyed and not access it after the handle was published to other threads.

Example

Run this code

#include <coroutine>
#include <iostream>
#include <stdexcept>
#include <thread>

auto switch_to_new_thread(std::jthread& out)
{
    struct awaitable
    {
        std::jthread* p_out;
        bool await_ready() { return false; }
        void await_suspend(std::coroutine_handle<> h)
        {
            std::jthread& out = *p_out;
            if (out.joinable())
                throw std::runtime_error("Output jthread parameter not empty");
            out = std::jthread([h] { h.resume(); });
            // Potential undefined behavior: accessing potentially destroyed *this
            // std::cout << "New thread ID: " << p_out->get_id() << '\n';
            std::cout << "New thread ID: " << out.get_id() << '\n'; // this is OK
        }
        void await_resume() {}
    };
    return awaitable{&out};
}

struct task
{
    struct promise_type
    {
        task get_return_object() { return {}; }
        std::suspend_never initial_suspend() { return {}; }
        std::suspend_never final_suspend() noexcept { return {}; }
        void return_void() {}
        void unhandled_exception() {}
    };
};

task resuming_on_new_thread(std::jthread& out)
{
    std::cout << "Coroutine started on thread: " << std::this_thread::get_id() << '\n';
    co_await switch_to_new_thread(out);
    // awaiter destroyed here
    std::cout << "Coroutine resumed on thread: " << std::this_thread::get_id() << '\n';
}

int main()
{
    std::jthread out;
    resuming_on_new_thread(out);
}

Possible output:

Coroutine started on thread: 139972277602112
New thread ID: 139972267284224
Coroutine resumed on thread: 139972267284224

注意:awaiter对象是协程状态的一部分(作为一个生命周期跨越一个暂停点的临时对象)，在co_await表达式完成之前被销毁。它可以用来根据某些异步I/O api的需要维护每个操作的状态，而无需借助额外的动态分配。
Note: the awaiter object is part of coroutine state (as a temporary whose lifetime crosses a suspension point) and is destroyed before the co_await expression finishes. It can be used to maintain per-operation state as required by some async I/O APIs without resorting to additional dynamic allocations.

The standard library defines two trivial awaitables: std::suspend_always and std::suspend_never.

这里省略了不完整的部分，原文中需要自己展开示例，这里忽略

co_yield

co_yield表达式向调用者返回一个值，并挂起当前协程:它是可恢复生成器函数的常见构建块。
co_yield expression returns a value to the caller and suspends the current coroutine: it is the common building block of resumable generator functions.

co_yield` expr

co_yield` braced-init-list

It is equivalent to

co_await promise.yield_value(expr)

一个典型的生成器的yield_value会将它的参数存储(复制/移动或者只是存储地址，因为参数的生命周期会经过co_await中的悬挂点)到生成器对象中，并返回std::suspend_always，从而将控制权转移到调用者/恢复者。
A typical generator's yield_value would store (copy/move or just store the address of, since the argument's lifetime crosses the suspension point inside the co_await) its argument into the generator object and return std::suspend_always, transferring control to the caller/resumer.