[/
    Copyright (c) 2016-2022 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/beast
]

[section:BuffersGenerator 缓冲区生成器]

[*缓冲区生成器] 用于提供通用接口，以生成用于顺序处理的序列化数据。

该生成器将被要求生成缓冲区。调用方代码用于指示已消费的数据量，并重复查询缓冲区，直到无更多数据可用，或该生成器指示错误条件为止。

通过这种方式，序列化器可适配为[*缓冲区生成器]，例如[link beast.ref.boost__beast__http__message_generator `http::message_generator`] 用于为多种具体 HTTP 消息类型提供类型擦除接口。

[link beast.ref.boost__beast__write write] 与 [link beast.ref.boost__beast__async_write async_write] 操作以自由函数形式提供重载。这些操作用于调用 [*缓冲区生成器] 的输出，并分别将数据写入 SyncWriteStream 或 AsyncWriteStream 进行处理。

[heading 关联类型]

* [link beast.ref.boost__beast__is_buffers_generator `is_buffers_generator`]
* __ConstBufferSequence__

[heading 要求]

在下表中:

- `G` 用于表示满足 [*缓冲区生成器] 要求的类型。
- `g` 用于表示类型 `G` 的值。
- `c` 用于表示类型 `G` 的可能为 const 的值。
- `n` 是类型 `std::size_t` 的值。
- `ec` 是类型 [link beast.ref.boost__beast__error_code `error_code&`] 的值。

[table 有效表达式
[[表达式] [类型] [语义、前置/后置条件]]
[
    [`G::const_buffers_type`]
    []
    [满足 __ConstBufferSequence__ 要求的类型。该类型用于表示 `g.prepare(ec)` 所返回的缓冲区类型。]
][
    [`c.is_done()`]
    [`bool`（布尔值）]
    [调用此函数以向生成器（generator）查询其完成状态。

当生成器不再产生新的缓冲区，且之前已产生的缓冲区已被完全消费时，即表示生成器已完成。

[*注意：] 在生成器 g 完成后，对其调用 prepare 的结果是未定义的（unspecified）。]
][
    [`g.prepare(ec)`]
    [`G::const_buffers_type`]
    [调用此函数以请求生成器生成包含待处理数据的缓冲区。

返回值为代表未消费数据的 ConstBufferSequence。

如果未发生错误，该函数将确保 ec.failed() 为 false；如果发生了错误，则将其设置为相应的错误码。

如果没有可用的未消费数据，此操作应取得进展，以最终达到完成状态。

在完成或遇到错误后调用‘prepare’的结果由生成器实现定义。通常情况下，不能假定这种调用具有意义或是安全的。

返回缓冲区的容量由生成器实现定义。

[*注意：] 此前调用‘prepare’所获得的任何缓冲区均会失效。]
][
    [`g.consume(n)`]
    []
    [调用此函数以向生成器发出信号，表明生成器的消费者（调用者）已处理了上一次调用‘prepare’所返回的部分数据。

n 的值表示已处理的数据量（以字节为单位）。

当 n 超过上一次调用‘prepare’返回的字节数时，‘consume’ 的行为应如同 n 等于该字节数一样。

剩余的未消费数据将在后续调用‘prepare’时返回。

[*注意：] 此前调用‘prepare’所获得的任何缓冲区均会失效。]
][
    [`is_buffers_generator<G>`]
    [`std::bool_constant`]
    [如果 G 满足条件，则为 std::true_type 的别名，否则为 std::false_type 的别名。]
]]

[heading 示例]

```
    // A buffer sequence generator
    struct BuffersGenerator
    {
        using const_buffers_type = net::const_buffer;

        bool is_done() const;
        const_buffers_type prepare( error_code& ec );
        void consume( std::size_t n );
    };

    static_assert(
        is_buffers_generator<BuffersGenerator>::value, "");
```

[heading 模型]

* [link beast.ref.boost__beast__http__message_generator `http::message_generator`]

[heading 算法]

* [link beast.ref.boost__beast__async_write `async_write`]
* [link beast.ref.boost__beast__write `write`] 

[endsect]