[/
    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 Notes]

Because calls to read data may return a variable amount of bytes, the
interface to calls that read data require an object that meets the requirements
of __DynamicBuffer__. This concept is modeled on __streambuf__.

The implementation does not perform queueing or buffering of messages. If
desired, these features should be provided by callers. The impact of this
design is that library users are in full control of the allocation strategy
used to store data and the back-pressure applied on the read and write side
of the underlying TCP/IP connection.

[heading Asynchronous Operations]

Asynchronous versions are available for all functions:

[code_websocket_8_1]

Calls to asynchronous initiation functions support the extensible asynchronous
model developed by the Boost.Asio author, allowing for traditional completion
handlers, stackful or stackless coroutines, and even futures:

[code_websocket_8_1f]

The example programs that come with the library demonstrate the usage of
websocket stream operations with all asynchronous varieties.

[heading The io_context]

The creation and operation of the __io_context__ associated with the
underlying stream is left to the callers, permitting any implementation
strategy including one that does not require threads for environments
where threads are unavailable. Beast WebSocket itself does not use
or require threads.

[heading Thread Safety]

Like a regular __Asio__ socket, a
[link beast.ref.boost__beast__websocket__stream `stream`]
is not thread safe. Callers are responsible for synchronizing operations on
the socket using an implicit or explicit strand, as per the Asio documentation.
The websocket stream asynchronous interface supports one of each of the
following operations to be active at the same time:

* [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`]

For example, the following code is produces undefined behavior, because the
program is attempting to perform two simultaneous reads:

[code_websocket_8_2]

However, this code is correct:

[code_websocket_8_3]

The implementation uses composed asynchronous operations; although
some individual operations can perform both reads and writes, this
behavior is coordinated internally to make sure the underlying stream
is operated in a safe fashion. This allows an asynchronous read operation
to respond to a received ping frame even while a user-initiated call to
asynchronous write is active.

[endsect]