diff --git a/doc/beast.qbk b/doc/beast.qbk index ffb0b52f..d5856382 100644 --- a/doc/beast.qbk +++ b/doc/beast.qbk @@ -191,8 +191,15 @@ supporting its development. [include websocket.qbk] [section:types Type Requirements] -[include core_types.qbk] -[include http_types.qbk] +[include types/Body.qbk] +[include types/BufferSequence.qbk] +[include types/Field.qbk] +[include types/FieldSequence.qbk] +[include types/Parser.qbk] +[include types/Reader.qbk] +[include types/Streambuf.qbk] +[include types/Streams.qbk] +[include types/Writer.qbk] [endsect] [include design.qbk] diff --git a/doc/quickref.xml b/doc/quickref.xml index 20562e03..753e5996 100644 --- a/doc/quickref.xml +++ b/doc/quickref.xml @@ -47,8 +47,10 @@ Functions + async_parse async_read async_write + parse prepare read write @@ -62,6 +64,7 @@ Body Field FieldSequence + Parser Reader Writer @@ -163,10 +166,10 @@ Concepts BufferSequence - AsyncStream - Stream + AsyncStream + Stream Streambuf - SyncStream + SyncStream diff --git a/doc/reference.xsl b/doc/reference.xsl index f57b3291..0824f077 100644 --- a/doc/reference.xsl +++ b/doc/reference.xsl @@ -1528,7 +1528,7 @@ - class ``[link beast.types.stream.AsyncStream [*AsyncStream]]`` + class ``[link beast.types.streams.AsyncStream [*AsyncStream]]`` class ``[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*AsyncReadStream]]`` @@ -1556,13 +1556,13 @@ class ``[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*MutableBufferSequence]]`` - class ``[link beast.types.stream.Stream [*Stream]]`` + class ``[link beast.types.streams.Stream [*Stream]]`` class ``[link beast.types.Streambuf [*Streambuf]]`` - class ``[link beast.types.stream.SyncStream [*SyncStream]]`` + class ``[link beast.types.streams.SyncStream [*SyncStream]]`` class ``[@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*SyncReadStream]]`` diff --git a/doc/types/Body.qbk b/doc/types/Body.qbk new file mode 100644 index 00000000..95c91417 --- /dev/null +++ b/doc/types/Body.qbk @@ -0,0 +1,50 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:Body Body] + +In this table: + +* `X` is a type meeting the requirements of [*`Body`]. + +[table Body requirements +[[operation] [type] [semantics, pre/post-conditions]] +[ + [`X::value_type`] + [] + [ + The type of the `message::body` member. + If this is not movable or not copyable, the containing message + will be not movable or not copyable. + ] +] +[ + [`X:value_type{}`] + [] + [`DefaultConstructible`] +] +[ + [`Body::reader`] + [] + [ + If present, a type meeting the requirements of + [link beast.types.Reader [*`Reader`]]. + Provides an implementation to parse the body. + ] +] +[ + [`Body::writer`] + [] + [ + If present, a type meeting the requirements of + [link beast.types.Writer [*`Writer`]]. + Provides an implementation to serialize the body. + ] +] +] + +[endsect] diff --git a/doc/types/BufferSequence.qbk b/doc/types/BufferSequence.qbk new file mode 100644 index 00000000..e6206bd7 --- /dev/null +++ b/doc/types/BufferSequence.qbk @@ -0,0 +1,15 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:BufferSequence BufferSequence] + +A `BufferSequence` is a type meeting either of the following requirements: + +* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]] +* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]] + +[endsect] diff --git a/doc/types/Field.qbk b/doc/types/Field.qbk new file mode 100644 index 00000000..a83309a1 --- /dev/null +++ b/doc/types/Field.qbk @@ -0,0 +1,41 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:Field Field] + +A [*`Field`] represents a single HTTP header field/value pair. + +In this table: + +* `X` denotes a type meeting the requirements of [*`Field`]. +* `a` denotes a value of type `X`. + +[table Field requirements + +[[operation][type][semantics, pre/post-conditions]] +[ + [`a.name()`] + [`boost::string_ref`] + [ + This function returns a value implicitly convertible to + `boost::string_ref` containing the case-insensitve field + name, without leading or trailing white space. + ] +] +[ + [`a.value()`] + [`boost::string_ref`] + [ + This function returns a value implicitly convertible to + `boost::string_ref` containing the value for the field. The + value is considered canonical if there is no leading or + trailing whitespace. + ] +] +] + +[endsect] diff --git a/doc/types/FieldSequence.qbk b/doc/types/FieldSequence.qbk new file mode 100644 index 00000000..c0cd123b --- /dev/null +++ b/doc/types/FieldSequence.qbk @@ -0,0 +1,51 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:FieldSequence FieldSequence] + +A [*`FieldSequence`] is an iterable container whose value type meets +the requirements of [link beast.types.Field [*`Field`]]. + +In this table: + +* `X` denotes a type that meets the requirements of [*`FieldSequence`]. + +* `a` is a value of type `X`. + +[table FieldSequence requirements +[[operation][type][semantics, pre/post-conditions]] +[ + [`X::value_type`] + [] + [ + A type that meets the requirements of `Field`. + ] +] +[ + [`X::const_iterator`] + [] + [ + A type that meets the requirements of `ForwardIterator`. + ] +] +[ + [`a.begin()`] + [`X::const_iterator`] + [ + Returns an iterator to the beginning of the field sequence. + ] +] +[ + [`a.end()`] + [`X::const_iterator`] + [ + Returns an iterator to the end of the field sequence. + ] +] +] + +[endsect] diff --git a/doc/types/Parser.qbk b/doc/types/Parser.qbk new file mode 100644 index 00000000..43d0cb46 --- /dev/null +++ b/doc/types/Parser.qbk @@ -0,0 +1,58 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:Parser Parser] + +A [*`Parser`] is used to deserialize HTTP/1 messages from [link beast.types.streams streams]. +Objects of this type are used with [link beast.ref.http__parse http::parse] and +[link beast.ref.http__async_parse http::async_parse]. + +In this table: + +* `X` denotes a type meeting the requirements of [*`Parser`]. + +* `a` denotes a value of type `X`. + +* `b` is a value meeting the requirements of [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConvertibleToConstBuffer.html [*`ConvertibleToConstBuffer`]]. + +* `ec` is a value of type [link beast.ref.error_code `error_code&`]. + +[table Parser requirements +[[operation] [type] [semantics, pre/post-conditions]] +[ + [`a.complete()`] + [`bool`] + [ + Returns `true` when a complete HTTP/1 message has been parsed. + ] +] +[ + [`a.write(b, ec)`] + [`std::size_t`] + [ + Parses the octets in the specified input buffer sequentially until + an error occurs, the end of the buffer is reached, or a complete + HTTP/1 message has been parsed. If an error occurs, `ec` is set + to the error code and parsing stops. This function returns the + number of bytes consumed in the input buffer. + ] +] +[ + [`a.write_eof(ec)`] + [`void`] + [ + Indicates to the parser that no more octets will be available. + Typically this function is called when the end of stream is reached. + For example, if a call to `boost::asio::ip::tcp::socket::read_some` + generates a `boost::asio::error::eof` error. Some HTTP/1 messages + determine the end of the message body by an end of file marker or + closing of the connection. + ] +] +] + +[endsect] diff --git a/doc/types/Reader.qbk b/doc/types/Reader.qbk new file mode 100644 index 00000000..a94db4d0 --- /dev/null +++ b/doc/types/Reader.qbk @@ -0,0 +1,54 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:Reader Reader] + +Parser implementations will construct the corresponding `reader` object +during the parse. This customization point allows the Body to determine +the strategy for storing incoming message body data. + +In this table: + +* `X` denotes a type meeting the requirements of [*`Reader`]. + +* `a` denotes a value of type `X`. + +* `p` is any pointer. + +* `n` is a value convertible to `std::size_t`. + +* `ec` is a value of type `error_code&`. + +* `m` denotes a value of type `message const&` where + `std::is_same:value == true` + + +[table Reader requirements +[[operation] [type] [semantics, pre/post-conditions]] +[ + [`X a(m);`] + [] + [ + `a` is constructible from `m`. The lifetime of `m` is + guaranteed to end no earlier than after `a` is destroyed. + ] +] +[ + [`a.write(p, n, ec)`] + [`void`] + [ + Deserializes the input sequence into the body. + If `ec` is set, the deserialization is aborted and the error + is returned to the caller. + ] +] +] + +[note Definitions for required `Reader` member functions should be declared +inline so the generated code becomes part of the implementation. ] + +[endsect] diff --git a/doc/core_types.qbk b/doc/types/Streambuf.qbk similarity index 50% rename from doc/core_types.qbk rename to doc/types/Streambuf.qbk index 1efe460b..bbb24cf7 100644 --- a/doc/core_types.qbk +++ b/doc/types/Streambuf.qbk @@ -5,54 +5,32 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] - - -[section:BufferSequence BufferSequence] - -A `BufferSequence` is a type meeting either of the following requirements: - -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]] -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]] - -[endsect] - - - -[section:stream Streams] - -Stream types represent objects capable of performing synchronous or -asynchronous I/O. They are based on concepts from `boost::asio`. - -[heading:Stream Stream] - -A type modeling [*`Stream`] meets either or both of the following requirements: - -* [link beast.types.stream.AsyncStream [*`AsyncStream`]] -* [link beast.types.stream.SyncStream [*`SyncStream`]] - -[heading:AsyncStream AsyncStream] - -A type modeling [*`AsyncStream`] meets the following requirements: - -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*`AsyncReadStream`]] -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncWriteStream.html [*`AsyncWriteStream`]] - -[heading:SyncStream SyncStream] - -A type modeling [*`SyncStream`] meets the following requirements: - -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*`SyncReadStream`]] -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncWriteStream.html [*`SyncWriteStream`]] - -[endsect] - - - [section:Streambuf Streambuf] +A [*`Streambuf`] represents a logical octet sequence divided in two sections, +the input sequence and the output sequence. Octets are written to the output +sequence, then moved to the input sequence where they are available for +reading. When some or all of the input sequence is no longer needed, it may +be consumed. + +The interface to this concept is intended to permit the following +implementation strategies: + +* A single contiguous octet array, which is reallocated as necessary to + accommodate changes in the size of the octet sequence. + +* 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 + accommodate changes in the size of the octet sequence. + +* 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 approached + currently offered by [link beast.ref.basic_streambuf `basic_streambuf`]. + In the table below: -* `X` denotes a class +* `X` denotes a class meeting the requirements of [*`Streambuf`] * `a` denotes a value of type `X` * `n` denotes a value convertible to `std::size_t` * `U`, `T` denote unspecified types. @@ -62,12 +40,12 @@ In the table below: [ [`X::const_buffers_type`] [`T`] - [`T` meets the requirements for `ConstBufferSequence`.] + [`T` meets the requirements for [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html `ConstBufferSequence`].] ] [ [`X::mutable_buffers_type`] [`U`] - [`U` meets the requirements for `MutableBufferSequence`.] + [`U` meets the requirements for [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html `MutableBufferSequence`].] ] [ [`a.commit(n)`] @@ -98,7 +76,7 @@ In the table below: [ [`a.max_size()`] [`std::size_t`] - [Returns the maximum size of the `Streambuf`.] + [Returns the maximum size of the stream buffer.] ] [ [`read_size_helper(a, n)`] diff --git a/doc/types/Streams.qbk b/doc/types/Streams.qbk new file mode 100644 index 00000000..8ecf1118 --- /dev/null +++ b/doc/types/Streams.qbk @@ -0,0 +1,34 @@ +[/ + Copyright (c) 2013-2016 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) +] + +[section:streams Streams] + +Stream types represent objects capable of performing synchronous or +asynchronous I/O. They are based on concepts from `boost::asio`. + +[heading:Stream Stream] + +A type modeling [*`Stream`] meets either or both of the following requirements: + +* [link beast.types.streams.AsyncStream [*`AsyncStream`]] +* [link beast.types.streams.SyncStream [*`SyncStream`]] + +[heading:AsyncStream AsyncStream] + +A type modeling [*`AsyncStream`] meets the following requirements: + +* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html [*`AsyncReadStream`]] +* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncWriteStream.html [*`AsyncWriteStream`]] + +[heading:SyncStream SyncStream] + +A type modeling [*`SyncStream`] meets the following requirements: + +* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncReadStream.html [*`SyncReadStream`]] +* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/SyncWriteStream.html [*`SyncWriteStream`]] + +[endsect] diff --git a/doc/http_types.qbk b/doc/types/Writer.qbk similarity index 60% rename from doc/http_types.qbk rename to doc/types/Writer.qbk index bf5f6a34..f2756527 100644 --- a/doc/http_types.qbk +++ b/doc/types/Writer.qbk @@ -5,199 +5,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] - - -[section:Body Body] - -In this table: - -* `X` is a type meeting the requirements of [*`Body`]. - -[table Body requirements -[[operation] [type] [semantics, pre/post-conditions]] -[ - [`X::value_type`] - [] - [ - The type of the `message::body` member. - If this is not movable or not copyable, the containing message - will be not movable or not copyable. - ] -] -[ - [`X:value_type{}`] - [] - [`DefaultConstructible`] -] -[ - [`Body::reader`] - [] - [ - If present, a type meeting the requirements of - [link beast.types.Reader [*`Reader`]]. - Provides an implementation to parse the body. - ] -] -[ - [`Body::writer`] - [] - [ - If present, a type meeting the requirements of - [link beast.types.Writer [*`Writer`]]. - Provides an implementation to serialize the body. - ] -] -] - -[endsect] - - - -[section:BufferSequence BufferSequence] - -A `BufferSequence` is a type meeting either of the following requirements: - -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]] -* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]] - -[endsect] - - - -[section:Field Field] - -A [*`Field`] represents a single HTTP header field/value pair. - -In this table: - -* `X` denotes a type meeting the requirements of [*`Field`]. -* `a` denotes a value of type `X`. - -[table Field requirements - -[[operation][type][semantics, pre/post-conditions]] -[ - [`a.name()`] - [`boost::string_ref`] - [ - This function returns a value implicitly convertible to - `boost::string_ref` containing the case-insensitve field - name, without leading or trailing white space. - ] -] -[ - [`a.value()`] - [`boost::string_ref`] - [ - This function returns a value implicitly convertible to - `boost::string_ref` containing the value for the field. The - value is considered canonical if there is no leading or - trailing whitespace. - ] -] -] - -[endsect] - - - -[section:FieldSequence FieldSequence] - -A [*`FieldSequence`] is an iterable container whose value type meets -the requirements of [link beast.types.Field [*`Field`]]. - -In this table: - -* `X` denotes a type that meets the requirements of [*`FieldSequence`]. - -* `a` is a value of type `X`. - -[table FieldSequence requirements -[[operation][type][semantics, pre/post-conditions]] -[ - [`X::value_type`] - [] - [ - A type that meets the requirements of `Field`. - ] -] -[ - [`X::const_iterator`] - [] - [ - A type that meets the requirements of `ForwardIterator`. - ] -] -[ - [`a.begin()`] - [`X::const_iterator`] - [ - Returns an iterator to the beginning of the field sequence. - ] -] -[ - [`a.end()`] - [`X::const_iterator`] - [ - Returns an iterator to the end of the field sequence. - ] -] -] - -[endsect] - - - -[section:Reader Reader] - -Parser implementations will construct the corresponding `reader` object -during the parse. This customization point allows the Body to determine -the strategy for storing incoming message body data. - -In this table: - -* `X` denotes a type meeting the requirements of [*`Reader`]. - -* `a` denotes a value of type `X`. - -* `p` is any pointer. - -* `n` is a value convertible to `std::size_t`. - -* `ec` is a value of type `error_code&`. - -* `m` denotes a value of type `message const&` where - `std::is_same:value == true` - - -[table Reader requirements -[[operation] [type] [semantics, pre/post-conditions]] -[ - [`X a(m);`] - [] - [ - `a` is constructible from `m`. The lifetime of `m` is - guaranteed to end no earlier than after `a` is destroyed. - ] -] -[ - [`a.write(p, n, ec)`] - [`void`] - [ - Deserializes the input sequence into the body. - If `ec` is set, the deserialization is aborted and the error - is returned to the caller. - ] -] -] - -[note Definitions for required `Reader` member functions should be declared -inline so the generated code becomes part of the implementation. ] - -[endsect] - - - [section:Writer Writer] A `Writer` serializes the message body. The implementation creates an instance @@ -370,4 +177,3 @@ public: ``` [endsect] -