1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[section Notes] 11 12Because calls to read data may return a variable amount of bytes, the 13interface to calls that read data require an object that meets the requirements 14of __DynamicBuffer__. This concept is modeled on __streambuf__. 15 16The implementation does not perform queueing or buffering of messages. If 17desired, these features should be provided by callers. The impact of this 18design is that library users are in full control of the allocation strategy 19used to store data and the back-pressure applied on the read and write side 20of the underlying TCP/IP connection. 21 22[heading Asynchronous Operations] 23 24Asynchronous versions are available for all functions: 25 26[code_websocket_8_1] 27 28Calls to asynchronous initiation functions support the extensible asynchronous 29model developed by the Boost.Asio author, allowing for traditional completion 30handlers, stackful or stackless coroutines, and even futures: 31 32[code_websocket_8_1f] 33 34The example programs that come with the library demonstrate the usage of 35websocket stream operations with all asynchronous varieties. 36 37[heading The io_context] 38 39The creation and operation of the __io_context__ associated with the 40underlying stream is left to the callers, permitting any implementation 41strategy including one that does not require threads for environments 42where threads are unavailable. Beast WebSocket itself does not use 43or require threads. 44 45[heading Thread Safety] 46 47Like a regular __Asio__ socket, a 48[link beast.ref.boost__beast__websocket__stream `stream`] 49is not thread safe. Callers are responsible for synchronizing operations on 50the socket using an implicit or explicit strand, as per the Asio documentation. 51The websocket stream asynchronous interface supports one of each of the 52following operations to be active at the same time: 53 54* [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`] 55* [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`] 56* [link beast.ref.boost__beast__websocket__stream.async_ping `async_ping`] or [link beast.ref.boost__beast__websocket__stream.async_pong `async_pong`] 57* [link beast.ref.boost__beast__websocket__stream.async_close `async_close`] 58 59For example, the following code is produces undefined behavior, because the 60program is attempting to perform two simultaneous reads: 61 62[code_websocket_8_2] 63 64However, this code is correct: 65 66[code_websocket_8_3] 67 68The implementation uses composed asynchronous operations; although 69some individual operations can perform both reads and writes, this 70behavior is coordinated internally to make sure the underlying stream 71is operated in a safe fashion. This allows an asynchronous read operation 72to respond to a received ping frame even while a user-initiated call to 73asynchronous write is active. 74 75[endsect] 76