mirror of
https://github.com/boostorg/beast.git
synced 2025-07-29 20:37:31 +02:00
Update networking refresher doc
This commit is contained in:
Vinnie Falco
@ -1,3 +1,9 @@
|
||||
Version 203
|
||||
|
||||
* Update networking refresher doc
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
Version 202
|
||||
|
||||
* Use cxxstd instead of cxxflags
|
||||
|
||||
@ -31,55 +31,66 @@
|
||||
[template issue[n] '''<ulink url="https://github.com/boostorg/beast/issues/'''[n]'''">#'''[n]'''</ulink>''']
|
||||
|
||||
[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`]]
|
||||
|
||||
@ -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 <boost/asio/io_context.hpp>
|
||||
namespace net = boost::asio;
|
||||
net::io_context ioc;
|
||||
```
|
||||
]
|
||||
][
|
||||
[[@https://think-async.com/Asio/ Asio (Standalone)]]
|
||||
[
|
||||
```
|
||||
#include <asio/io_context.hpp>
|
||||
namespace net = asio;
|
||||
net::io_context ioc;
|
||||
```
|
||||
]
|
||||
][
|
||||
[[@https://github.com/chriskohlhoff/networking-ts-impl networking-ts-impl]]
|
||||
[
|
||||
```
|
||||
#include <experimental/io_context>
|
||||
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]
|
||||
|
||||
@ -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<tcp::socket>`]
|
||||
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<tcp::socket>`]
|
||||
which is already connected with a remote host.
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
200
doc/qbk/03_core/1_refresher.qbk
Normal file
200
doc/qbk/03_core/1_refresher.qbk
Normal file
@ -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<tcp::socket>`]
|
||||
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<tcp::socket>`]
|
||||
which is already connected with a remote host.
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
@ -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
|
||||
|
||||
@ -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<class AsyncStream, class Handler>
|
||||
template <class AsyncStream, class Handler>
|
||||
class echo_op
|
||||
{
|
||||
// This holds all of the state information required by the operation.
|
||||
|
||||
@ -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"
|
||||
(<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html">P1322R0</a>).
|
||||
|
||||
@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"
|
||||
(<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html">P1322R0</a>).
|
||||
*/
|
||||
template<class Protocol, class Executor>
|
||||
class basic_stream_socket
|
||||
|
||||
Reference in New Issue
Block a user