forked from boostorg/beast
70 lines
2.6 KiB
Plaintext
70 lines
2.6 KiB
Plaintext
|
[/
|
||
|
|
Copyright (c) 2013-2017 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)
|
||
|
|
]
|
||
|
|
|
||
|
|
[section:notes 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:
|
||
|
|
```
|
||
|
|
websocket::opcode op;
|
||
|
|
ws.async_read(op, sb,
|
||
|
|
[](boost::system::error_code const& ec)
|
||
|
|
{
|
||
|
|
...
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
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:
|
||
|
|
```
|
||
|
|
void echo(websocket::stream<ip::tcp::socket>& ws,
|
||
|
|
boost::asio::yield_context yield)
|
||
|
|
{
|
||
|
|
ws.async_read(sb, yield);
|
||
|
|
std::future<websocket::error_code> fut =
|
||
|
|
ws.async_write, sb.data(), boost::use_future);
|
||
|
|
...
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
[heading The io_service]
|
||
|
|
|
||
|
|
The creation and operation of the __io_service__ 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.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 asynchronous interface supports one active read and one active write
|
||
|
|
simultaneously. Undefined behavior results if two or more reads or two or
|
||
|
|
more writes are attempted concurrently. Caller initiated WebSocket ping, pong,
|
||
|
|
and close operations each count as an active write.
|
||
|
|
|
||
|
|
The implementation uses composed asynchronous operations internally; a high
|
||
|
|
level read can cause both reads and writes to take place on the underlying
|
||
|
|
stream. This behavior is transparent to callers.
|
||
|
|
|
||
|
|
[endsect]
|