简介

​ C++20协程只是提供协程机制，而不是提供协程库。C++20的协程是无栈协程，无栈协程是一个可以挂起/恢复的特殊函数，是函数调用的泛化，且只能被线程调用，本身并不抢占内核调度。

​ C++20 提供了三个新关键字(co_await、co_yield 和 co_return)，如果一个函数中存在这三个关键字之一，那么它就是一个协程。

​ 协程相关的三个关键字：co_await、co_yield与co_return

• co_yield some_value: 保存当前协程的执行状态并挂起，返回some_value给调用者
• co_await some_awaitable: 如果some_awaitable没有ready，就保存当前协程的执行状态并挂起
• co_return some_value: 彻底结束当前协程，返回some_value给协程调用者

协程相关的对象

协程帧(coroutine frame)

当 caller 调用一个协程的时候会先创建一个协程帧，协程帧会构建 promise 对象，再通过 promise 对象产生 return object。

协程帧中主要有这些内容：

• 协程参数

• 局部变量

• promise 对象

这些内容在协程恢复运行的时候需要用到，caller 通过协程帧的句柄 std::coroutine_handle 来访问协程帧。

promise_type

promise_type 是 promise 对象的类型。promise_type 用于定义一类协程的行为，包括协程创建方式、协程初始化完成和结束时的行为、发生异常时的行为、如何生成 awaiter 的行为以及 co_return 的行为等等。promise 对象可以用于记录/存储一个协程实例的状态。每个协程桢与每个 promise 对象以及每个协程实例是一一对应的。

promise_type的接口

promise_type里的接口需要我们实现，promise_type里的接口是给编译器调用的

coroutine return object

它是promise.get_return_object()方法创建的，一种常见的实现手法会将 coroutine_handle 存储到 coroutine object 内，使得该 return object 获得访问协程的能力。

std::coroutine_handle

协程帧的句柄，主要用于访问底层的协程帧、恢复协程和释放协程帧。
程序员可通过调用 std::coroutine_handle::resume() 唤醒协程。

std::coroutine_handle接口

coroutine_handle的接口不需要我们实现，可以直接调用

co_await、awaiter、awaitable

• co_await：一元操作符；

• awaitable：支持 co_await 操作符的类型；

• awaiter：定义了 await_ready、await_suspend 和 await_resume 方法的类型。

co_await expr(expr是表达式) 通常用于表示等待一个任务(可能是 lazy 的，也可能不是)完成。co_await expr 时，expr 的类型需要是一个 awaitable，而该 co_await表达式的具体语义取决于根据该 awaitable 生成的 awaiter。

协程对象如何协作

以一个简单的代码展示这些协程对象如何协作：

Return_t foo () { 
    auto res = co_await awaiter; 
    co_return res ; 
}

Return_t：promise return object。

awaiter: 等待一个task完成。

图中浅蓝色部分的方法就是 Return_t 关联的 promise 对象的函数，浅红色部分就是 co_await 等待的 awaiter。

这个流程的驱动是由编译器根据协程函数生成的代码驱动的，分成三部分：

• 协程创建；
• co_await awaiter 等待 task 完成；
• 获取协程返回值和释放协程帧。

协程的创建

Return_t foo () { 
    auto res = co_await awaiter; 
    co_return res ; 
}

foo()协程会生成下面这样的模板代码(伪代码)，协程的创建都会产生类似的代码：

{
	co_await promise.initial_suspend();
  	try
  	{
    	coroutine body;
  	}
  	catch (...)
  	{
    	promise.unhandled_exception();
  	}
FinalSuspend:
  	co_await promise.final_suspend();
}

首先需要创建协程，创建协程之后是否挂起则由调用者设置 initial_suspend 的返回类型来确定。

创建协程的流程大概如下：

• 创建一个协程帧(coroutine frame)
• 在协程帧里构建 promise 对象
• 把协程的参数拷贝到协程帧里
• 调用 promise.get_return_object() 返回给 caller 一个对象，即代码中的 Return_t 对象

在这个模板框架里有一些可定制点：如 initial_suspend、final_suspend、unhandled_exception 和 return_value。

