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，以填補相關參考資料的不足。

1

感性的了解一下協程

協程可以簡單地理解為：一個執行時可以主動打斷，程序執行流程可以在調用方和被調用方之間進進出出若干次的函數。

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（當然實際上range是一個協程，代碼 81 行只是借用了原來的函數和返回值語法了，嚴格來說不能認為這里聲明了一個返回generator類型的函數） ，以及 90 行需要聲明gen的類型以外， 可以說和 Python 沒什么兩樣了。

2

std::coroutine_handle

std::coroutine_handle類模板是為我們實現協程的各種“魔法”提供支持的最底層的設施，其主要負責存儲協程的句柄。它分為模板std::coroutine_handle和模板特化std::coroutine_handle，std::coroutine_handle可以簡單理解為就是做了類型擦除的std::coroutine_handle。

打開頭文件我們不難看出，std::coroutine_handle中的不少方法是依靠 __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 類將其包裝起來，以解決忘記銷毀或者其他比如淺拷貝等問題。

這里，鄭重向大家推薦由清華大學出版社出版的《C++20 實踐入門》和《C++20 高級編程》。這兩本書是目前最新的一批介紹 C++20 的教程。該書緊跟潮流，就 C++20 的幾大熱點內容，如modules、concepts、ranges等作了詳細介紹。全卷內容質量上乘，精雕細琢，非那些在歷史舊版本的基礎上草草加兩章節新內容圈錢的書可比也！

非常感謝清華大學出版社對這篇文章的贊助！本著對我的讀者負責的態度，我堅持要求審讀完書的大部分內容后才能做推薦，清華大學出版社的編輯對此給予了高度支持。且，從 8 月份聯系我開始，到本文落筆，編輯非常寬容地給了我 4 個月的時間 —— 一段非常充足的時間閱讀了這兩本書，之后才有了這里的精心推薦。再次表示致敬和謝意！

3

generator

我們的generator類終于出場了。

首先，C++ 的協程要求generator中必須有promise_type這個類型。你可以通過typedef/using的方式 alias 一個別名，也可以干脆就定義成generator的內部類 —— 本文選擇后者。

template 
struct generator
{
    struct promise_type
    {
    }
};

promise_type中有這么幾個可定制的、會影響協程行為的重要接口，先介紹兩個：

1)initial_suspend—— 它回答的是協程一出生時是否就要馬上掛起的問題；

2)final_suspend—— 它回答的是協程最后一次是否要掛起的問題；

對于一個generator而言，這兩個問題的回答是：

初始時始終都要掛起，最后一次始終都不掛起。

std::suspend_alwaysstd::suspend_never是標準庫里面已經定義好的類型，可以方便地回答是否要掛起的問題。

    struct promise_type
    {
        ...

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

        std::suspend_never 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::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 
struct generator
{
    struct promise_type;

    std::coroutine_handle handle;

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

    generator(std::coroutine_handle handle) :
        handle(handle)
    {
    }

    ...
};

我們之前也提到，coroutine_handle是無 RAII 的，因此generator中得根據三/五法則，做好 RAII。該析構的析構，禁止拷貝，寫好移動構造/移動賦值。

template 
struct generator
{
    struct promise_type;

    std::coroutine_handle handle;

    ...

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

private:
    generator(std::coroutine_handle 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 opt;

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

在promise中，我們還增加了一個optional，用以存放 yield 的結果。注意，很多例子，甚至包括 cppreference 在內，promise內部都是用的T類型的裸值來存放 yield 的結果的。在模板編程中這樣做兼容性不太好，我們需要考慮能照顧到不可默認構造的類型。除此以外，我們使用萬能引用和完美轉發以提升構造值時的性能。

而這個opt，當然是在等generator來取它的。

template 
struct generator
{
    ...

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

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

int main()
{
    generator 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 
#include 
#include 
#include 
#include 

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

template 
struct generator
{
    struct promise_type;

    std::coroutine_handle handle;

    struct promise_type
    {
        std::optional opt;

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

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

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

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

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

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

private:
    generator(std::coroutine_handle 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 range(int n)
{
    for(int i = 0; i < n; ++i) {
        co_yield i;
    }
}

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

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

}

4

能雙向傳遞信息的

bigenerator

我們目前完成的generator只能做到協程內部向外部 yield 一個值，傳遞出來信息。能不能做到外部也向協程內部回復一個值，將信息由外部傳遞到協程內部呢？C++ 的協程機制也是允許的。

其實，co_yield表達式，當然，我們上面也知道了， 其實就是co_await promise.yield_value()這個表達式，其實也是有計算結果的，只不過，我們之前generator中的例子，計算結果為void類型 —— 沒有返回值罷了。

要想整個表達式有返回值，當然我們得從promise.yield_value()的返回值入手。我們以前用的是std::suspend_always，現在得自己配置了。

先上效果：

再上源碼：

#include 
#include 
#include 
#include 
#include 

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

template 
struct bigenerator
{
    struct promise_type;

    std::coroutine_handle handle;


    struct awaitable : public std::suspend_always
    {
        std::variant * ref;

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


    struct promise_type
    {
        std::variant var;

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

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

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

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

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

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

private:
    bigenerator(std::coroutine_handle 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 
    T & next(Args&& ... args)
    {
        handle.promise().var.template emplace(std::forward(args)...);
        handle.resume();
        if (handle.done()) {
            throw generator_done("generator done");
        }
        return std::get(handle.promise().var);
    }

};

bigenerator 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;
    }
}
 

    struct awaitable : public std::suspend_always
    {
        std::variant * ref;

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

    struct promise_type
    {
        ...

        std::variant var;

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

template 
struct bigenerator
{
    ...

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