feedc0de/boost_beast
1
0
Fork 0
forked from boostorg/beast
Code Pull Requests Activity

Doc fixes and tidying

Browse Source
This commit is contained in:
Vinnie Falco
2017-05-05 12:34:36 -07:00
parent fc0e356149
commit f50a37b778
5 changed files with 21 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
doc/design.qbk
View File

@@ -38,7 +38,7 @@ and __MutableBufferSequence__ concepts for passing buffers to functions.
The authors have found the dynamic buffer and buffer sequence interfaces to 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 be optimal for interacting with Asio, and for other tasks such as incremental
parsing of data in buffers (for example, parsing websocket frames stored 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 During the development of Beast the authors have studied other software
packages and in particular the comments left during the Boost Review process 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 We presume this means a facility to match expressions against the URI
in HTTP requests, and dispatch them to calling code. The authors feel 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. 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), "...supporting TLS (is this a feature? If not this would be a show-stopper),
etc." etc."
][ ][
Beast.HTTP does not provide direct facilities for implementing TLS Beast does not provide direct facilities for implementing TLS connections;
connections; however, the interfaces already existing on the however, the interfaces already existing on the `boost::asio::ssl::stream`
`boost::asio::ssl::stream` are available and can be used to establish are available and can be used to establish secure connections. Then,
secure connections. Then, functions like `http::read` or `http::async_write` functions like `http::read` or `http::async_write` can work with those
can work with those encrypted connections with no problem. 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." "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, 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, 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 making use of this behavior is up to callers (since Beast is low level).
level).
]] ]]
[[ [[
@@ -160,7 +159,7 @@ start. Other design goals:
the same network reading and writing interface for 2 as that for 1.0 the same network reading and writing interface for 2 as that for 1.0
and 1.1. 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 The IETF HTTP Working Group adopted message compatiblity with HTTP/1.x
as an explicit goal. A parser can simply emit full headers after as an explicit goal. A parser can simply emit full headers after
decoding the compressed HTTP/2 headers. The stream ID is not logically decoding the compressed HTTP/2 headers. The stream ID is not logically

8
doc/http.qbk
View File

@@ -238,7 +238,7 @@ used in the examples:
``` ```
* [link beast.ref.http__dynamic_body [*`dynamic_body`:]] A body with a * [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. object which uses multiple octet arrays of varying lengths to represent data.
[heading Advanced] [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 store and re-use these extra bytes on subsequent messages, the read interface
requires an additional parameter: a [link beast.ref.DynamicBuffer [*`DynamicBuffer`]] requires an additional parameter: a [link beast.ref.DynamicBuffer [*`DynamicBuffer`]]
object. This example reads a message from the socket, with the extra bytes 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; boost::asio::streambuf sb;
... ...
@@ -350,12 +350,12 @@ called:
``` ```
An alternative to using a `boost::asio::streambuf` is to use a 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: is optimized for performance:
``` ```
void handle_read(boost::system::error_code); void handle_read(boost::system::error_code);
... ...
beast::streambuf sb; beast::multi_buffer sb;
response<string_body> res; response<string_body> res;
read(sock, sb, res); read(sock, sb, res);
``` ```

3
doc/master.qbk
View File

@@ -47,9 +47,10 @@
[def __basic_fields__ [link beast.ref.http__basic_fields `basic_fields`]] [def __basic_fields__ [link beast.ref.http__basic_fields `basic_fields`]]
[def __fields__ [link beast.ref.http__fields `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 __header__ [link beast.ref.http__header `header`]]
[def __message__ [link beast.ref.http__message `message`]] [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`]] [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 Beast is a cross-platform, header-only C++ library built on Boost.Asio that

5
doc/types/DynamicBuffer.qbk
View File

@@ -20,8 +20,7 @@ implementation strategies:
* A single contiguous octet array, which is reallocated as necessary to * A single contiguous octet array, which is reallocated as necessary to
accommodate changes in the size of the octet sequence. This is the accommodate changes in the size of the octet sequence. This is the
implementation approach currently offered by implementation approach currently offered by __flat_buffer__.
[link beast.ref.basic_flat_streambuf `basic_flat_streambuf`].
* A sequence of one or more octet arrays, where each array is of the same * 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 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 * 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 array objects are appended to the sequence to accommodate changes in the
size of the character sequence. This is the implementation approach 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: In the table below:

4
doc/websocket.qbk
View File

@@ -338,7 +338,7 @@ void echo(beast::websocket::stream<boost::asio::ip::tcp::socket>& ws)
} }
ws.set_option(beast::websocket::message_type{fi.op}); ws.set_option(beast::websocket::message_type{fi.op});
beast::consuming_buffers< beast::consuming_buffers<
beast::streambuf::const_buffers_type> cb{b.data()}; beast::multi_buffer::const_buffers_type> cb{b.data()};
for(;;) for(;;)
{ {
using boost::asio::buffer_size; using boost::asio::buffer_size;
@@ -475,7 +475,7 @@ the fragments:
Because calls to read data may return a variable amount of bytes, the 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 interface to calls that read data require an object that meets the requirements
of [link beast.ref.DynamicBuffer [*`DynamicBuffer`]]. This concept is modeled on 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 The implementation does not perform queueing or buffering of messages. If
desired, these features should be provided by callers. The impact of this desired, these features should be provided by callers. The impact of this