Add buffers_generator

doc/qbk/07_concepts/BuffersGenerator.qbk

@@ -0,0 +1,140 @@
+[/
+    Copyright (c) 2016-2022 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:BuffersGenerator BuffersGenerator]
+
+A [*BuffersGenerator] provides a generalized interface for generating
+serialized data for sequential processing.
+
+The generator will be asked to produce buffers. The consuming code will signal
+how much of the data has been consumed, and repeatedly query for buffers until
+no more data is available, or the generator indicates an error condition.
+
+Overloads of [link beast.ref.boost__beast__write `write`] and [link
+beast.ref.boost__beast__async_write `async_write`] operations are provided as
+free functions. These operations will consume the output of a
+[*BuffersGenerator] and process the data by writing them to a
+__SyncWriteStream__ or __AsyncWriteStream__ respectively.
+
+[heading Associated Types]
+
+* [link beast.ref.boost__beast__is_buffers_generator `is_buffers_generator`]
+* __ConstBufferSequence__
+
+[heading Requirements]
+
+In this table:
+
+* `G` denotes a type meeting the requirements of [*BuffersGenerator].
+* `g` denotes a value of type `G`.
+* `n` is a value of type `std::size_t`.
+* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`].
+
+[table Valid expressions
+[[Expression] [Type] [Semantics, Pre/Post-conditions]]
+[
+    [`G::const_buffers_type`]
+    []
+    [
+        A type which meets the requirements of __ConstBufferSequence__.
+        This is the type of buffer returned by `g.prepare(ec)`.
+    ]
+][
+    [`g.is_done()`]
+    [`bool`]
+    [
+        Called to ask the generator for its completion status.
+
+        A generator has completed when no new buffer will be produced and
+        previously produced buffers have been fully consumed.
+
+        [*Note:] The result of invoking `prepare` on `g` once it has completed
+        is unspecified.
+
+        This member function does not alter the state of the generator.
+    ]
+][
+    [`g.prepare(ec)`]
+    [`G::const_buffers_type`]
+    [
+        Called to ask the generator to produce buffers containing data for
+        processing.
+
+        The returned value is the __ConstBufferSequence__ representing
+        unconsumed data.
+
+        The function will ensure that `ec.failed()` is `false` if there was no
+        error or set to the appropriate error code if there was one. 
+
+        If no unconsumed data is available, this operation shall make progress
+        to eventually reach completion.
+        
+        The result of invoking `prepare` after completion or encountered
+        error(s) is defined by the generator implementation. It can not be
+        assumed to be meaningful or safe to do so, in general.
+
+        The capacity of the buffer returned is defined by the generator
+        implementation.
+        
+        [*Note:] Any buffers obtained by previous calls to `prepare` are
+        invalidated.
+    ]
+][
+    [`g.consume(n)`]
+    []
+    [
+        This function is called to signal that the consumer (caller) of the
+        generator has processed part of the data returned by the previous call
+        to `prepare`.
+
+        The value of `n` indicates how much of the data processed (in bytes).
+
+        When `n` exceeds the number of bytes returned from the last call to
+        `prepare`, `consume` shall behave as if `n` was equal to that number.
+
+        Remaining unconsumed data will be returned from subsequent calls to
+        `prepare`.
+
+        [*Note:] Any buffers obtained by previous calls to `prepare` are
+        invalidated.
+    ]
+][
+    [`is_buffers_generator<G>`]
+    [`std::true_type`]
+    [
+        An alias for `std::true_type` for `G`, otherwise an alias
+        for `std::false_type`.
+    ]
+]]
+
+[heading Exemplar]
+
+```
+    // A buffer sequence generator
+    struct BuffersGenerator
+    {
+        using const_buffers_type = net::const_buffer;
+
+        bool is_done();
+        const_buffers_type prepare( error_code& ec );
+        void consume( std::size_t n );
+    };
+
+    static_assert(
+        is_buffers_generator<BuffersGenerator>::value, "");
+```
+
+[heading Models]
+
+[heading Algorithms]
+
+* [link beast.ref.boost__beast__async_write `async_write`]
+* [link beast.ref.boost__beast__write `write`] 
+
+[endsect]

doc/qbk/07_concepts/_concepts.qbk

@@ -15,6 +15,7 @@ This section describes all of the concepts defined by the library.
 [include BodyReader.qbk]
 [include BodyWriter.qbk]
 [include BufferSequence.qbk]
+[include BuffersGenerator.qbk]
 [include DynamicBuffer.qbk]
 [include Fields.qbk]
 [include FieldsWriter.qbk]

doc/qbk/main.qbk

@@ -95,6 +95,7 @@
 [def __BodyReader__             [link beast.concepts.BodyReader ['BodyReader]]]
 [def __BodyWriter__             [link beast.concepts.BodyWriter ['BodyWriter]]]
 [def __BufferSequence__         [link beast.concepts.BufferSequence ['BufferSequence]]]
+[def __BuffersGenerator__       [link beast.concepts.BufferSequence ['BuffersGenerator]]]
 [def __DynamicBuffer__          [link beast.concepts.DynamicBuffer ['DynamicBuffer]]]
 [def __Fields__                 [link beast.concepts.Fields ['Fields]]]
 [def __FieldsWriter__           [link beast.concepts.FieldsWriter ['FieldsWriter]]]

doc/qbk/quickref.xml

@@ -76,15 +76,15 @@
         <bridgehead renderas="sect3">Type Traits</bridgehead>
         <simplelist type="vert" columns="1">
           <member><link linkend="beast.ref.boost__beast__executor_type">executor_type</link></member>
-          <member><link linkend="beast.ref.boost__beast__lowest_layer_type">lowest_layer_type</link></member>
           <member><link linkend="beast.ref.boost__beast__has_get_executor">has_get_executor</link></member>
           <member><link linkend="beast.ref.boost__beast__is_async_read_stream">is_async_read_stream</link></member>
-          <member><link linkend="beast.ref.boost__beast__is_async_write_stream">is_async_write_stream</link></member>
           <member><link linkend="beast.ref.boost__beast__is_async_stream">is_async_stream</link></member>
+          <member><link linkend="beast.ref.boost__beast__is_async_write_stream">is_async_write_stream</link></member>
           <member><link linkend="beast.ref.boost__beast__is_file">is_file</link></member>
           <member><link linkend="beast.ref.boost__beast__is_sync_read_stream">is_sync_read_stream</link></member>
           <member><link linkend="beast.ref.boost__beast__is_sync_stream">is_sync_stream</link></member>
           <member><link linkend="beast.ref.boost__beast__is_sync_write_stream">is_sync_write_stream</link></member>
+          <member><link linkend="beast.ref.boost__beast__lowest_layer_type">lowest_layer_type</link></member>
         </simplelist>
         <bridgehead renderas="sect3">SSL</bridgehead>
         <simplelist type="vert" columns="1">
@@ -141,6 +141,7 @@
       </entry><entry valign="top">
         <bridgehead renderas="sect3">Functions</bridgehead>
         <simplelist type="vert" columns="1">
+          <member><link linkend="beast.ref.boost__beast__async_write">async_write</link></member>
           <member><link linkend="beast.ref.boost__beast__buffer_bytes">buffer_bytes</link></member>
           <member><link linkend="beast.ref.boost__beast__buffers_cat">buffers_cat</link></member>
           <member><link linkend="beast.ref.boost__beast__buffers_front">buffers_front</link></member>
@@ -152,12 +153,14 @@
           <member><link linkend="beast.ref.boost__beast__ostream">ostream</link></member>
           <member><link linkend="beast.ref.boost__beast__read_size">read_size</link></member>
           <member><link linkend="beast.ref.boost__beast__read_size_or_throw">read_size_or_throw</link></member>
+          <member><link linkend="beast.ref.boost__beast__write">write</link></member>
         </simplelist>
       </entry><entry valign="top">
         <bridgehead renderas="sect3">Type Traits</bridgehead>
         <simplelist type="vert" columns="1">
-          <member><link linkend="beast.ref.boost__beast__buffers_type">buffers_type</link></member>
           <member><link linkend="beast.ref.boost__beast__buffers_iterator_type">buffers_iterator_type</link></member>
+          <member><link linkend="beast.ref.boost__beast__buffers_type">buffers_type</link></member>
+          <member><link linkend="beast.ref.boost__beast__is_buffers_generator">is_buffers_generator</link></member>
           <member><link linkend="beast.ref.boost__beast__is_const_buffer_sequence">is_const_buffer_sequence</link></member>
           <member><link linkend="beast.ref.boost__beast__is_mutable_buffer_sequence">is_mutable_buffer_sequence</link></member>
         </simplelist>
@@ -165,6 +168,7 @@
         <bridgehead renderas="sect3">Concepts</bridgehead>
         <simplelist type="vert" columns="1">
           <member><link linkend="beast.concepts.BufferSequence">BufferSequence</link></member>
+          <member><link linkend="beast.concepts.BuffersGenerator">BuffersGenerator</link></member>
           <member><link linkend="beast.concepts.DynamicBuffer">DynamicBuffer</link></member>
         </simplelist>
       </entry>

doc/xsl/custom-overrides.xsl

@@ -23,6 +23,7 @@
     'Body',
     'BufferSequence',
     'BufferSequence',  (: TODO: Was this intended to be 'BufferSequence_' ?? :)
+    'BuffersGenerator',
     'CompletionCondition',
     'CompletionHandler',
     'CompletionToken',