76 lines
3.2 KiB
Plaintext
76 lines
3.2 KiB
Plaintext
[/
|
|
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]
|