协程概念
协程是一个可以暂停执行以便稍后恢复的函数。
协程是无堆栈的:通过返回给调用者来暂停执行,并且恢复执行所需的数据与堆栈分开存储。
这允许异步执行顺序的代码(例如,在没有显式回调的情况下处理非阻塞 I/O),并且还支持惰性计算无限序列和其他用途的算法。
如果函数的定义执行以下任何一项,则该函数是协程:
1、使用 co_await 运算符暂停执行直到恢复
task<> tcp_echo_server()
{
char data[1024];
while(true)
{
size_t n = co_await socket.async_read_some(buffer[data]);
co_await async_write(socket,buffer(data,n));
}
}
2、使用关键字 co_yield 暂停执行返回值
generator<int> itoa(int n = 0)
{
while(true)
{
co_yield n++;
}
}
3、使用关键字 co_return 完成执行返回值
lazy<int> f()
{
co_return 7;
}
每个协程都必须具有满足许多要求的返回类型,如下所述:
限制
协程不能使用可变参数、普通返回语句或占位符返回类型(auto 或 Concept)。
constexpr 函数、构造函数、析构函数和主函数不能是协程。
执行
每个协程都与
a、从协程内部操纵的承诺对象。 协程通过此对象提交其结果或异常。
b、协程句柄,从协程外部操作。 这是一个非拥有句柄,用于恢复协程的执行或销毁协程框架。
c、协程状态,它是一个内部的堆分配(除非分配被优化),对象包含
1)承诺(promise)对象
2)参数(全部按值复制)
3)当前暂停点的某种表示,以便 resume 知道在哪里继续, destroy 知道哪些局部变量在范围内
4)生命周期跨越当前挂起点的局部变量和临时变量
当协程开始执行时,它会执行以下操作:
1、使用 operator new 分配协程状态对象(见下文)
2、将所有函数参数复制到协程状态:移动或复制按值复制参数,按引用参数保持引用(如果在引用对象的生命周期结束后恢复协程,则可能会变得悬空)
#include <coroutine>
#include <iostream>
struct promise;
struct coroutine : std::coroutine_handle<promise>
{ using promise_type = struct 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();
}
3、调用 promise 对象的构造函数。 如果 Promise 类型有一个接受所有协程参数的构造函数,则调用该构造函数,并带有复制后的协程参数。 否则调用默认构造函数。
4、调用 promise.get_return_object() 并将结果保存在局部变量中。 当协程第一次挂起时,该调用的结果将返回给调用者。 任何在此步骤之前(包括该步骤)引发的异常都会传给调用者,而不是放在 Promise 中。
5、调用 promise.initial_suspend() 并 co_await 其结果。 典型的 Promise 类型要么返回一个 suspend_always,用于延迟启动的协程,要么返回一个 suspend_never,用于急切启动的协程。
6、当 co_await promise.initial_suspend() 恢复时,开始执行协程主体。
7、当协程到达暂停点时,如果需要,在隐式转换为协程的返回类型后,将之前获得的返回对象返回给调用者/恢复者。
8、当协程到达 co_return 语句时,它会执行以下操作:
1)调用 promise.return_void() 为
a、co_return;
b、co_return expr 其中 expr 的类型为 void
c、从返回 void 的协程的末尾掉落。 在这种情况下,如果 Promise 类型没有 Promise::return_void() 成员函数,则行为未定义。
2)或为 co_return expr 调用 promise.return_value(expr),其中 expr 具有非 void 类型
3)以与创建时相反的顺序销毁所有具有自动存储持续时间的变量。
4)调用 promise.final_suspend() 并 co_await 其结果。
9、如果协程以未捕获的异常结束,它将执行以下操作:
1)捕获异常并从 catch-block 中调用 promise.unhandled_exception()
2)调用 promise.final_suspend() 并 co_await 结果(例如,恢复协程或获取结果)。 从这一点恢复协程是未定义的行为。
10、当协程状态因为 co_return 或未捕获的异常终止,或者因为它的句柄被销毁而被销毁时,它会执行以下操作:
1)调用 promise 对象的析构函数。
2)调用函数参数副本的析构函数。
3)调用 operator delete 释放协程状态使用的内存
4)将执行转移给调用者/resumer。
堆分配
协程状态通过非数组 operator new 在堆上分配。
如果 Promise 类型定义了类级别的替换,则将使用它,否则将使用全局的 operator new。
如果 Promise 类型定义了一个带有附加参数的 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
Promise 类型由编译器使用 std::coroutine_traits 根据协程的返回类型确定。
形式上,令 R 和 Args... 分别表示协程的返回类型和参数类型列表,Class T 和 /*cv-qual*/(如果有)分别表示协程所属的类类型及其 cv-qualification。如果它被定义为非静态成员函数,它的 Promise 类型由以下决定:
1、std::coroutine_traits<R, Args...>::promise_type,如果协程没有定义为非静态成员函数,
2、std::coroutine_traits<R, Class T /*cv-qual*/&, Args...>::promise_type,如果协程被定义为非右值引用限定的非静态成员函数,
3、std::coroutine_traits<R, Class T /*cv-qual*/&&, Args...>::promise_type,如果协程被定义为右值引用限定的非静态成员函数。
例如:
1、如果协程定义为 task<float> foo(std::string x, bool flag);,则其 Promise 类型为 std::coroutine_traits<task<float>, std::string, bool>::promise_type。
2、如果协程定义为 task<void> my_class::method1(int x) const;,则其 Promise 类型为 std::coroutine_traits<task<void>, const my_class&, int>::promise_type。
3、如果协程定义为 task<void> my_class::method1(int x) &&;,则其 Promise 类型为 std::coroutine_traits<task<void>, my_class&&, int>::promise_type。
co_await
unary operator co_await 挂起协程并将控制权返回给调用者。 它的操作数是一个表达式,其类型必须要么定义 operator co_await,要么可以通过当前协程的 Promise::await_transform 转换为这种类型。
co_await expr
首先,将 expr 转换为可等待对象,如下所示:
1、如果 expr 由初始挂起点、最终挂起点或 yield 表达式产生,则awaitable是 expr。
2、否则,如果当前协程的 Promise 类型有成员函数 await_transform,那么 awaitable 就是 promise.await_transform(expr)。
3、否则,awaitable 就是 expr
然后,得到awaiter对象,如下:
1、如果 operator co_await 的重载决议给出了单个最佳重载,则awaiter是该调用的结果(对于成员重载,awaitable.operator co_await(),对于非成员重载,operator co_await(static_cast<Awaitable&&>(awaitable)))
2、否则,如果重载决议没有找到 operator co_await,则awaiter是可等待的。
3、否则,如果重载决议不明确,则程序格式错误。
如果上面的表达式是纯右值,则 awaiter 对象是它的临时物化对象。 否则,如果上面的表达式是一个泛左值,那么 awaiter 对象就是它所引用的对象。
然后,调用 awaiter.await_ready() (如果知道结果已准备好或可以同步完成,这是避免挂起成本的捷径)。 如果其结果,上下文转换为 bool 为假,则协程被挂起(其协程状态由局部变量和当前挂起点填充)。
awaiter.await_suspend(handle) 被调用,其中 handle 是表示当前协程的协程句柄。 在该函数内部,挂起的协程状态可以通过该句柄观察到,并且该函数有责任安排它在某个执行程序上恢复或被销毁(返回错误计数作为调度)
1、如果 await_suspend 返回 void,则立即将控制权返回给当前协程的调用者/恢复者(此协程保持挂起状态)。
2、如果 await_suspend 返回布尔值,值 true 将控制权返回给当前协程的调用者/恢复者;值 false 恢复当前协程。
3、如果 await_suspend 返回某个其他协程的协程句柄,则恢复该句柄(通过调用 handle.resume())(注意这可能会链接到最终导致当前协程恢复)
4、如果 await_suspend 抛出异常,则捕获异常,恢复协程,立即重新抛出异常
最后,调用 awaiter.await_resume() (无论协程是否挂起),其结果是整个 co_await expr 表达式的结果。
如果协程在 co_await 表达式中被挂起,然后又被恢复,那么恢复点就在调用 awaiter.await_resume() 之前。
注意,由于协程在进入 awaiter.await_suspend() 之前已完全挂起,因此该函数可以自由地跨线程传输协程句柄,而无需额外同步。例如,它可以将其放入回调中,计划在异步I/O操作完成时在线程池上运行。在这种情况下,由于当前协同路由可能已经恢复,因此执行了waiter对象的析构函数,当await_suspend()继续在当前线程上执行时,await_suspend()应将*this视为已销毁,并且在句柄发布到其他线程后不访问它。
Example
#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: 140193066129216
New thread ID: 140193045907200
Coroutine resumed on thread: 140193045907200
注意:awaiter 对象是协程状态的一部分(作为一个临时对象,其生命周期跨越一个暂停点),并在 co_await 表达式完成之前被销毁。 它可用于根据某些异步 I/O API 的要求维护每个操作的状态,而无需求助于额外的堆分配。
标准库定义了两个简单的等待项:std::suspend_always 和 std::suspend_never。
co_yield
Yield-expression 向调用者返回一个值并暂停当前协程:它是可恢复生成器函数的通用构建块
co_yield expr
co_yield braced-init-list
它相当于
co_await promise.yield_value(expr)
典型的生成器的 yield_value 会将其参数存储(复制/移动或仅存储其地址,因为参数的生命周期跨越 co_await 内的暂停点)到生成器对象中并返回 std::suspend_always,将控制权转移给调用者/恢复者。
#include <coroutine>
#include <exception>
#include <iostream>
template<typename T>
struct Generator {
struct promise_type;
using handle_type = std::coroutine_handle<promise_type>;
struct promise_type { // required
T value_;
std::exception_ptr exception_;
Generator get_return_object() {
return Generator(handle_type::from_promise(*this));
}
std::suspend_always initial_suspend() { return {}; }
std::suspend_always final_suspend() noexcept { return {}; }
void unhandled_exception() { exception_ = std::current_exception(); } // saving
// exception
template<std::convertible_to<T> From> // C++20 concept
std::suspend_always yield_value(From &&from) {
value_ = std::forward<From>(from); // caching the result in promise
return {};
}
void return_void() {}
};
handle_type h_;
Generator(handle_type h) : h_(h) {}
~Generator() { h_.destroy(); }
explicit operator bool() {
fill();
/*
唯一可靠地确定我们是否完成协程,是否将通过 C++ getter(下面的operator())在协程中生成下
一个值(co_yield)的唯一方法是执行/恢复协程,直到下一个 co_yield 点(或让它脱落)。然后
我们存储/缓存结果以承诺允许getter(下面的operator()在不执行协程的情况下获取它)。
*/
return !h_.done();
}
T operator()() {
fill();
full_ = false; // 我们将移出先前缓存的结果以使 promise 再次为空
return std::move(h_.promise().value_);
}
private:
bool full_ = false;
void fill() {
if (!full_) {
h_();
if (h_.promise().exception_)
std::rethrow_exception(h_.promise().exception_);
// 在被调用的上下文中传播协程异常
full_ = true;
}
}
};
Generator<uint64_t>
fibonacci_sequence(unsigned n)
{
if (n==0)
co_return;
if (n>94)
throw std::runtime_error("Too big Fibonacci sequence. Elements would overflow.");
co_yield 0;
if (n==1)
co_return;
co_yield 1;
if (n==2)
co_return;
uint64_t a=0;
uint64_t b=1;
for (unsigned i = 2; i < n; i++)
{
uint64_t s=a+b;
co_yield s;
a=b;
b=s;
}
}
int main()
{
try {
auto gen = fibonacci_sequence(10); // max 94 before uint64_t overflows
for (int j=0; gen; j++)
std::cout << "fib("<<j <<")=" << gen() << '\n';
}
catch (const std::exception& ex)
{
std::cerr << "Exception: " << ex.what() << '\n';
}
catch (...)
{
std::cerr << "Unknown exception.\n";
}
}
Output:
fib(0)=0
fib(1)=1
fib(2)=1
fib(3)=2
fib(4)=3
fib(5)=5
fib(6)=8
fib(7)=13
fib(8)=21
fib(9)=34