C++ coroutine generator 实现笔记

胡剑唯

〇、引言

C++20 给我们带来了非常现代化的协程特性，但是主要的增加都集中于语核部分。由于库特性尚未准备充分，所以 C++20 标准库中尚没有多少现成的、组装好的协程设施供我们使用。但是！仅仅通过使用 std::coroutine_handle （这是一个编译器为之开洞的类）并在你的类中定制好几个规定的接口，我们就可以组合出五花八门的功能。你可以理解为，虽然我们没有现成的飞机、火车，但是我们有沙子和铁矿石！完全可以从沙子和铁矿石出发，造出飞机、火车。我知道很多人诟病 C++ 的这个特点，没有现成的这个、现成的那个，自己造很麻烦。但是这也是我比较喜欢 C++ 的一点——上限非常高，你可以为自己的飞机、火车做定制，加上你想要的功能或去掉你不想要的功能；除此以外，你甚至还可以造出之前还没有问世的东西，比如星舰！在其他语言中，语言和标准库给你提供了什么就是什么了，你几乎没有超越的能力。
在 C++23 周期，LEWG (库特性工作组) 在新冠肆虐的艰难背景下完成了大量的工作，使得 C++23 增添了不少很有益的设施（可参考 C++23特性总结 - 上 - Mick235711的文章 - 知乎 https://zhuanlan.zhihu.com/p/562383157）。但是，对于协程方面的内容还是举棋不定。std::generator 和 std::lazy 在合并的计划里进进出出，而最终只有 std::generator 达成目标。对于更花花绿绿的协程库，像 task 等，则可怜的连提案都没有。
另外，在可预见的将来，哪怕标准库收录了一些基本的协程类，为了探索更加花花绿绿的协程高级功能，我们还是需要从最基本的协程设施出发，也就是理解 std::coroutine_handle 和相应的接口。
本文将向读者展示如何实现一个简单的生成器 (generator) 和一个能支持协程内外双向信息传递的生成器。网上关于什么是协程的讲解很多，哪怕是讲 C++ 协程的中文材料也不少。且因笔者时间精力有限，本文不会详细地介绍协程概念，而是更侧重于展示怎么实现出一个 generator，以填补相关参考资料的不足。
一、感性的了解一下协程

协程可以简单地理解为：一个执行时可以主动打断，程序执行流程可以在调用方和被调用方之间进进出出若干次的函数。
Python 是最早的一批支持协程的语言，我们不妨用 Python 来演示一下协程的神奇。（其实早在 19 年，那时 C++ 编译器还没支持协程的时候，笔者就是利用 Python 来理解协程的）


从这个例子我们可以看出以下几点怪异的现象：
1) myrange 函数中并没有一句 return 语句，我们却调用 myrange 函数得到了一个 gen 对象（第 22 行）
2) 22 行调用 myrange 函数后，这个函数似乎并没有立即开始执行（没有执行第 3 行的 print 语句，倒是执行第 23 行的 print 语句了）
3) 调用 gen 对象的 __next__ 方法后，myrange 函数开始执行。执行到第 7 行时，myrange 函数 "yield" 了一个值，然后程序的执行流程又切换到主函数的第 24 行。__next__ 方法得到了刚刚 "yield" 的结果。
4) 26  行再次调用 __next__ 时，执行流程回到了 myrange 中。而且并不是从 myrange 的开头重新开始执行，而是从上一次 "yield" 的地方，也就是第 7 行继续执行。i 的值似乎也没受到影响。
如果你熟悉了协程的特点，这无非可以概括为，协程执行时可以主动打断（更学术一点叫挂起）自己，将控制权交还给调用方。协程挂起期间，协程的栈上信息都可以得到保留。协程恢复后，从上一次的挂起点继续执行。

经过封装后的 C++ 协程库，也可以向用户展示出和 Python 中几乎完全一致的用法。如下就是我们将要实现的 generator 所展示的应用效果。


当然，C++ 毕竟是一个静态类型的语言，除了 range 函数要写 “返回值” generator<int>（当然实际上 range 是一个协程，代码 81 行只是借用了原来的函数和返回值语法了，严格来说不能认为这里声明了一个返回 generator<int> 类型的函数） ，以及 90 行需要声明 gen 的类型以外， 可以说和 Python 没什么两样了。
二、std::coroutine_handle

