[/
    Copyright (c) 2016-2019 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:BodyWriter 消息体写入器]

[*BodyWriter] 提供一种 [@https://en.wikipedia.org/wiki/Online_algorithm 在线算法]，用于在序列化过程中从消息体获取零个或多个缓冲区序列。实现会在需要时创建该类型的实例，并调用一次或多次以检索包含消息体八位字节的缓冲区。[BodyWriter] 的接口设计用于获取以下场景的缓冲区：

* 无法完整存入内存的消息体。
* 由协程输出逐步生成的消息体。
* 由已在内存中的零个或多个缓冲区表示的消息体。
* 大小无法预先确定的消息体。
* 由其他线程动态生成的消息体数据。
* 通过算法计算得到的消息体数据。

[heading 关联类型]

* [link beast.ref.boost__beast__http__is_body_writer `is_body_writer`]
* __Body__

[heading 要求]

[warning
    这些要求可能发生不向后兼容的变更
    changes in subsequent versions.
]

在下表中：

W 表示满足 [*BodyWriter] 要求的类型。

B 表示一个 Body 类型，其中
      `std::is_same<W, B::writer>::value == true`.
* `a` 表示类型为 `W` 的值。  
* `h` 表示类型为 `header<isRequest, Fields> const&` 的常量值。  
* `v` 表示类型可能为常量的 `Body::value_type&` 值。  
* `ec` 表示类型为 [link beast.ref.boost__beast__error_code `error_code&`] 的值。  
* `W<T>` 表示类型 `boost::optional<std::pair<T, bool>>`。

[table 有效表达式
[[表达式] [类型] [语义、前置条件与后置条件]]
[
    [`W::const_buffers_type`]
    []
    [该类型满足 ConstBufferSequence 的要求，为 W::get 返回的缓冲区类型。]
][
    [`W{h,v};`]
    []
    [可从 `h` 和 `v` 构造。`h` 和 `v` 的生命周期保证不早于 `W` 销毁前结束。写入器在首次调用 `init` 之前不应访问 `h` 或 `v` 的内容，以支持消息的延迟构造。

构造函数可选择要求 `h` 和 `v` 为 const 引用，其影响如下：

* 若 `W` 要求 `h` 和 `v` 为 const 引用，则对应消息体类型的序列化器构造函数将接受对消息的 const 引用。
* 否则，若 `W` 要求 `h` 和 `v` 为非 const 引用，则对应消息体类型的序列化器构造函数将要求对消息的非 const 引用。]
][
    [`a.init(ec)`]
    []
    [最终译文：在调用 get 之前调用一次，以完全初始化对象。消息体在进入该函数前有效，并持续有效直到写入器销毁。该函数在无错误时确保 !ec 为 true，否则将 ec 设置为对应的错误码。]
][
    [`a.get(ec)`]
    [`W<W::const_buffers_type>`]
    [`init` 成功后，该函数被调用一次或多次。若之前调用已返回代表该主体的所有缓冲区，或该函数设置 `ec` 用于指示错误，则该函数返回 `boost::none`。若仍存在剩余缓冲区，则该函数应返回一个 pair，其第一元素包含一个长度非零的缓冲区序列，用于表示该主体中下一组八位字节；其第二元素为 `bool` 类型，`true` 用于表示后续调用可能返回更多缓冲区，`false` 用于表示本次调用所返回的缓冲区为该主体最后一部分。该函数确保：若无错误，则 `!ec` 为 `true`；若存在错误，则将 `ec` 设为对应的错误码。]
]]

[heading 示例]

[concept_BodyWriter]

[heading 模型]

* [link beast.ref.boost__beast__http__basic_dynamic_body.writer `basic_dynamic_body::writer`]
* [link beast.ref.boost__beast__http__basic_file_body__writer `basic_file_body::writer`]
* [link beast.ref.boost__beast__http__basic_string_body.writer `basic_string_body::writer`]
* [link beast.ref.boost__beast__http__buffer_body.writer `buffer_body::writer`]
* [link beast.ref.boost__beast__http__empty_body.writer `empty_body::writer`]
* [link beast.ref.boost__beast__http__span_body.writer `span_body::writer`]
* [link beast.ref.boost__beast__http__vector_body.writer `vector_body::writer`]

[endsect]