我们可以通过 promise 的 initial_suspend 和 final_suspend 返回类型来控制协程是否挂起，在 unhandled_exception 里处理异常，在 return_value 里保存协程返回值。

可以根据需要定制 initial_suspend 和 final_suspend 的返回对象来决定是否需要挂起协程。如果挂起协程，代码的控制权就会返回到caller，否则继续执行协程函数体(function body)。

PS:如果禁用异常，那么生成的代码里就不会有 try-catch。此时协程的运行效率几乎等同非协程版的普通函数。

co_await 机制

co_await 操作符是 C++20 新增的一个关键字，co_await expr 一般表示等待一个惰性求值的任务，这个任务可能在某个线程执行，也可能在 OS 内核执行，什么时候执行结束不知道，为了性能，我们又不希望阻塞等待这个任务完成，所以就借助 co_await 把协程挂起并返回到 caller，caller 可以继续做事情，当任务完成之后协程恢复并拿到 co_await 返回的结果。

所以 co_await 一般有这几个作用：

• 挂起协程；
• 返回到 caller；
• 等待某个任务(可能是 lazy 的，也可能是非 lazy 的)完成之后返回任务的结果。

编译器会根据 co_await expr 生成这样的代码:

{
    auto&& value = <expr>;
    auto&& awaitable = get_awaitable(promise, static_cast<decltype(value)>(value));
    auto&& awaiter = get_awaiter(static_cast<decltype(awaitable)>(awaitable));
    if (!awaiter.await_ready()) //是否需要挂起协程
  	{
    	using handle_t = std::experimental::coroutine_handle<P>;
 
    	using await_suspend_result_t = decltype(awaiter.await_suspend(handle_t::from_promise(p)));
 
    	<suspend-coroutine> //挂起协程
 
    	if constexpr (std::is_void_v<await_suspend_result_t>)
    	{
      		awaiter.await_suspend(handle_t::from_promise(p)); //异步(也可能同步)执行task
      		<return-to-caller-or-resumer> //返回给caller
    	}
    	else
    	{
      		static_assert(
         		std::is_same_v<await_suspend_result_t, bool>,
         		"await_suspend() must return 'void' or 'bool'.");
 
      		if (awaiter.await_suspend(handle_t::from_promise(p)))
      		{
        		<return-to-caller-or-resumer>
      		}
    	}
 
    	<resume-point> //task执行完成，恢复协程，这里是协程恢复执行的地方
  	}
 
	return awaiter.await_resume(); //返回task结果
}

这个代码执行流程就是“协程运行流程图”中粉红色部分，从这个生成的代码可以看到，通过定制 awaiter.await_ready() 的返回值就可以控制是否挂起协程还是继续执行，返回 false 就会挂起协程，并执行 awaiter.await_suspend，通过 awaiter.await_suspend 的返回值来决定是返回 caller 还是继续执行。

正是 co_await 的这种机制是变“异步回调”为“同步”的关键。

C++20 协程中最重要的两个对象就是 promise 对象(恢复协程和获取某个任务的执行结果)和 awaiter(挂起协程，等待task执行完成)，其它的都是“工具人”，要实现想要的的协程，关键是要设计如何让这两个对象协作好。

例子

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

namespace Coroutine {
    struct task {
        struct promise_type {
            promise_type() {
                std::cout << "1.task-promise_type():create promise object
";
            }

            task get_return_object() {
                std::cout << "2.task-get_return_object():create coroutine return object, and the coroutine is created now
";
                return {std::coroutine_handle<task::promise_type>::from_promise(*this)};
            }

            // initial_suspend()决定协程初始化后，是继续直接继续执行协程，还是挂起协程返回caller
            // 返回std::suspend_never，表示不挂起协程，会继续执行协程函数体(coroutine body)
            // 返回std::suspend_always，表示挂起协程，不会去执行coroutine body，程序的执行返回到caller那里
            std::suspend_never initial_suspend() {
                std::cout << "3.task-initial_suspend():do you want to susupend the current coroutine?
";
                std::cout << "4.task-initial_suspend():don't suspend because return std::suspend_never, so continue to execute coroutine body
";
                return {};
            }