std::coroutine_handle 类模板是为我们实现协程的各种“魔法”提供支持的最底层的设施，其主要负责存储协程的句柄。它分为模板 std::coroutine_handle<Promise> 和模板特化 std::coroutine_handle<void> ，std::coroutine_handle<void> 可以简单理解为就是做了类型擦除的 std::coroutine_handle<Promise>。
打开 <coroutine> 头文件我们不难看出，std::coroutine_handle<Promise> 中的不少方法是依靠 __builtin 内建函数，也就是编译器开洞实现的。




std::coroutine_handle 中保存了协程的上下文。我们协程执行到哪儿切出去了（协程切换回来后从哪儿开始继续执行）？我们协程的栈上变量在协程切出去期间怎么能得到保留？这些问题的解决都是归功于 std::coroutine_handle 保存了协程的上下文。
std::coroutine_handle 中的方法不多，但是各个都至关重要。由于有些概念还没有铺垫，我们先只罗列三个比较容易理解的方法：
done 方法，可以查询一个协程是否已经结束；
resume 方法可以恢复一个协程的执行；
destroy 方法可以销毁一个协程。
std::coroutine_handle 只是一个很底层很底层的设施，没有 RAII 包裹。它就像裸指针一样（其实它内部也就是一个裸指针），需要靠我们手动创建、手动销毁。我们刚刚谈到，std::coroutine_handle 保存了协程的上下文，其中就有栈上变量的信息。如果一个 handle 被创建出来，用完以后我们忘了对它调用 destroy 了，那么其中存储的上下文信息当然也就没有被销毁——也就是内存泄漏了。如果不小心做了两次 destroy，那么就可能会引发 double free 错误了。所以，我们得写一个 RAII 类将其包装起来，以解决忘记销毁或者其他比如浅拷贝等问题。
<hr/>这里，郑重向大家推荐由清华大学出版社出版的《C++20 实践入门》和《C++20 高级编程》。这两本书是目前最新的一批介绍 C++20 的教程。该书紧跟潮流，就 C++20 的几大热点内容，如 modules、concepts 、ranges 等作了详细介绍。全卷内容质量上乘，精雕细琢，非那些在历史旧版本的基础上草草加两章节新内容圈钱的书可比也！
非常感谢清华大学出版社对这篇文章的赞助！本着对我的读者负责的态度，我坚持要求审读完书的大部分内容后才能做推荐，清华大学出版社的编辑对此给予了高度支持。且，从 8 月份联系我开始，到本文落笔，编辑非常宽容地给了我 4 个月的时间 —— 一段非常充足的时间阅读了这两本书，之后才有了这里的精心推荐。再次表示致敬和谢意！




三、generator

我们的 generator 类终于出场了。
首先，C++ 的协程要求 generator 中必须有 promise_type 这个类型。你可以通过 typedef/using 的方式 alias 一个别名，也可以干脆就定义成 generator 的内部类 —— 本文选择后者。
template <typename T>
struct generator
{
    struct promise_type
    {
    }
};
promise_type 中有这么几个可定制的、会影响协程行为的重要接口，先介绍两个：
1) initial_suspend —— 它回答的是协程一出生时是否就要马上挂起的问题；
2) final_suspend —— 它回答的是协程最后一次是否要挂起的问题；
对于一个 generator 而言，这两个问题的回答是：
初始时和最后一次始终始终都要挂起。
std::suspend_always std::suspend_never 是标准库里面已经定义好的类型，可以方便地回答是否要挂起的问题。
    struct promise_type
    {
        ...

        std::suspend_always initial_suspend() const
        {
            return {};
        }

        std::suspend_always final_suspend() const noexcept
        // 这里注意一下，由于 final_suspend 在收尾阶段工作，所以必须是 noexcept 的
        {
            return {};
        }
    }
