std::generator

< cpp‎ | coroutine
在标头 <generator> 定义
template<

    class Ref,
    class V = void,
    class Allocator = void >
class generator

    : public ranges::view_interface<generator<Ref, V, Allocator>>
 (1) (C++23 起)
namespace pmr {

    template< class Ref, class V = void >
    using generator =
        std::generator<Ref, V, std::pmr::polymorphic_allocator<>>;

}
 (2) (C++23 起)
1) 类模板 std::generator 表示对协程求值返回的元素的 view。
2) 为使用多态分配器的 generator 提供的便利别名模板。

std::generator 通过反复恢复可返回值的协程以生成元素的序列。 每当 co_yield 语句被求值，协程就产生序列的一个元素。 当 co_yield 语句具有形式 co_yield ranges::elements_of(rng) 时，range rng 中的每个元素作为序列的一个元素被依次生成。

std::generator 实现 view 及 input_range。

为 std::generator 添加特化的程序行为未定义。

模板形参

Ref - 生成器的引用类型（ranges::range_reference_t）。如果 V 是 void，则值类型和引用类型均从 Ref 推导
V - 生成器的值类型（range_value_t），或者为 void
Allocator - 分配器类型或者 void

若 Allocator 不是 void，则当 Allocator 不满足分配器 (Allocator) 的要求时其行为未定义。

成员类型

成员 定义
value (私有) std::conditional_t<std::is_void_v<V>, std::remove_cvref_t<Ref>, V>;。
(仅用于阐述的成员类型*)
reference (私有) std::conditional_t<std::is_void_v<V>, Ref&&, Ref>;。
(仅用于阐述的成员类型*)
yielded std::conditional_t<std::is_reference_v<reference>, reference, const reference&>。
类型要求
-
std::allocator_traits<Allocator>::pointer 是指针类型。
-
value 是无 cv 限定的对象类型。
-
reference 是引用类型或者无 cv 限定的实现 copy_constructible 的对象类型。
-
令 /*RRef*/ 表示：std::remove_reference_t</*reference*/>&&，若 /*reference*/ 是引用类型，否则是 /*reference*/。

若这些类型规定中有任何一个未能满足，则程序非良构。

成员对象

成员 定义
active_ (私有)

每个 std::generator 的活动实例内部都关联一个栈（如同以类型 std::unique_ptr<std::stack<std::coroutine_handle<>>> 的对象持有）。

  • 当调用 begin 时，建立新栈且将该生成器加入到这个栈中。
  • 当 co_yield ranges::elements_of(rng) 语句在生成器体中求值时，将 rng 转换为生成器且加入到包含外围生成器的栈中。
  • 当生成器的迭代器自增时，恢复关联栈栈顶的协程。
  • 当生成器完成时 (也就是 promise_type::final_suspend 被调用时)，从此栈中移除它。
    (仅用于阐述的成员对象*)
coroutine_ (私有) std::coroutine_handle<promise_type> 类型的句柄
(仅用于阐述的成员对象*)

成员函数

 构造一个 generator 对象
(公开成员函数)
有效率的销毁整个已生成的 generator 栈
(公开成员函数)
赋值一个 generator 对象
(公开成员函数)
恢复起初暂停的协程并返回指向其句柄的迭代器
(公开成员函数)
返回 std::default_sentinel
(公开成员函数)
继承自 std::ranges::view_interface
返回视图是否为空。仅当视图满足 forward_range 时提供。
(std::ranges::view_interface<D> 的公开成员函数)
(C++23)
 返回指向范围起始的常量迭代器。
(std::ranges::view_interface<D> 的公开成员函数)
(C++23)
 返回对应于范围常量迭代器的哨位。
(std::ranges::view_interface<D> 的公开成员函数)
返回派生视图是否为非空。仅当 ranges::empty 可应用于它时提供。
(std::ranges::view_interface<D> 的公开成员函数)

嵌套类

 承诺类型
(公开成员类)
迭代器类型
(仅用于阐述的成员类*)

注解

功能特性测试宏 值 标准 功能特性
__cpp_lib_generator 202207L (C++23) std::generator – 适用于范围的同步协程生成器

示例

#include <generator>
#include <iostream>
 
template<typename T>
struct Tree
{
    T value;
    Tree *left{}, *right{};
 
    std::generator<const T&> traverse_inorder() const
    {
        if (left)
            for (const T& x : left->traverse_inorder())
                co_yield x;
 
        co_yield value;
        if (right)
            for (const T& x : right->traverse_inorder())
                co_yield x;
    }
};
 
int main()
{
    Tree<char> tree[]
    {
                                    {'D', tree + 1, tree + 2},
        //                            │
        //            ┌───────────────┴────────────────┐
        //            │                                │
                    {'B', tree + 3, tree + 4},       {'F', tree + 5, tree + 6},
        //            │                                │
        //  ┌─────────┴─────────────┐      ┌───────────┴─────────────┐
        //  │                       │      │                         │
          {'A'},                  {'C'}, {'E'},                    {'G'}
    };
 
    for (char x : tree->traverse_inorder())
        std::cout << x << ' ';
    std::cout << '\n';
}

输出：

A B C D E F G

引用

  • C++23 标准（ISO/IEC 14882:2024）：
  • 26.8 Range generators [coro.generator]

参阅

(C++20)
 创建在等待或销毁时无可观察作用的协程柄
(函数)