协程 (C++20)
协程是能暂停执行以在之后恢复的函数。协程是无栈的:它们通过返回到调用方暂停执行,并且从栈分离存储恢复执行需要的数据。这样就可以编写异步执行的顺序代码(例如不使用显式的回调来处理非阻塞 I/O),还支持对惰性计算的无限序列上的算法及其他用途。
如果函数的定义进行了下列操作之一,那么它是协程:
- 用
co_await
运算符暂停执行,直到恢复:
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_yield
暂停执行并返回一个值:
generator<int> iota(int n = 0) { while(true) co_yield n++; }
- 用关键词 co_return 完成执行并返回一个值:
lazy<int> f() { co_return 7; }
每个协程必须具有能够满足一组要求的返回类型,标注于下。
限制
协程不能使用变长实参,普通的 return 语句,或占位符返回类型(auto
或 Concept
)。
constexpr 函数、构造函数、析构函数及 main
函数 不能是协程。
执行
每个协程均与下列对象关联:
- 承诺(promise)对象,从协程内部操纵。协程通过此对象提交其结果或异常。
- 协程句柄 (coroutine handle),从协程外部操纵。这是用于恢复协程执行或销毁协程帧的非拥有柄。
- 协程状态 (coroutine state),它是一个包含以下各项的分配于堆(除非优化掉其分配)的内部对象:
- 承诺对象
- 各个形参(全部按值复制)
- 当前暂停点的某种表示,使得恢复时程序知晓要从何处继续,销毁时知晓有哪些局部变量在作用域内
- 生存期跨过当前暂停点的局部变量和临时量
当协程开始执行时,它进行下列操作:
- 用 operator new 分配协程状态对象(见下文)
- 将所有函数形参复制到协程状态中:按值传递的形参被移动或复制,按引用传递的参数保持为引用(因此,如果在被指代对象的生存期结束后恢复协程,它可能变成悬垂引用)
- 调用承诺对象的构造函数。如果承诺类型拥有接收所有协程形参的构造函数,那么以复制后的协程实参调用该构造函数。否则调用其默认构造函数。
- 调用 promise.get_return_object() 并将其结果在局部变量中保持。该调用的结果将在协程首次暂停时返回给调用方。至此并包含这个步骤为止,任何抛出的异常均传播回调用方,而非置于承诺中。
- 调用 promise.initial_suspend() 并 co_await 其结果。典型的承诺类型要么(对于惰性启动的协程)返回 std::suspend_always,要么(对于急切启动的协程)返回 std::suspend_never。
- 当 co_await promise.initial_suspend() 恢复时,开始协程体的执行。
当协程抵达暂停点时:
- 将先前获得的返回对象返回给调用方/恢复方,如果需要则先隐式转换到协程的返回类型。
当协程抵达 co_return 语句时,它进行下列操作:
- 对下列情形调用 promise.return_void()
- co_return;
- co_return expr,其中 expr 具有 void 类型
- 控制流出返回 void 的协程的结尾。此时如果承诺类型 Promise 没有 Promise::return_void() 成员函数,那么则行为未定义。
- 或对于 co_return expr 调用 promise.return_value(expr),其中 expr 具有非 void 类型
- 以创建的逆序销毁所有具有自动存储期的变量。
- 调用 promise.final_suspend() 并 co_await 其结果。
如果协程因未捕捉的异常结束,那么它进行下列操作:
- 捕捉异常并在 catch 块内调用 promise.unhandled_exception()
- 调用 promise.final_suspend() 并 co_await 其结果(例如,以恢复某个继续或发布其结果)。此时开始恢复协程是未定义行为。
当经由 co_return
或未捕捉异常而终止协程导致协程状态被销毁,或经由其句柄而导致其被销毁时,它进行下列操作:
- 调用承诺对象的析构函数。
- 调用各个函数形参副本的析构函数。
- 调用 operator delete 以释放协程状态所用的内存。
- 转移执行回到调用方/恢复方。
堆分配
协程状态由非数组 operator new 在堆上分配。
如果承诺类型定义了类级别的替代函数,那么会使用它,否则会使用全局的 operator new。
如果承诺类型定义了接收额外形参的 operator new 的布置形式,且它们所匹配的实参列表中的第一实参是要求的大小(std::size_t 类型),而其余则是各个协程函数实参,那么将这些实参传递给 operator new(这使得能对协程使用前导分配器约定)
以下情况下,可以优化掉对 operator new 的调用(即使使用了自定义分配器):
- 协程状态的生存期严格内嵌于调用方的生存期,且
- 协程帧的大小在调用点已知
此时协程状态嵌入调用方的栈帧(如果调用方是普通函数)或协程状态(如果调用方是协程)之中。
如果分配失败,那么协程抛出 std::bad_alloc,除非承诺类型 Promise 类型定义了成员函数 Promise::get_return_object_on_allocation_failure()。如果定义了该成员函数,那么使用 operator new 的 nothrow 形式进行分配,而在分配失败时,协程会立即将从 Promise::get_return_object_on_allocation_failure() 获得的对象返回给调用方。
承诺类型(Promise)
编译器用 std::coroutine_traits 从协程的返回类型确定承诺类型。
正式而言,令 R
与 Args...
分别代表协程的返回类型与参数类型列表,ClassT
与 /*cv限定*/ (如果存在)分别代表协程所属的类与其 cv 限定,如果定义它为非静态成员函数,以如下方式确定它的承诺类型 :
- std::coroutine_traits<R, Args...>::promise_type,如果不定义协程为非静态成员函数,
- std::coroutine_traits<R, ClassT /*cv限定*/&, Args...>::promise_type,如果定义协程为非右值引用限定的非静态成员函数,
- std::coroutine_traits<R, ClassT /*cv限定*/&&, Args...>::promise_type,如果定义协程为右值引用限定的非静态成员函数。
例如:
- 如果定义协程为 task<float> foo(std::string x, bool flag);,那么它的承诺类型是 std::coroutine_traits<task<float>, std::string, bool>::promise_type。
- 如果定义协程为 task<void> my_class::method1(int x) const;,那么它的承诺类型是 std::coroutine_traits<task<void>, const my_class&, int>::promise_type。
- 如果定义协程为 task<void> my_class::method1(int x) &&;,那么它的承诺类型是 std::coroutine_traits<task<void>, my_class&&, int>::promise_type。
co_await
一元运算符 co_await 暂停协程并将控制返回给调用方。它的操作数是一个表达式,其类型必须要么定义 operator co_await,要么能以当前协程的 Promise::await_transform 转换到这种类型。
co_await 表达式
|
|||||||||
首先,以下列方式将 表达式 转换成可等待体(awaitable):
- 如果 表达式 由初始暂停点、最终暂停点或 yield 表达式所产生,那么可等待体是 表达式 本身。
- 否则,如果当前协程的承诺类型拥有成员函数 await_transform,那么可等待体是 promise.await_transform(表达式)。
- 否则,可等待体是 表达式 本身。
然后以下列方式获得等待器(awaiter)对象:
- 如果针对 operator co_await 的重载决议给出单个最佳重载,那么等待器是该调用的结果(对于成员重载为 awaitable.operator co_await();,对于非成员重载为 operator co_await(static_cast<Awaitable&&>(awaitable));)
- 否则,如果重载决议找不到
operator co_await
,那么等待器是可等待体本身 - 否则,如果重载决议有歧义,那么程序非良构
如果上述表达式为纯右值,那么等待器对象是从它实质化的临时量。否则,如果上述表达式为泛左值,那么等待器对象是它所指代的对象。
然后,调用 awaiter.await_ready()(这是当已知结果就绪或可以同步完成时,用以避免暂停开销的快捷方式)。如果它的结果按语境转换成 bool
为 false,那么:
- 暂停协程(以各局部变量和当前暂停点填充其协程状态)。
- 调用 awaiter.await_suspend(handle),其中 handle 是表示当前协程的协程句柄。这个函数内部可以通过这个句柄观察暂停的协程,而且此函数负责调度它以在某个执行器上恢复,或将其销毁(并返回
false
当做调度)- 如果
await_suspend
返回void
,那么立即将控制返回给当前协程的调用方/恢复方(此协程保持暂停),否则 - 如果
await_suspend
返回bool
,那么:
- 值为 true 时将控制返回给当前协程的调用方/恢复方
- 值为 false 时恢复当前协程。
- 如果
await_suspend
返回某个其他协程的协程句柄,那么(通过调用 handle.resume())恢复该句柄(注意这可以连锁进行,并最终导致当前协程恢复) - 如果
await_suspend
抛出异常,那么捕捉该异常,恢复协程,并立即重抛异常
- 如果
- 最后,调用 awaiter.await_resume(),它的结果就是整个 co_await expr 表达式的结果。
如果协程在 co_await 表达式中暂停而在后来恢复,那么恢复点处于紧接对 awaiter.await_resume() 的调用之前。
注意,因为协程在进入 awaiter.await_suspend() 前已经完全暂停,所以该函数可以自由地在线程间转移协程柄而无需额外同步。例如,可以将它放入回调,将它调度成在异步 I/O 操作完成时在线程池上运行等。此时因为当前协程可能已被恢复,从而执行了等待器的析构函数,同时由于 await_suspend()
在当前线程上持续执行, await_suspend()
应该把 *this 当作已被销毁并且在柄被发布到其他线程后不再访问它。
示例
#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("jthread 输出参数非空"); out = std::jthread([h] { h.resume(); }); // 潜在的未定义行为:访问潜在被销毁的 *this // std::cout << "新线程 ID:" << p_out->get_id() << "\n"; std::cout << "新线程 ID:" << out.get_id() << "\n"; // 这样可以 } 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 << "协程开始,线程 ID:" << std::this_thread::get_id() << "\n"; co_await switch_to_new_thread(out); // 等待器在此销毁 std::cout << "协程恢复,线程 ID:" << std::this_thread::get_id() << "\n"; } int main() { std::jthread out; resuming_on_new_thread(out); }
可能的输出:
协程开始,线程 ID:139972277602112 新线程 ID:139972267284224 协程恢复,线程 ID:139972267284224
注意:等待器对象是协程状态的一部分(作为生存期跨过暂停点的临时量),并且在 co_await 表达式结束前销毁。可以用它维护某些异步 I/O API 所要求的每操作内状态,而无需用到额外的堆分配。
标准库定义了两个平凡的可等待体:std::suspend_always 及 std::suspend_never。
本节未完成 原因:示例 |
co_yield
yield 表达式向调用方返回一个值并暂停当前协程:它是可恢复生成器函数的常用构建块
co_yield 表达式
|
|||||||||
co_yield 花括号初始化器列表
|
|||||||||
它等价于
co_await promise.yield_value(表达式)
典型的生成器的 yield_value
会将其实参存储(复制/移动或仅存储其地址,因为实参的生存期跨过 co_await 内的暂停点)到生成器对象中并返回 std::suspend_always,将控制转移给调用方/恢复方。
本节未完成 原因:示例 |
库支持
协程支持库定义数个类型,提供协程的编译与运行时支持。