在新协程创建完毕好后，C++ 会执行 co_await promise.initial_suspend()，同样的， 在协程结束前也会 co_await promise.final_suspend()。当然了，从名字中我们也能看出，co_await 一个 std::suspend_always 时，执行流程永远都会无条件切出去，而对于 std::suspend_never 则是永远也不会切出。
还记得我们刚刚观察的 Python 代码中的现象吗？主函数中调用 myrange 的时候，是不是立马得到一个 gen 对象的？是不是 myrange 里面没有立即得到执行的？在第一次调用 __next__ 的时候才会去执行的吧？这其实就是因为 myrange 协程一创建好就挂起自己将程序流程切回到调用方了。
如果 initial_suspend 这里回答的是 suspend_never，那么协程就会立刻开始执行。
建议等 generator 实现完成后读者自己动手实践下，将 initial_suspend 的回答换成 final_suspend，看看结果会有什么改变。
3) promise_type 中第三个定制接口是 unhandled_exception，它回答的是协程被其里头的没有捕获的异常终止时做何处理的问题。
我们这里只是简单处理一下，调用 exit 提前终止程序。当然这样的做法太简化了，实际应用时可以考虑使用 std::exception_ptr  等设施做更严谨的处理。
    struct promise_type
    {
        ...

        void unhandled_exception()
        {
            std::exit(EXIT_FAILURE);
        }
    }
4) promise_type 中第四个定制接口，也是最核心的一个是 get_return_object。这个方法也涉及到了如何创建一个 coroutine 的问题 —— 答案就是使用 std::coroutine_handle<promise_type>::from_promise(*this)，即从自己这个 promise ( 也就是*this)  创建一个 coroutine (from_promise 得到的就是一个 coroutine_handle)。generator 中也需要配合，提供一个接受 coroutine_handle 类型的构造函数，将刚刚构造出的 coroutine_handle 保存。
现在，通过get_return_object 得到了 return_object，就会开始询问是否要做 initial_suspend 了 (刚刚介绍的 initial_suspend 还记得吗？)
template <typename T>
struct generator
{
    struct promise_type;

    std::coroutine_handle<promise_type> handle;

    struct promise_type
    {
        ...
        generator get_return_object()
        {
            return generator{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
    };

    generator(std::coroutine_handle<promise_type> handle) :
        handle(handle)
    {
    }

    ...
};
我们之前也提到，coroutine_handle 是无 RAII 的，因此 generator 中得根据三/五法则，做好 RAII。该析构的析构，禁止拷贝，写好移动构造/移动赋值。
template <typename T>
struct generator
{
    struct promise_type;

    std::coroutine_handle<promise_type> handle;

    ...

public:
    generator() = default;
    generator(const generator &) = delete;

private:
    generator(std::coroutine_handle<promise_type> handle) :
        handle(handle)
    {
    }

public:

    generator(generator && src) :
        handle(src.handle)
    {
        src.handle = nullptr;
    }

    generator& operator=(const generator &) = delete;

    generator& operator=(generator && src)
    {
        if (handle) {
            handle.destroy();
        }
        handle = src.handle;
        src.handle = nullptr;
    }

    ~generator()
    {
        if (handle) {
            handle.destroy();
        }
    }

    ...
};
5) 定制 yield_value 接口
接下来的定制则对于 generator 来说至关重要，我们马上就可以让我们的 generator 支持 yield 了！


还是以此举例，co_yield 关键字实际上只是一个语法糖，这一行会被编译器替换为 co_await promise.yield_value(i)，在有了 initial_suspend 和 final_suspend 的经验后，我们这次也就能很容易地猜测出，我们要在 promise_type 中实现一个 yield_value 方法，而返回值负责回答要不要切出的问题。显然，每次 yield 时总是要挂起协程，所以，yield_value 方法的返回值类型应当是 suspend_always。你猜对了吗？
    struct promise_type
    {
        ....

        std::optional<T> opt;

        template <typename Arg>
        std::suspend_always yield_value(Arg && arg)
        {
            opt.emplace(std::forward<Arg>(arg));
            return {};
        }
    };
在 promise 中，我们还增加了一个 optional，用以存放 yield 的结果。注意，很多例子，甚至包括 cppreference 在内，promise 内部都是用的 T 类型的裸值来存放 yield 的结果的。在模板编程中这样做兼容性不太好，我们需要考虑能照顾到不可默认构造的类型。除此以外，我们使用万能引用和完美转发以提升构造值时的性能。
而这个 opt，当然是在等 generator 来取它的。
template <typename T>
struct generator
{
    ...

