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