            // 调用完void return_void()或者void return_value(T v)后，就会调用final_suspend()
            // 如果final_suspend返回std::suspend_never表示不挂起协程，那么协程就会自动销毁，先后销毁promise, 协程帧上得参数和协程帧；
            // 如果返回std::suspend_always则不会自动销毁协程，需要用户手动去删除协程。
            std::suspend_never final_suspend() noexcept {
                std::cout << "15.task-final_suspend():coroutine body finished, do you want to susupend the current coroutine?
";
                std::cout << "16.task-final_suspend():don't suspend because return std::suspend_never, and the continue will be automatically destroyed, bye
";
                return {};
            }

            // 如果协程是void没有返回值，那么就需要定义void return_void()
            // 如果有返回值那么就定义void return_value(T v),用来保存协程的返回值
            // return_value或者return_void，这两个方法只允许存在一个
            void return_void() {
                std::cout << "14.task-return_void():coroutine don't return value, so return_void is called
";
            }

            void unhandled_exception() {}
        };

        std::coroutine_handle<task::promise_type> handle_;
    };

    struct awaiter {
        // 调用co_wait awaiter{};时调用await_ready()
        // 表示是否准备好，要不要挂起协程
        // await_ready()返回false一般表示要挂起协程，并执行await_suspend
        // 返回true说明协程已经执行完了，这时候调用await_resume返回协程的结果。
        bool await_ready() {
            std::cout << "6.await_ready():do you want to suspend current coroutine?
";
            std::cout << "7.await_ready():yes, suspend becase awaiter.await_ready() return false
";
            return false;
        }

        //await_suspend 的返回值来决定是返回 caller 还是继续执行。
        //返回void：协程执行权交还给当前协程的caller。当前协程在未来某个时机被resume之后，然后执行协程函数中co_await下面的语句
        //返回true：同返回void。
        //返回false：直接执行await_resume
        void await_suspend(std::coroutine_handle<task::promise_type> handle) {
            std::cout << "8.await_suspend(std::coroutine_handle<task::promise_type> handle):execute awaiter.await_suspend()
";
            std::thread([handle]() mutable {
                std::cout << "11.lambada():resume coroutine to execute coroutine body
";
                handle();//等价于handle.resume();
                std::cout << "17.lambada():over
";
            }).detach();
            std::cout << "9.await_suspend(std::coroutine_handle<task::promise_type> handle):a new thread lauched, and will return back to caller
";
        }

        //调用完await_resume后直接执行协程函数中co_await下面的语句
        void await_resume() {
            std::cout << "12.await_resume()
";
        }
    };

    task test() {
        std::cout << "5.test():begin to execute coroutine body, the thread id=" << std::this_thread::get_id() << ",and call co_await awaiter{};
"; //#1
        co_await awaiter{};
        std::cout << "13.test():coroutine resumed, continue execute coroutine body now, the thread id=" << std::this_thread::get_id() << "
"; //#3
    }

    template<typename T>
    struct lazy {
    public:
        struct promise_type;

        lazy(std::coroutine_handle<promise_type> handle) : m_handle(handle) {
            std::cout << "3.lazy(std::coroutine_handle<promise_type> handle):Construct a lazy object" << std::endl;
        }

        ~lazy() {
            std::cout << "15.~lazy():Destruct a lazy object " << std::endl;
            m_handle.destroy();
        }

        T get() {
            std::cout << "6.lazy.get():I want to execute the coroutine now. call m_handle.resume()" << std::endl;
            if (!m_handle.done()) {
                m_handle.resume();
            }
            std::cout << "13.lazy.get():We got the return value...:" << m_handle.promise().value << std::endl;
            return m_handle.promise().value;
        }

        struct promise_type {
            T value = {};

            promise_type() {
                std::cout << "1.lazy-promise_type():Promise created" << std::endl;
            }

            ~promise_type() {
                std::cout << "16.lazy- ~promise_type():Promise died" << std::endl;
            }