    T & next()
    {
        handle.resume();
        if (handle.done()) {
            throw generator_done("generator done");
        }
        return *(handle.promise().opt);
    }
};

generator<int> range(int n)
{
    for(int i = 0; i < n; ++i) {
        co_yield i;
    }
}

int main()
{
    generator<int> gen = range(4);

    for (int i = 0; i < 4; ++i) {
        std::cout << gen.next() << std::endl;
    }
}
这里需要结合前文介绍过的内容梳理下。由于 initial_suspend 的返回值是 suspend_always，所以协程刚创建好后就切出，执行流程到了 gen = range(4) 。
再下面，每次对 gen 调用 next 方法时，会执行 handle.resume() 恢复协程。
协程首次恢复运行，当然是从 range 函数的开头开始执行 (如果不是首次恢复运行，当然就是从上一次 yield 出去的地方恢复运行)，直到碰上了 co_yield。这时， 调用 promise.yield_value(i)，根据 co_yield 后面值 (也就是 i) 构造好了值保存在 opt 中。随后，由于 promise.yield_value(i) 的结果是 suspend_always，所以协程切出， 执行流程回到了 handle.resume() 之后。正常情况下 (协程没有执行完毕)，next 方法就会从 promise 里的那个 optional 中取出 yield 的结果，返回给主函数中以供输出。如果检测到已经是最后一次 yield 后再调用 next 的 (即 resume 后检测到 done 的话)，则抛出 generator_done 异常。
完整的 generator 代码如下：
#include <coroutine>
#include <optional>
#include <iostream>
#include <stdexcept>
#include <cstdlib>

struct generator_done :
        std::logic_error
{
    private:
        typedef std::logic_error super;
   
    public:
        using super::super;
};

template <typename T>
struct generator
{
    struct promise_type;

    std::coroutine_handle<promise_type> handle;

    struct promise_type
    {
        std::optional<T> opt;

        std::suspend_always initial_suspend() const
        {
            return {};
        }

        std::suspend_always final_suspend() const noexcept
        {
            return {};
        }

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

        generator get_return_object()
        {
            return generator{std::coroutine_handle<promise_type>::from_promise(*this)};
        }

        template <typename Arg>
        std::suspend_always yield_value(Arg && arg)
        {
            opt.emplace(std::forward<Arg>(arg));
            return {};
        }
    };

public:
    generator() = default;
    generator(const generator &) = delete;

private:
    generator(std::coroutine_handle<promise_type> handle) :
        handle(handle)
    {
    }

public:
    generator(generator && src) :
        handle(src.handle)
    {
        src.handle = nullptr;
    }

    generator& operator=(const generator &) = delete;

    generator& operator=(generator && src)
    {
        if (handle) {
            handle.destroy();
        }
        handle = src.handle;
        src.handle = nullptr;
    }


    ~generator()
    {
        if (handle) {
            handle.destroy();
        }
    }

    T & next()
    {
        handle.resume();
        if (handle.done()) {
            throw generator_done("generator done");
        }
        return *(handle.promise().opt);
    }

};

generator<int> range(int n)
{
    for(int i = 0; i < n; ++i) {
        co_yield i;
    }
}

int main ()
{
    generator<int> gen = range(5);

    for (int i = 0; i < 5; ++i) {
        std::cout << gen.next() << std::endl;
    }
}
四、能双向传递信息的 bigenerator

我们目前完成的 generator 只能做到协程内部向外部 yield 一个值，传递出来信息。能不能做到外部也向协程内部回复一个值，将信息由外部传递到协程内部呢？C++ 的协程机制也是允许的。
其实，co_yield 表达式，当然，我们上面也知道了， 其实就是 co_await promise.yield_value() 这个表达式，其实也是有计算结果的，只不过，我们之前 generator 中的例子，计算结果为 void 类型 —— 没有返回值罢了。
要想整个表达式有返回值，当然我们得从 promise.yield_value() 的返回值入手。我们以前用的是 std::suspend_always，现在得自己配置了。
先上效果：


再上源码：
#include <coroutine>
#include <variant>
#include <iostream>
#include <stdexcept>
#include <cstdlib>

struct generator_done :
        std::logic_error
{
    private:
        typedef std::logic_error super;
   
    public:
        using super::super;
};

template <typename T, typename U>
struct bigenerator
{
    struct promise_type;

