[/
    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 记录]

由于读取数据的调用可能返回数量不等的字节，因此读取数据的调用接口需要一个满足 __DynamicBuffer__ 要求的对象。该概念基于 __streambuf__ 建模。

该实现不执行消息的排队或缓冲操作。如果需要这些功能，应由调用方提供。这种设计的影响是，库用户可以完全控制存储数据的分配策略，以及底层 TCP/IP 连接上读写两侧的背压管理。

[heading 异步操作类型]

所有函数都提供异步版本。

[code_websocket_8_1]

对异步发起函数的调用支持 Boost.Asio 作者开发的可扩展异步模型，允许使用传统的完成处理器、有栈或无栈协程，甚至 future：

[code_websocket_8_1f]

库附带的示例程序展示了 WebSocket 流操作在所有异步变体中的用法。

[heading I/O 上下文对象]

与底层流关联的 __io_context__ 的创建和操作由调用方负责，允许采用任何实现策略，包括在无线程环境中不需要线程的策略。Beast WebSocket 本身不使用也不要求线程。

[heading 线程安全性]

与普通的 Asio 套接字类似，[link beast.ref.boost__beast__websocket__stream stream] 不是线程安全的。调用方需要按照 Asio 文档的要求，使用隐式或显式的串行器来同步套接字操作。WebSocket 流的异步接口支持以下各类操作同时各有一个处于活动状态：

* [link beast.ref.boost__beast__websocket__stream.async_read `async_read`] or [link beast.ref.boost__beast__websocket__stream.async_read_some `async_read_some`]
* [link beast.ref.boost__beast__websocket__stream.async_write `async_write`] or [link beast.ref.boost__beast__websocket__stream.async_write_some `async_write_some`]
* [link beast.ref.boost__beast__websocket__stream.async_ping `async_ping`] or [link beast.ref.boost__beast__websocket__stream.async_pong `async_pong`]
* [link beast.ref.boost__beast__websocket__stream.async_close `async_close`]

例如，以下代码会导致未定义行为，因为程序试图同时执行两个读取操作：

[code_websocket_8_2]

然而，以下代码是正确的：

[code_websocket_8_3]

实现使用组合异步操作。虽然某些操作可能同时涉及读取和写入，但内部会协调这些行为，确保底层流安全运行。因此，即使有用户发起的异步写入操作正在进行，异步读取操作也能正常响应收到的 ping 帧。

[endsect]