[/
    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 解析器流操作]

非平凡算法需要执行的操作不仅限于一次性接收完整消息，该算法需要做更多事，例如：


* 先接收头部，再接收消息体。

* 使用固定大小缓冲区接收大型消息体。

* 逐步接收消息：每个 I/O 周期内只处理有限的数据量。

* 在读取头部之后，再确定 __Body__ 类型。

这类操作要求调用方管理相关状态的生命周期，具体方式为构造一个派生自 __basic_parser__ 的类。Beast 提供派生类 __parser__，该类型使用 __basic_fields__ 字段容器来创建完整的 __message__ 对象。

[table 解析器
[[名称][描述]]
[[__解析器__
][
    ```
/// 用于生成消息的 HTTP/1 解析器
template<
bool isRequest,                         // 若为 true 则解析 HTTP 请求
class Body,                             // 结果消息的消息体
class Allocator = std::allocator<char>> // 头部所使用的分配器
class parser
: public basic_parser<...>;
    ```
]]
[[
    [link beast.ref.boost__beast__http__request_parser `request_parser`]
][
    ```
/// 用于生成请求消息的 HTTP/1 解析器
template<class Body, class Allocator = std::allocator<char>>
using request_parser = parser<true, Body, Allocator>;
    ```
]]
[[
    [link beast.ref.boost__beast__http__response_parser `response_parser`]
][
    ```
/// 用于生成响应消息的 HTTP/1 解析器
template<class Body, class Allocator = std::allocator<char>>
using response_parser = parser<false, Body, Allocator>;
    ```
]]
]

[note
    __basic_parser__ 及其派生类用于处理八位字节流。
    serialized in the HTTP/1 format described in __rfc7230__.
]

用于操作解析器的流操作如下：

[table 解析器流操作
[[名称][描述]]
[[
    [link beast.ref.boost__beast__http__read.overload1 [*read]]
][从 __SyncReadStream__ 读取所有数据到解析器。
]]
[[
    [link beast.ref.boost__beast__http__async_read.overload1 [*async_read]]
][从 __AsyncReadStream__ 异步读取所有数据到解析器。
]]
[[
    [link beast.ref.boost__beast__http__read_header.overload1 [*read_header]]
][从 __SyncReadStream__ 仅读取头部八位字节到解析器。
]]
[[
    [link beast.ref.boost__beast__http__async_read_header [*async_read_header]]
][从 __AsyncReadStream__ 异步仅读取头部八位字节到解析器。
]]
[[
    [link beast.ref.boost__beast__http__read_some.overload1 [*read_some]]
][从 __SyncReadStream__ 读取部分八位字节到解析器。
]]
[[
    [link beast.ref.boost__beast__http__async_read_some [*async_read_some]]
][从 __AsyncReadStream__ 异步读取部分八位字节到解析器。
]]
]

与消息流操作类似，解析器流操作也需要一个持久的 DynamicBuffer 来保存流中未使用的八位字节。当动态缓冲区使用单个连续内存块存储输入序列时，基本解析器实现能达到最优性能。因此，建议使用 flat_buffer、flat_static_buffer 或 flat_static_buffer_base 的实例；当然，用户自定义的 DynamicBuffer 实现，只要它能生成长度为 1 的输入序列，也同样适用。

解析器内部包含一个已构造的消息对象。传入解析器构造函数的参数会转发到消息容器中。调用方可通过 [link beast.ref.boost__beast__http__parser.get `parser::get`] 访问该消息。若 `Fields` 和 `Body` 类型支持移动构造，调用方还可通过 [link beast.ref.boost__beast__http__parser.release `parser::release`] 获取消息的所有权。以下示例使用解析器读取一个包含字符串消息体的 HTTP 响应，并将其打印出来：

[http_snippet_13]



[section:incremental_read 增量读取 __示例__]

该函数使用 [link beast.ref.boost__beast__http__buffer_body `buffer_body`] 和解析器流操作，通过一个固定大小的小缓冲区逐步读取消息体：

[example_incremental_read]

[endsect]



[section:read_large_response_body 读取大型响应消息体 __示例__]

本示例展示如何提高响应消息体大小的默认限制，以便读取超过默认 8MB 大小的内容。

[example_read_large_response_body]

[endsect]



[endsect]