[/
    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 缓冲区类型]

为方便处理 __Asio__ 中定义的 __ConstBufferSequence__ 和 __MutableBufferSequence__ 这两种概念，Beast 将它们视为一种特殊的范围类型。该库提供以下算法和包装器，采用延迟求值的方式对这类范围进行高效转换。转换时不会分配内存，只是在已有且未修改的内存缓冲区上创建轻量级迭代器。缓冲区的控制权依然属于调用方，不涉及所有权转移。

[table 缓冲区算法与类型
[[名称][描述]]
[[
    [link beast.ref.boost__beast__buffer_bytes `buffer_bytes`]
][这是一个更可靠的 `net::buffer_size` 版本，使用起来更简单，并且适用于可转换为 `net::const_buffer` 或 `net::mutable_buffer` 的类型。
]]
[[
    [link beast.ref.boost__beast__buffers_cat `buffers_cat`]
][该函数返回一个新的缓冲区序列，对该序列进行迭代遍历时，其效果相当于将所有输入缓冲区序列拼接在一起。利用该例程，可以将对流 `write_some` 函数的多次调用合并为一次，从而减少昂贵的系统调用。
]]
[[
    [link beast.ref.boost__beast__buffers_cat_view `buffers_cat_view`]
][该类表示将两个或多个缓冲区序列拼接后形成的新缓冲区序列。该类型与 [link beast.ref.boost__beast__buffers_cat `buffers_cat`] 返回的对象类型一致。
]]
[[
    [link beast.ref.boost__beast__buffers_front `buffers_front`]
][该函数用于返回缓冲区序列中的第一个缓冲区。如果该序列为空，则返回一个大小为零的缓冲区。
]]
[[
    [link beast.ref.boost__beast__buffers_prefix `buffers_prefix`]
][该函数用于返回一个代表原始缓冲区前缀的新缓冲区或缓冲区序列。
]]
[[
    [link beast.ref.boost__beast__buffers_prefix_view `buffers_prefix_view`]
][该类表示从现有缓冲区序列前缀中形成的新缓冲区序列。该类型与 [link beast.ref.boost__beast__buffers_prefix `buffers_prefix`] 返回的缓冲区类型一致。
]]
[[
    [link beast.ref.boost__beast__buffers_range `buffers_range`]
    [link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`]
][该函数用于返回一个表示所传入缓冲区序列的可迭代范围。迭代该范围时获取的值始终为常量缓冲区，除非底层缓冲区序列是可变的，此时迭代获取的值将变为可变缓冲区。该函数旨在为编写遍历缓冲区序列的 [范围 for] 语句提供便捷的语法表达。

[link beast.ref.boost__beast__buffers_range `buffers_range`] 函数会保留缓冲区序列的副本，而 [link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`] 则只保留引用（此时调用方需确保被引用缓冲区序列的生命周期延续到该范围对象销毁为止）。
]]
[[
    [link beast.ref.boost__beast__buffers_suffix `buffers_suffix`]
][该类用于包装现有缓冲区序列的底层内存，并呈现原始序列的一个后缀。该后缀的长度可以逐步缩短，方便调用方按顺序逐步处理缓冲区序列中的内容。
]]
[[
    [link beast.ref.boost__beast__buffers_to_string `buffers_to_string`]
][该函数用于将缓冲区序列转换为 `std::string` 字符串，可用于诊断和测试场景。
]]
[[
 [link beast.ref.boost__beast__buffer_ref `buffer_ref`]
 [link beast.ref.boost__beast__ref `ref`]
][该函数用于将通过引用传递的 Beast 缓冲区转换为可通过值传递给 Asio 函数的缓冲区引用。该函数实现了 __DynamicBuffer__v2__ 概念。
]]
]

__Asio__ 中引入的 __DynamicBuffer__ 概念用于描述一种支持所有权且可调整大小的缓冲区序列。Beast 提供以下一组动态缓冲区概念的补充实现：

