diff --git a/CHANGELOG.md b/CHANGELOG.md index c679e9a8..3afde32c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +Version 203 + +* Update networking refresher doc + +-------------------------------------------------------------------------------- + Version 202 * Use cxxstd instead of cxxflags diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index c68a8bd7..eba055ff 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -31,55 +31,66 @@ [template issue[n] '''#'''[n]''''''] [def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]] -[def __NetTS__ [@http://cplusplus.github.io/networking-ts/draft.pdf [*Networking.TS]]] +[def __NetTS__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/n4771.pdf Networking TS]] [def __rfc6455__ [@https://tools.ietf.org/html/rfc6455 rfc6455]] [def __rfc7230__ [@https://tools.ietf.org/html/rfc7230 rfc7230]] [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]] [def __async_initfn__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html initiating function]] +[/ Networking Identifiers ] + [def __asio_handler_allocate__ [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]] [def __asio_handler_invoke__ [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]] +[def __const_buffer__ [@boost:/doc/html/boost_asio/reference/const_buffer.html `const_buffer`]] [def __deduced__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]] [def __executor_work_guard__ [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `net::executor_work_guard`]] [def __get_associated_allocator__ [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `net::get_associated_allocator`]] [def __get_associated_executor__ [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `net::get_associated_executor`]] [def __io_context__ [@boost:/doc/html/boost_asio/reference/io_context.html `net::io_context`]] +[def __mutable_buffer__ [@boost:/doc/html/boost_asio/reference/mutable_buffer.html `mutable_buffer`]] [def __post__ [@boost:/doc/html/boost_asio/reference/post.html `net::post`]] [def __socket__ [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`]] +[def __strand__ [@boost:/doc/html/boost_asio/reference/strand.html `net::strand`]] [def __ssl_context__ [@boost:/doc/html/boost_asio/reference/ssl__context.html `net::ssl::context`]] [def __ssl_stream__ [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream`]] [def __streambuf__ [@boost:/doc/html/boost_asio/reference/streambuf.html `net::streambuf`]] [def __use_future__ [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future`]] [def __yield_context__ [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`]] -[def __AsyncReadStream__ [@boost:/doc/html/boost_asio/reference/AsyncReadStream.html [*AsyncReadStream]]] -[def __AsyncWriteStream__ [@boost:/doc/html/boost_asio/reference/AsyncWriteStream.html [*AsyncWriteStream]]] -[def __CompletionHandler__ [@boost:/doc/html/boost_asio/reference/CompletionHandler.html [*CompletionHandler]]] -[def __CompletionCondition__ [@boost:/doc/html/boost_asio/reference/CompletionCondition.html [*CompletionCondition]]] -[def __ConnectCondition__ [@boost:/doc/html/boost_asio/reference/ConnectCondition.html [*ConnectCondition]]] -[def __ConstBufferSequence__ [@boost:/doc/html/boost_asio/reference/ConstBufferSequence.html [*ConstBufferSequence]]] -[def __EndpointSequence__ [@boost:/doc/html/boost_asio/reference/EndpointSequence.html [*EndpointSequence]]] -[def __Executor__ [@boost:/doc/html/boost_asio/reference/Executor1.html [*Executor]]] -[def __Handler__ [@boost:/doc/html/boost_asio/reference/Handler.html [*Handler]]] -[def __IteratorConnectHandler__ [@boost:/doc/html/boost_asio/reference/IteratorConnectHandler.html [*IteratorConnectHandler]]] -[def __MutableBufferSequence__ [@boost:/doc/html/boost_asio/reference/MutableBufferSequence.html [*MutableBufferSequence]]] -[def __Protocol__ [@boost:/doc/html/boost_asio/reference/Protocol.html [*Protocol]]] -[def __RangeConnectHandler__ [@boost:/doc/html/boost_asio/reference/RangeConnectHandler.html [*RangeConnectHandler]]] -[def __ReadHandler__ [@boost:/doc/html/boost_asio/reference/ReadHandler.html [*ReadHandler]]] -[def __SyncReadStream__ [@boost:/doc/html/boost_asio/reference/SyncReadStream.html [*SyncReadStream]]] -[def __SyncWriteStream__ [@boost:/doc/html/boost_asio/reference/SyncWriteStream.html [*SyncWriteStream]]] -[def __WriteHandler__ [@boost:/doc/html/boost_asio/reference/WriteHandler.html [*WriteHandler]]] +[/ Networking Named Requirements] -[def __AsyncStream__ [link beast.concepts.streams.AsyncStream [*AsyncStream]]] -[def __Body__ [link beast.concepts.Body [*Body]]] -[def __BodyReader__ [link beast.concepts.BodyReader [*BodyReader]]] -[def __BodyWriter__ [link beast.concepts.BodyWriter [*BodyWriter]]] -[def __DynamicBuffer__ [link beast.concepts.DynamicBuffer [*DynamicBuffer]]] -[def __Fields__ [link beast.concepts.Fields [*Fields]]] -[def __FieldsWriter__ [link beast.concepts.FieldsWriter [*FieldsWriter]]] -[def __File__ [link beast.concepts.File [*File]]] -[def __Stream__ [link beast.concepts.streams [*Stream]]] -[def __SyncStream__ [link beast.concepts.streams.SyncStream [*SyncStream]]] +[def __AsyncReadStream__ [@boost:/doc/html/boost_asio/reference/AsyncReadStream.html ['AsyncReadStream]]] +[def __AsyncWriteStream__ [@boost:/doc/html/boost_asio/reference/AsyncWriteStream.html ['AsyncWriteStream]]] +[def __CompletionHandler__ [@boost:/doc/html/boost_asio/reference/CompletionHandler.html ['CompletionHandler]]] +[def __CompletionCondition__ [@boost:/doc/html/boost_asio/reference/CompletionCondition.html ['CompletionCondition]]] +[def __ConnectCondition__ [@boost:/doc/html/boost_asio/reference/ConnectCondition.html ['ConnectCondition]]] +[def __ConstBufferSequence__ [@boost:/doc/html/boost_asio/reference/ConstBufferSequence.html ['ConstBufferSequence]]] +[def __EndpointSequence__ [@boost:/doc/html/boost_asio/reference/EndpointSequence.html ['EndpointSequence]]] +[def __Executor__ [@boost:/doc/html/boost_asio/reference/Executor1.html ['Executor]]] +[def __Handler__ [@boost:/doc/html/boost_asio/reference/Handler.html ['Handler]]] +[def __IteratorConnectHandler__ [@boost:/doc/html/boost_asio/reference/IteratorConnectHandler.html ['IteratorConnectHandler]]] +[def __MutableBufferSequence__ [@boost:/doc/html/boost_asio/reference/MutableBufferSequence.html ['MutableBufferSequence]]] +[def __Protocol__ [@boost:/doc/html/boost_asio/reference/Protocol.html ['Protocol]]] +[def __RangeConnectHandler__ [@boost:/doc/html/boost_asio/reference/RangeConnectHandler.html ['RangeConnectHandler]]] +[def __ReadHandler__ [@boost:/doc/html/boost_asio/reference/ReadHandler.html ['ReadHandler]]] +[def __SyncReadStream__ [@boost:/doc/html/boost_asio/reference/SyncReadStream.html ['SyncReadStream]]] +[def __SyncWriteStream__ [@boost:/doc/html/boost_asio/reference/SyncWriteStream.html ['SyncWriteStream]]] +[def __WriteHandler__ [@boost:/doc/html/boost_asio/reference/WriteHandler.html ['WriteHandler]]] + +[/ Beast Named Requirements ] + +[def __AsyncStream__ [link beast.concepts.streams.AsyncStream ['AsyncStream]]] +[def __Body__ [link beast.concepts.Body ['Body]]] +[def __BodyReader__ [link beast.concepts.BodyReader ['BodyReader]]] +[def __BodyWriter__ [link beast.concepts.BodyWriter ['BodyWriter]]] +[def __DynamicBuffer__ [link beast.concepts.DynamicBuffer ['DynamicBuffer]]] +[def __Fields__ [link beast.concepts.Fields ['Fields]]] +[def __FieldsWriter__ [link beast.concepts.FieldsWriter ['FieldsWriter]]] +[def __File__ [link beast.concepts.File ['File]]] +[def __Stream__ [link beast.concepts.streams ['Stream]]] +[def __SyncStream__ [link beast.concepts.streams.SyncStream ['SyncStream]]] + +[/ Beast Identifiers ] [def __basic_fields__ [link beast.ref.boost__beast__http__basic_fields `basic_fields`]] [def __basic_multi_buffer__ [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]] diff --git a/doc/qbk/03_core.qbk b/doc/qbk/03_core.qbk index 24ba3400..5a823423 100644 --- a/doc/qbk/03_core.qbk +++ b/doc/qbk/03_core.qbk @@ -7,29 +7,92 @@ Official repository: https://github.com/boostorg/beast ] -[section:using_io Using Core Facilities] +[section:using_io Using Networking] -This library makes I/O primitives used by the implementation publicly -available so users can take advantage of them in their own libraries. -These primitives include traits, buffers, buffer algorithms, files, -and helpers for implementing asynchronous operations compatible with -__Asio__ and described in __N3747__. This section lists these facilities -by group, with descriptions. +This library depends and builds on the networking facilities destined to become +part of the official C++ standard library. The latest draft of the proposal to +add these networking facilities is called the +[@http://cplusplus.github.io/networking-ts/draft.pdf Networking Technical Specification]. +This specification is projected to become official no sooner than the year +2023. There are three implementations of this specification, which differ +cosmetically but otherwise use the same function signatures and type +declarations: the reference networking-ts implementation, the Boost.Asio +implementation, and the stand-alone Asio implementation. The following +table illustrates shows how an I/O context variable is declared by including +the appropriate header and using a suitable namespace alias: -[section Aliases and Abbreviations] - -[important - This documentation assumes familiarity with __Asio__. Sample - code and identifiers used throughout are written as if the - following declarations are in effect: - - [snippet_core_1a] - [snippet_core_1b] +[table Networking Implementations +[[Name][Namespace and Header Example ]] +[ + [__Asio__] + [ +``` + #include + namespace net = boost::asio; + net::io_context ioc; +``` + ] +][ + [[@https://think-async.com/Asio/ Asio (Standalone)]] + [ +``` + #include + namespace net = asio; + net::io_context ioc; +``` + ] +][ + [[@https://github.com/chriskohlhoff/networking-ts-impl networking-ts-impl]] + [ +``` + #include + namespace net = std::experimental::net; + net::io_context ioc; +``` + ] +] ] -[endsect] +This document refers to the three implementations above interchangeably and +collectively as "networking." The Boost.Asio and Asio flavors of networking +provide additional functionality which is not currently proposed for C++ (but +will likely appear in a future specification). Examples of functionality +in Boost.Asio not present in the proposed networking draft include support for: -[include 03_core/1_asio.qbk] +* [@boost:/doc/html/boost_asio/reference/serial_port.html Serial ports] +* [@boost:/doc/html/boost_asio/reference/local__stream_protocol.html UNIX domain sockets] +* [@boost:/doc/html/boost_asio/reference/signal_set.html POSIX signals] (e.g. SIGINT, SIGABORT) +* [@boost:/doc/html/boost_asio/reference/ssl__stream.html TLS streams] (such as OpenSSL) + +In this documentation, the example code, and the implementation, the `net` +namespace is used to qualify networking identifiers. For Boost.Beast, +`net` will be an alias for the `boost::asio` namespace. + +While this library offers performant implementations of the HTTP and +WebSocket network protocols, it depends on the networking interface +to perform tasks which are not specific to the protocol. Examples of +these tasks include performing domain name resolution (DNS lookup), +establishing outgoing connections, and accepting incoming connections. +Callers are responsible for interacting with networking to initialize +objects to the correct state where they are usable by this library. + +To facilitiate interacting with networking, the library provides an +extensive collection of types and algorithms. This section of the +documentation explains these types and algorithms, provides examples +of usage, and also provides refreshers and tutorials for working with +networking. + +[heading Abbreviations] + +This documentation assumes familiarity with __Asio__, which is +required to work with Beast. Sample code and identifiers used +throughout are written as if the following declarations are in +effect: + +[snippet_core_1a] +[snippet_core_1b] + +[include 03_core/1_refresher.qbk] [include 03_core/2_streams.qbk] [include 03_core/3_buffers.qbk] [include 03_core/4_files.qbk] diff --git a/doc/qbk/03_core/1_asio.qbk b/doc/qbk/03_core/1_asio.qbk deleted file mode 100644 index 5149c387..00000000 --- a/doc/qbk/03_core/1_asio.qbk +++ /dev/null @@ -1,61 +0,0 @@ -[/ - Copyright (c) 2016-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) - - Official repository: https://github.com/boostorg/beast -] - -[section:asio_refresher Networking Refresher] - -[warning - Beast does not manage sockets, make outgoing connections, - accept incoming connections, handle timeouts, close endpoints, - do name lookups, deal with TLS certificates, perform authentication, - or otherwise handle any aspect of connection management. This is - left to the interfaces already existing on the underlying streams. -] - -Library stream algorithms require a __socket__, __ssl_stream__, or other -__Stream__ object that has already established communication with a remote -peer. This example is provided as a reminder of how to work with -sockets: - -[snippet_core_2] - -Throughout this documentation identifiers with the following names have -special meaning: - -[table Global Variables -[[Name][Description]] -[[ - [@boost:/doc/html/boost_asio/reference/io_context.html [*`ioc`]] -][ - A variable of type __io_context__ which is running on one separate thread, - and upon which an __executor_work_guard__ object has been constructed. -]] -[[ - [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]] -][ - A variable of type - [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`] - which has already been connected to a remote host. -]] -[[ - [@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]] -][ - A variable of type - [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream`] - which is already connected and has handshaked with a remote host. -]] -[[ - [link beast.ref.boost__beast__websocket__stream [*`ws`]] -][ - A variable of type - [link beast.ref.boost__beast__websocket__stream `websocket::stream`] - which is already connected with a remote host. -]] -] - -[endsect] diff --git a/doc/qbk/03_core/1_refresher.qbk b/doc/qbk/03_core/1_refresher.qbk new file mode 100644 index 00000000..47ffdef1 --- /dev/null +++ b/doc/qbk/03_core/1_refresher.qbk @@ -0,0 +1,200 @@ +[/ + Copyright (c) 2016-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) + + Official repository: https://github.com/boostorg/beast +] + +[section:asio_refresher Refresher] + +To use Beast effectively, a prior understanding of networking is required. +This section reviews networking concepts as a reminder and guide for further +learning. + +A +['network] +allows programs located anywhere to exchange information after opting-in +to communications by establishing a +['connection]. +Data is reliably transferred on a connection in either direction (full-duplex) +with bytes arriving in the same order they were sent. These connections, along +with the objects and types used to represent them, are collectively termed +['streams]. + +The +['internet] +is a global network of interconnected computers which exchange information +using a variety of standardized communication protocols. The most popular +protocol is +['TCP/IP], +which this library relies on exclusively. The protocol takes care of the +low level details so that applications see a +['stream], +which is the reliable, full-duplex connection carrying the ordered set +of bytes described above. + +A vendor supplies a program called a +['driver], +enabling networking hardware such as an +['ethernet adaptor] +to talk to the operating system. The OS in turn permits running programs to +interact with networking using various flavors of interfaces, such as: + +* Berkeley sockets +* POSIX sockets +* Windows Sockets 2 ("Winsock") + +C++ Networking, represented by __NetTS__ and __Asio__, provides another layer +of abstraction with features such as: + +* Deadline timers +* Buffer sequences +* Stream concepts +* Asynchronous I/O + +These concepts enable generic programming so that higher levels of abstraction +may be composed to arbitrary degree. In fact, the interfaces and concepts +offered by networking are best described as providing support for general +input and output algorithms ("I/O"), including TCP/IP. + +[heading Buffers] + +A +['buffer] +holds a contiguous sequence of bytes used to perform reads or writes on an +['I/O object]. +The networking types __const_buffer__ and __mutable_buffer__ represent +these memory regions as type-safe pointer/size pairs. The concepts +__ConstBufferSequence__ and __MutableBufferSequence__ are bidirectional +ranges whose value type is convertible to __const_buffer__ and +__mutable_buffer__ respectively. Buffer sequences may be used to transact +in multiple buffers in a single function call. These types are non-owning; +copying a buffer or buffer sequences only creates a shallow reference, +it does allocate a copy of the contents. + +Buffers described thus far may not be resized. The __DynamicBuffer__ +concept defines a storage type whose size can change. Beast uses +dynamic buffers in interfaces where the amount of storage required +to complete an operation is not known ahead of time. + + + + [/ [heading Synchronous I/O] ] + + + +[heading Asynchronous I/O] + +An asynchronous operation starts with a call to an +['initiating function], +whose name begins with the prefix `async_`. The initating function +allocates memory as needed, possibly capturing arguments, then +launches the operation before returning to the caller immediately. +The operation is now +['outstanding], +making progress without blocking the caller. + +The result of the operation is +['available] +when the externally observable side effects are fully established. +A movable function object known as a +['completion handler] +(provided to the initiating function) is then invoked with the result. +A completion handler is also referred to as a +['continuation], +since it represents a continuation of the flow of execution that +started from the initiating function call. +Temporary storage required to perform an operation may be allocated using +the completion handler's +['associated allocator], +which can optionally be suggested by the caller. These allocations +[*must] be freed before the completion handler is invoked. + +Networking provides well-defined facilities for determining the context +where handlers run. Every I/O object is associated with an +['ExecutionContext], +which permits implementations to store private per-context data and +also supplies instances of its +['Executor] that determines where and how a handler is invoked in the +exection context. Instances of __io_context__ offer the basic execution +guarantee: handlers will only be executed from caller-provided threads +which are currently invoking +[@boost:/doc/html/boost_asio/reference/io_context/run/overload1.html `net::io_context::run`]. + +An +['associated executor] +is defined for every completion handler, which defaults to the I/O +object's executor. The executor for a completion handler may be +customized, for example by choosing a __strand__. A strand provides an +additional execution guarantee: function objects submitted to the strand +are never executed concurrently by the underlying executor. Strands permit +concurrent asynchronous applications to be developed which do not require +explicit locking. + +[/ + [heading Concurrency Without Locking] + + multiple threads calling io_context::run + + When a composed operation submits intermediate completion handlers for operations used to meet its stated effects, the intermediate handlers must use the same executor as that used for the final completion handler + This is to avoid accessing the underlying I/O object in ways that violate preconditions + + [heading Universal Asynchronous Model] + + The use of invocable function objects +] + + + +[warning + Beast does not manage sockets, make outgoing connections, + accept incoming connections, handle timeouts, close endpoints, + do name lookups, deal with TLS certificates, perform authentication, + or otherwise handle any aspect of connection management. This is + left to the interfaces already existing on the underlying streams. +] + +Library stream algorithms require a __socket__, __ssl_stream__, or other +__Stream__ object that has already established communication with a remote +peer. This example is provided as a reminder of how to work with +sockets: + +[snippet_core_2] + +Throughout this documentation identifiers with the following names have +special meaning: + +[table Global Variables +[[Name][Description]] +[[ + [@boost:/doc/html/boost_asio/reference/io_context.html [*`ioc`]] +][ + A variable of type __io_context__ which is running on one separate thread, + and upon which an __executor_work_guard__ object has been constructed. +]] +[[ + [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]] +][ + A variable of type + [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`] + which has already been connected to a remote host. +]] +[[ + [@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]] +][ + A variable of type + [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream`] + which is already connected and has handshaked with a remote host. +]] +[[ + [link beast.ref.boost__beast__websocket__stream [*`ws`]] +][ + A variable of type + [link beast.ref.boost__beast__websocket__stream `websocket::stream`] + which is already connected with a remote host. +]] +] + +[endsect] diff --git a/doc/qbk/08_design.qbk b/doc/qbk/08_design.qbk index c1e15e4b..f8070fd8 100644 --- a/doc/qbk/08_design.qbk +++ b/doc/qbk/08_design.qbk @@ -26,8 +26,8 @@ flaws exhibited by other libraries: * Leave important decisions, such as allocating memory or managing flow control, to the user. -Beast uses the __DynamicBuffer__ concept presented in the Networking TS -(__NetTS__), and relies heavily on the __ConstBufferSequence__ and +Beast uses the __DynamicBuffer__ concept presented in the __NetTS__, +and relies heavily on the __ConstBufferSequence__ and __MutableBufferSequence__ concepts for passing buffers to functions. The authors have found the dynamic buffer and buffer sequence interfaces to be optimal for interacting with Asio, and for other tasks such as incremental diff --git a/example/echo-op/echo_op.cpp b/example/echo-op/echo_op.cpp index 90f86493..363df50c 100644 --- a/example/echo-op/echo_op.cpp +++ b/example/echo-op/echo_op.cpp @@ -20,7 +20,7 @@ template< class AsyncStream, class CompletionToken> auto -async_echo(AsyncStream& stream, CompletionToken&& token) +async_echo (AsyncStream& stream, CompletionToken&& token) //] -> BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, void(boost::beast::error_code)); @@ -68,8 +68,8 @@ template< class CompletionToken> BOOST_ASIO_INITFN_RESULT_TYPE( /*< `BOOST_ASIO_INITFN_RESULT_TYPE` customizes the return value based on the completion token >*/ CompletionToken, - void(boost::beast::error_code)) /*< This is the signature for the completion handler >*/ -async_echo( + void (boost::beast::error_code)) /*< This is the signature for the completion handler >*/ +async_echo ( AsyncStream& stream, CompletionToken&& token); @@ -79,7 +79,7 @@ async_echo( // This composed operation reads a line of input and echoes it back. // -template +template class echo_op { // This holds all of the state information required by the operation. diff --git a/include/boost/beast/core/basic_stream_socket.hpp b/include/boost/beast/core/basic_stream_socket.hpp index 398fc08c..4b2cb63b 100644 --- a/include/boost/beast/core/basic_stream_socket.hpp +++ b/include/boost/beast/core/basic_stream_socket.hpp @@ -27,14 +27,15 @@ namespace boost { namespace beast { -/** A stream socket wrapper with integrated timeout and bandwidth management. +/** A stream socket with integrated timeout and bandwidth management. - This wraps a normal stream socket to provide the following additional - features: + This stream socket adapts a `net::basic_stream_socket` to provide + the following additional features: @li The class template is parameterized on a user-defined executor used for asynchronous operations. This achieves partial support for - "Networking TS enhancement to enable custom I/O executors" [P1322R0]. + "Networking TS enhancement to enable custom I/O executors" + (P1322R0). @li Optional timeouts may be specified for logical operations which perform asynchronous reads, writes, and connects. @@ -73,7 +74,8 @@ namespace beast { necessary to also bind each submitted completion handler used in subsequent operations to the strand, this is taken care of automatically. - @par Using Executors + @par Associated Executor + @par Using Timeouts @@ -149,7 +151,8 @@ namespace beast { that all asynchronous operations are performed within the same implicit or explicit strand. - @see http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html + @see "Networking TS enhancement to enable custom I/O executors" + (P1322R0). */ template class basic_stream_socket