    std::coroutine_handle<promise_type> handle;


    struct awaitable : public std::suspend_always
    {
        std::variant<T, U> * ref;

        U & await_resume() const
        {
            return std::get<U>(*ref);
        }
    };


    struct promise_type
    {
        std::variant<T, U> var;

        std::suspend_always initial_suspend() const
        {
            return {};
        }

        std::suspend_always final_suspend() const noexcept
        {
            return {};
        }

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

        bigenerator get_return_object()
        {
            return bigenerator{std::coroutine_handle<promise_type>::from_promise(*this)};
        }

        template <typename Arg>
        awaitable yield_value(Arg && arg)
        {
            var.template emplace<T>(std::forward<Arg>(arg));
            return awaitable{.ref = &var};
        }
    };

public:
    bigenerator() = default;
    bigenerator(const bigenerator &) = delete;

private:
    bigenerator(std::coroutine_handle<promise_type> handle) :
        handle(handle)
    {
    }

public:
    bigenerator(bigenerator && src) :
        handle(src.handle)
    {
        src.handle = nullptr;
    }

    bigenerator& operator=(const bigenerator &) = delete;

    bigenerator& operator=(bigenerator && src)
    {
        if (handle) {
            handle.destroy();
        }
        handle = src.handle;
        src.handle = nullptr;
    }


    ~bigenerator()
    {
        if (handle) {
            handle.destroy();
        }
    }

    template <typename ... Args>
    T & next(Args&& ... args)
    {
        handle.promise().var.template emplace<U>(std::forward<Args>(args)...);
        handle.resume();
        if (handle.done()) {
            throw generator_done("generator done");
        }
        return std::get<T>(handle.promise().var);
    }

};

bigenerator<int, std::string> range(int n)
{
    for(int i = 0; i < n; ++i) {
        std::string sunk = co_yield i;
        std::cout << sunk << std::endl;
    }
}

int main ()
{
    bigenerator gen = range(10);

    for (int i = 0; i < 5; ++i) {
        std::cout << gen.next(i + 1, 'a') << std::endl;
    }
}

然后讲解：
主要变动就是一个新的内部类：awaitable ，在 bigenerator 中，yield_value 接口返回的就是这个类型。它继承自 std::suspend_always，表明我们确实还是需要每次 yield 时都要挂起，但是，这里我们重写了 await_resume 方法，使得协程在恢复时调用这个方法，从 promise 中取出外界传递进去的结果。
    struct awaitable : public std::suspend_always
    {
        std::variant<T, U> * ref;

        U & await_resume() const
        {
            return std::get<U>(*ref);
        }
    };
下面的代码片段展示了 yield_value 中怎么构造 awaitable。其实只要告知 promise 中的 variant 的地址就可以了。bigenerator 中改用了 variant，主要是考虑到 yield 出去的值和 resume 时传递进来的值不会在同一时刻存在，使用 variant 有助于节省空间。
    struct promise_type
    {
        ...

        std::variant<T, U> var;

        template <typename Arg>
        awaitable yield_value(Arg && arg)
        {
            var.template emplace<T>(std::forward<Arg>(arg));
            return awaitable{.ref = &var};
        }
    };
还有 bigenerator  中 next 的变化，其实也就是恢复协程前，在 promise 的 variant 中构造好传进去的对象就好了。
template <typename T, typename U>
struct bigenerator
{
    ...

    template <typename ... Args>
    T & next(Args&& ... args)
    {
        handle.promise().var.template emplace<U>(std::forward<Args>(args)...);
        handle.resume();
        if (handle.done()) {
            throw generator_done("generator done");
        }
        return std::get<T>(handle.promise().var);
    }
};
当然，我们这里没有考虑到 bigenerator<T, T> 这种传出来和传进去的消息类型都一样的情况，但其实只要做一下偏特化就可以了。由于不是协程部分的技术难点，就不再多介绍了。
全文完

无声的风

代码里调用handle.destroy()之前的条件判断好像写反了[思考]

小白花白小

感谢[爱]

刘梓辰他爹

handle.destroy()会把handle置为nullptr吗

树叶的雪

handle 是对象，不是指针