            auto get_return_object() {
                std::cout << "2.lazy-get_return_object():create coroutine return object, and the coroutine is created now" << std::endl;
                return lazy<T>{std::coroutine_handle<promise_type>::from_promise(*this)};
            }

            auto initial_suspend() {
                std::cout << "4.lazy-initial_suspend():Started the coroutine" << std::endl;
                return std::suspend_always{};
            }

            auto final_suspend() noexcept {
                std::cout << "12.lazy-final_suspend():Finished the coroutine" << std::endl;
                return std::suspend_always{};
            }

            void return_value(T v) {
                std::cout << "11.lazy-return_value(T v):Got coroutine result " << v << std::endl;
                value = v;
            }

            void unhandled_exception() {
                std::exit(1);
            }

            //协程体中调用co_yield xxx;的时候调用yield_value(T val)
            auto yield_value(T val) {
                std::cout << "9.lazy-yield_value(T val): " << val << std::endl;
                value = val;

                //后续不再挂起协程，继续执行
                return std::suspend_never();

//                //后续继续挂起协程
//                return std::suspend_always();
            }

        };

        std::coroutine_handle<promise_type> m_handle;
    };

    lazy<int> my_coroutine() {
        std::cout << "7.my_coroutine():Execute the coroutine function body" << std::endl;
        std::cout << "8.my_coroutine():call---co_yield 66;" << std::endl;
        co_yield 66;
        std::cout << "10.my_coroutine():call---co_return 88;" << std::endl;
        co_return 88;
    }
} // namespace Coroutine

int main() {
    Coroutine::test();
    std::cout << "10.main():come back to caller becuase of co_await awaiter
";
    std::this_thread::sleep_for(std::chrono::seconds(1));

    std::cout << "-----------------------------------" << std::endl;

    auto coro = Coroutine::my_coroutine();
    std::cout << "5.main():call coro.get()" << std::endl;
    auto result = coro.get();
    std::cout << "14.main():The coroutine result: " << result << std::endl;

//    std::cout << "main():Second call coro.get()  " << std::endl;
//    result = coro.get();
//    std::cout << "main():The coroutine result2: " << result << std::endl;

    return 0;
}

输出结果：

1.task-promise_type():create promise object
2.task-get_return_object():create coroutine return object, and the coroutine is created now
3.task-initial_suspend():do you want to susupend the current coroutine?
4.task-initial_suspend():don't suspend because return std::suspend_never, so continue to execute coroutine body
5.test():begin to execute coroutine body, the thread id=1,and call co_await awaiter{};
6.await_ready():do you want to suspend current coroutine?
7.await_ready():yes, suspend becase awaiter.await_ready() return false
8.await_suspend(std::coroutine_handle<task::promise_type> handle):execute awaiter.await_suspend()
9.await_suspend(std::coroutine_handle<task::promise_type> handle):a new thread lauched, and will return back to caller
10.main():come back to caller becuase of co_await awaiter
11.lambada():resume coroutine to execute coroutine body
12.await_resume()
13.test():coroutine resumed, continue execute coroutine body now, the thread id=2
14.task-return_void():coroutine don't return value, so return_void is called
15.task-final_suspend():coroutine body finished, do you want to susupend the current coroutine?
16.task-final_suspend():don't suspend because return std::suspend_never, and the continue will be automatically destroyed, bye
17.lambada():over
-----------------------------------
1.lazy-promise_type():Promise created
2.lazy-get_return_object():create coroutine return object, and the coroutine is created now
3.lazy(std::coroutine_handle<promise_type> handle):Construct a lazy object
4.lazy-initial_suspend():Started the coroutine
5.main():call coro.get()
6.lazy.get():I want to execute the coroutine now. call m_handle.resume()
7.my_coroutine():Execute the coroutine function body
8.my_coroutine():call---co_yield 66;
9.lazy-yield_value(T val): 66
10.my_coroutine():call---co_return 88;
11.lazy-return_value(T v):Got coroutine result 88
12.lazy-final_suspend():Finished the coroutine
13.lazy.get():We got the return value...:88
14.main():The coroutine result: 88
15.~lazy():Destruct a lazy object 
16.lazy- ~promise_type():Promise died

Process finished with exit code 0