mirror of
https://github.com/boostorg/beast.git
synced 2025-07-31 21:34:46 +02:00
Doc fixes and tidying
This commit is contained in:
@@ -38,7 +38,7 @@ 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
|
||||
parsing of data in buffers (for example, parsing websocket frames stored
|
||||
in a [link beast.ref.static_streambuf `static_streambuf`]).
|
||||
in a [link beast.ref.static_buffer `static_buffer`]).
|
||||
|
||||
During the development of Beast the authors have studied other software
|
||||
packages and in particular the comments left during the Boost Review process
|
||||
@@ -98,7 +98,7 @@ start. Other design goals:
|
||||
][
|
||||
We presume this means a facility to match expressions against the URI
|
||||
in HTTP requests, and dispatch them to calling code. The authors feel
|
||||
that this is a responsibility of higher level code. Beast.HTTP does
|
||||
that this is a responsibility of higher level code. Beast does
|
||||
not try to offer a web server.
|
||||
]]
|
||||
|
||||
@@ -118,11 +118,11 @@ start. Other design goals:
|
||||
"...supporting TLS (is this a feature? If not this would be a show-stopper),
|
||||
etc."
|
||||
][
|
||||
Beast.HTTP does not provide direct facilities for implementing TLS
|
||||
connections; however, the interfaces already existing on the
|
||||
`boost::asio::ssl::stream` are available and can be used to establish
|
||||
secure connections. Then, functions like `http::read` or `http::async_write`
|
||||
can work with those encrypted connections with no problem.
|
||||
Beast does not provide direct facilities for implementing TLS connections;
|
||||
however, the interfaces already existing on the `boost::asio::ssl::stream`
|
||||
are available and can be used to establish secure connections. Then,
|
||||
functions like `http::read` or `http::async_write` can work with those
|
||||
encrypted connections with no problem.
|
||||
]]
|
||||
|
||||
[[
|
||||
@@ -143,12 +143,11 @@ start. Other design goals:
|
||||
[[
|
||||
"You should send a 100-continue to ask for the rest of the body if required."
|
||||
][
|
||||
The Beast interface needs to support this functionality (by allowing this
|
||||
The Beast interface supporst this functionality (by allowing this
|
||||
special case of partial message parsing and serialization). Specifically,
|
||||
it should let callers read the request up to just before the body,
|
||||
it lets callers read the request up to just before the body,
|
||||
and let callers write the request up to just before the body. However,
|
||||
making use of this behavior should be up to callers (since Beast is low
|
||||
level).
|
||||
making use of this behavior is up to callers (since Beast is low level).
|
||||
]]
|
||||
|
||||
[[
|
||||
@@ -160,7 +159,7 @@ start. Other design goals:
|
||||
the same network reading and writing interface for 2 as that for 1.0
|
||||
and 1.1.
|
||||
|
||||
The Beast.HTTP message model is suitable for HTTP/2 and can be re-used.
|
||||
The Beast HTTP message model is suitable for HTTP/2 and can be re-used.
|
||||
The IETF HTTP Working Group adopted message compatiblity with HTTP/1.x
|
||||
as an explicit goal. A parser can simply emit full headers after
|
||||
decoding the compressed HTTP/2 headers. The stream ID is not logically
|
||||
|
@@ -238,7 +238,7 @@ used in the examples:
|
||||
```
|
||||
|
||||
* [link beast.ref.http__dynamic_body [*`dynamic_body`:]] A body with a
|
||||
`value_type` of [link beast.ref.streambuf `streambuf`]: an efficient storage
|
||||
`value_type` of [link beast.ref.multi_buffer `multi_buffer`]: an efficient storage
|
||||
object which uses multiple octet arrays of varying lengths to represent data.
|
||||
|
||||
[heading Advanced]
|
||||
@@ -323,7 +323,7 @@ a single byte at a time which is unsuitable for performance reasons). To
|
||||
store and re-use these extra bytes on subsequent messages, the read interface
|
||||
requires an additional parameter: a [link beast.ref.DynamicBuffer [*`DynamicBuffer`]]
|
||||
object. This example reads a message from the socket, with the extra bytes
|
||||
stored in the streambuf parameter for use in a subsequent call to read:
|
||||
stored in the `streambuf` parameter for use in a subsequent call to read:
|
||||
```
|
||||
boost::asio::streambuf sb;
|
||||
...
|
||||
@@ -350,12 +350,12 @@ called:
|
||||
```
|
||||
|
||||
An alternative to using a `boost::asio::streambuf` is to use a
|
||||
__streambuf__, which meets the requirements of __DynamicBuffer__ and
|
||||
__multi_buffer__, which meets the requirements of __DynamicBuffer__ and
|
||||
is optimized for performance:
|
||||
```
|
||||
void handle_read(boost::system::error_code);
|
||||
...
|
||||
beast::streambuf sb;
|
||||
beast::multi_buffer sb;
|
||||
response<string_body> res;
|
||||
read(sock, sb, res);
|
||||
```
|
||||
|
@@ -47,9 +47,10 @@
|
||||
|
||||
[def __basic_fields__ [link beast.ref.http__basic_fields `basic_fields`]]
|
||||
[def __fields__ [link beast.ref.http__fields `fields`]]
|
||||
[def __flat_buffer__ [link beast.ref.flat_buffer `flat_buffer`]]
|
||||
[def __header__ [link beast.ref.http__header `header`]]
|
||||
[def __message__ [link beast.ref.http__message `message`]]
|
||||
[def __streambuf__ [link beast.ref.streambuf `streambuf`]]
|
||||
[def __multi_buffer__ [link beast.ref.multi_buffer `multi_buffer`]]
|
||||
[def __basic_multi_buffer__ [link beast.ref.basic_multi_buffer `basic_multi_buffer`]]
|
||||
|
||||
Beast is a cross-platform, header-only C++ library built on Boost.Asio that
|
||||
|
@@ -20,8 +20,7 @@ implementation strategies:
|
||||
|
||||
* A single contiguous octet array, which is reallocated as necessary to
|
||||
accommodate changes in the size of the octet sequence. This is the
|
||||
implementation approach currently offered by
|
||||
[link beast.ref.basic_flat_streambuf `basic_flat_streambuf`].
|
||||
implementation approach currently offered by __flat_buffer__.
|
||||
|
||||
* A sequence of one or more octet arrays, where each array is of the same
|
||||
size. Additional octet array objects are appended to the sequence to
|
||||
@@ -30,7 +29,7 @@ implementation strategies:
|
||||
* A sequence of one or more octet arrays of varying sizes. Additional octet
|
||||
array objects are appended to the sequence to accommodate changes in the
|
||||
size of the character sequence. This is the implementation approach
|
||||
currently offered by [link beast.ref.basic_streambuf `basic_streambuf`].
|
||||
currently offered by __multi_buffer__.
|
||||
|
||||
In the table below:
|
||||
|
||||
|
@@ -338,7 +338,7 @@ void echo(beast::websocket::stream<boost::asio::ip::tcp::socket>& ws)
|
||||
}
|
||||
ws.set_option(beast::websocket::message_type{fi.op});
|
||||
beast::consuming_buffers<
|
||||
beast::streambuf::const_buffers_type> cb{b.data()};
|
||||
beast::multi_buffer::const_buffers_type> cb{b.data()};
|
||||
for(;;)
|
||||
{
|
||||
using boost::asio::buffer_size;
|
||||
@@ -475,7 +475,7 @@ the fragments:
|
||||
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 [link beast.ref.DynamicBuffer [*`DynamicBuffer`]]. This concept is modeled on
|
||||
[@http://www.boost.org/doc/libs/1_61_0/doc/html/boost_asio/reference/basic_streambuf.html `boost::asio::basic_streambuf`].
|
||||
[@http://www.boost.org/doc/libs/1_64_0/doc/html/boost_asio/reference/basic_streambuf.html `boost::asio::basic_streambuf`].
|
||||
|
||||
The implementation does not perform queueing or buffering of messages. If
|
||||
desired, these features should be provided by callers. The impact of this
|
||||
|
Reference in New Issue
Block a user