work in progress

Author: MungoG

include/boost/beast2/body_write_stream.hpp

@@ -63,32 +63,41 @@ class body_write_stream
 
     /** Constructor
 
-        This constructor creates the stream by forwarding all arguments to the
-        underlying socket.  The socket then needs to be open and connected or
-        accepted before data can be sent or received on it.
+        This constructor creates the stream which retains a reference to the
+        underlying stream.  The underlying stream then needs to be open before
+        data can be written
 
-        @param s  The underlying stream from which the HTTP message is write.
+        @param s  The underlying stream to which the HTTP message is written.
                   This object's executor is initialized to that of the
                   underlying stream.
 
-        @param pr A http_proto::parser object which will perform the parsing of
+        @param sr A http_proto::serializer object which will perform the serialization of
                   the HTTP message and extraction of the body.  This must be
-                  initialized by the caller and ownership of the parser is
+                  initialized by the caller and ownership of the serializer is
                   retained by the caller, which must guarantee that it remains
                   valid until the handler is called.
+
+        @param srs A http_proto::serializer::stream object which must have been
+                   obtained by a call to `start_stream` on `sr`.  Ownership of the
+                   serializer::stream is
+                   retained by the caller, which must guarantee that it remains
+                   valid until the handler is called.
     */
-    explicit body_write_stream(AsyncWriteStream& s, http_proto::serializer& sr);
+    explicit body_write_stream(
+        AsyncWriteStream& s,
+        http_proto::serializer& sr,
+        http_proto::serializer::stream& srs);
 
     /** Write some data asynchronously.
 
-        This function is used to asynchronously write data from the stream.
+        This function is used to asynchronously write data to the stream.
 
         This call always returns immediately.  The asynchronous operation will
         continue until one of the following conditions is true:
 
-        @li The HTTP headers are write in full from the underlying stream and one
-            or more bytes of the body are write from the stream and stored in the
-            buffer `mb`.
+        @li One or more bytes are written from `cb` to the body stored in the
+            serializer and one or more bytes are written from the serializer to the
+            underlying stream.
 
         @li An error occurs.
 
@@ -98,13 +107,14 @@ class body_write_stream
         implemented using the underlying stream's `async_write_some` are
         performed until this operation completes.
 
-        @param mb The buffers into which the body data will be write.  If the
-        size of the buffers is zero bytes, the operation always completes
-        immediately with no error.  Although the buffers object may be copied as
-        necessary, ownership of the underlying memory blocks is retained by the
-        caller, which must guarantee that they remain valid until the handler is
-        called.  Where the mb buffer is not of sufficient size to hold the write
-        data, the remainder may be write by subsequent calls to this function.
+        @param cb The buffer sequence from which the body data will be read.  If
+        the size of the buffer sequence is zero bytes, the operation always
+        completes immediately with no error.  Although the buffers object may be
+        copied as necessary, ownership of the underlying memory blocks is
+        retained by the caller, which must guarantee that they remain valid until
+        the handler is called.  Where the internal buffer of the contained
+        serializer is not of sufficient size to hold the data to be copied from
+        cb, the remainder may be write by subsequent calls to this function.
 
         @param handler The completion handler to invoke when the operation
         completes.  The implementation takes ownership of the handler by
@@ -113,7 +123,8 @@ class body_write_stream
         @code
         void handler(
             error_code const& error,        // result of operation
-            std::size_t bytes_transferred   // the number of bytes consumed by the parser
+            std::size_t bytes_transferred   // the number of bytes consumed from
+                                            // cb by the serializer
         );
         @endcode
         Regardless of whether the asynchronous operation
@@ -122,11 +133,17 @@ class body_write_stream
         handler will be performed in a manner equivalent to using
         `asio::async_immediate`.
 
-        @note The `async_write_some` operation may not receive all of the
+        @note The `async_write_some` operation may not transmit all of the
         requested number of bytes.  Consider using the function
         `asio::async_write` if you need to ensure that the requested amount of
         data is write before the asynchronous operation completes.
 
+        @note This function does not guarantee that all of the consumed data is
+        written to the underlying stream. For this reason one or more calls to
+        `async_write_some` must be followed by a call to `async_close` to put the
+        serializer into the `done` state and to write all data remaining in the
+        serializer to the underlying stream.
+
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -148,9 +165,79 @@ class body_write_stream
         void(system::error_code, std::size_t))
     async_write_some(ConstBufferSequence mb, CompletionToken&& handler);
 
+    /** Close serializer::stream and flush remaining data to the underlying stream asynchronously.
+
+        This function is used to asynchronously call `close` on the
+        `serializer::stream` object referenced in the construction of this
+        `body_write_stream` and write all remaining data in the serializer to the
+        underlying stream.
+
+        This call always returns immediately.  The asynchronous operation will
+        continue until one of the following conditions is true:
+
+        @li All remaining output bytes of the serializer are written to the
+            underlying stream and the serializer's `is_done()` method returns true.
+
+        @li An error occurs.
+
+        The algorithm, known as a <em>composed asynchronous operation</em>, is
+        implemented in terms of calls to the underlying stream's
+        `async_write_some` function. The program must ensure that no other calls
+        implemented using the underlying stream's `async_write_some` are
+        performed until this operation completes.
+
+        @param handler The completion handler to invoke when the operation
+        completes.  The implementation takes ownership of the handler by
+        performing a decay-copy.  The equivalent function signature of the
+        handler must be:
+        @code
+        void handler(
+            error_code const& error,        // result of operation
+            std::size_t bytes_transferred   // the number of bytes consumed from
+                                            // cb by the serializer
+        );
+        @endcode
+        Regardless of whether the asynchronous operation
+        completes immediately or not, the completion handler will not be invoked
+        from within this function. On immediate completion, invocation of the
+        handler will be performed in a manner equivalent to using
+        `asio::async_immediate`.
+
+        @note The `async_write_some` operation may not transmit all of the
+        requested number of bytes.  Consider using the function
+        `asio::async_write` if you need to ensure that the requested amount of
+        data is write before the asynchronous operation completes.
+
+        @note This function does not guarantee that all of the consumed data is
+        written to the underlying stream. For this reason one or more calls to
+        `async_write_some` must be followed by a call to `async_close` to put the
+        serializer into the `done` state and to write all data remaining in the
+        serializer to the underlying stream.
+
+        @par Per-Operation Cancellation
+
+        This asynchronous operation supports cancellation for the following
+        net::cancellation_type values:
+
+        @li @c net::cancellation_type::terminal
+        @li @c net::cancellation_type::partial
+        @li @c net::cancellation_type::total
+
+        if they are also supported by the underlying stream's @c async_write_some
+        operation.
+    */
+    template<
+        BOOST_ASIO_COMPLETION_TOKEN_FOR(void(system::error_code))
+            CompletionToken>
+    BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(
+        CompletionToken,
+        void(system::error_code))
+    async_close(CompletionToken&& handler);
+
 private:
     AsyncWriteStream& stream_;
     http_proto::serializer& sr_;
+    http_proto::serializer::stream& srs_;
 };
 
 } // beast2