[table 动态缓冲区实现类型
[[名称][描述]]
[[
    [link beast.ref.boost__beast__buffers_adaptor `buffers_adaptor`]
][该包装器用于将任意 __MutableBufferSequence__ 适配为 __DynamicBuffer__，其输入与输出区域的总大小上限等于底层可变缓冲区序列的大小。该实现不进行堆内存分配。
]]
[[
    [link beast.ref.boost__beast__flat_buffer `flat_buffer`]
    [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`]
][该类保证输入与输出区域均为长度为一的缓冲区序列。构造时可设置输入与输出区域总大小的可选上限。该基本容器是一个 [@https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer [分配器感知容器]]。
]]
[[
    [link beast.ref.boost__beast__multi_buffer `multi_buffer`]
    [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]
][该类使用一个或多个大小不同的字符数组构成的序列。当字符序列的大小发生变化时，会向该序列中追加额外的字符数组对象。该基本容器是一个 [@https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer [分配器感知容器]]。
]]
[[
    [link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`]
    [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`]
][该类保证输入与输出区域均为长度为一的缓冲区序列。它提供动态缓冲区的功能，但输入与输出区域的总大小受模板常量表达式参数所定义的上限约束。该序列的存储空间保存在类内部，实现不进行堆内存分配。
]]
[[
    [link beast.ref.boost__beast__static_buffer `static_buffer`]
    [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`]
][该类提供循环动态缓冲区的功能，输入与输出区域的总大小受模板常量表达式参数所定义的上限约束。实现过程中不会移动缓冲区中的内存数据。该序列的存储空间保存在类内部，实现不进行堆内存分配。
]]
]

这些缓冲区在内存分配方面提供不同的保证。“稳定”意味着通过调用 `data` 或 `prepare` 获取的现有可变缓冲区和常量缓冲区将保持有效。

请注意，拷贝操作始终需要重新调用 `data` 和 `prepare`。

[table 内存稳定性
[[名称] [内存分配] [缓冲区序列长度] [最大容量] [可移动语义] [数据准备与提交] [消耗]]
[
    [[link beast.ref.boost__beast__flat_buffer `flat_buffer`]]
    [动态的] [1] [动态的] [yes] [失效] [失效]
]
[
    [[link beast.ref.boost__beast__multi_buffer `multi_buffer`]]
    [动态的] [动态的] [稳定的] [yes] [失效]
]
[
    [[link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`]]
    [静态的] [1] [静态的] [no] [失效]
]
[
    [[link beast.ref.boost__beast__static_buffer `static_buffer`]]
    [静态的] [1-2] [静态的] [no] [可能导致失效]
]
]

这两个函数用于促进缓冲区与标准输出流之间的互操作性。

[table 缓冲区输出流
[[名称][描述]]
[[
    [link beast.ref.boost__beast__make_printable `make_printable`]
][该函数用于包装 __ConstBufferSequence__，使其能够与 `operator<<` 和 `std::ostream` 配合使用。
]]
[[
    [link beast.ref.boost__beast__ostream `ostream`]
][该函数用于返回一个包装了动态缓冲区的 `std::ostream` 对象。通过 `operator<<` 发送到该流的字符会存储到动态缓冲区中。
]]
]

以下类型特征用于编写操作缓冲区的编译期元函数：

[table 缓冲区算法与类型
[[名称][描述]]
[[
    [link beast.ref.boost__beast__buffers_iterator_type `buffers_iterator_type`]
][该元函数用于确定某个缓冲区序列所使用的迭代器类型。
]]
[[
    [link beast.ref.boost__beast__buffers_type `buffers_type`]
][该元函数用于确定缓冲区序列列表的底层缓冲区类型。该别名对应的具体类型会随模板类型参数的不同而变化。
]]
[[
    [link beast.ref.boost__beast__is_const_buffer_sequence `is_const_buffer_sequence`]
][该元函数用于判断所有指定类型是否都满足 __ConstBufferSequence__ 概念的要求。若每个指定类型都满足要求，则该类型别名为 `std::true_type`；否则为 `std::false_type`。
]]
[[
    [link beast.ref.boost__beast__is_mutable_buffer_sequence `is_mutable_buffer_sequence`]
][该元函数用于判断所有指定类型是否都满足 __MutableBufferSequence__ 概念的要求。若每个指定类型都满足要求，则该类型别名为 `std::true_type`；否则为 `std::false_type`。
]]
]

[endsect]