std::generator

来自cppreference.com
 
C++
 
工具库
通用工具
关系运算符 (C++20 弃用)
 
协程支持
协程特征
(C++20)
协程句柄
(C++20)
无操作协程
(C++20)
(C++20)
平凡可等待体
(C++20)
(C++20)
范围生成器
(C++23)
 
范围库
范围适配器
 
std::generator
 
<tbody> </tbody>
在标头 <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 提供的便利别名模板。
See More

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 - 生成器的值类型（ranges::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。
  • 实现 std::common_reference_with<reference &&, value &>。
  • 实现 std::common_reference_with<reference &&, RRef &&>。
  • 实现 std::common_reference_with<RRef &&, const value &>。

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

数据成员

成员 定义
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
(公开成员函数) [编辑]
继承自 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)
            co_yield std::ranges::elements_of(left->traverse_inorder());

        co_yield value;

        if (right)
            co_yield std::ranges::elements_of(right->traverse_inorder());
    }
};

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)
 创建等待或销毁无可观察作用的协程句柄
(函数) [编辑]