Add example of reading large response body

closes #2240

CHANGELOG.md

@@ -1,3 +1,7 @@
+* Add example of reading large response body.
+
+--------------------------------------------------------------------------------
+
 Version 316:
 
 * Disable GHA CI for clang-9.

doc/qbk/04_http/05_parser_streams.qbk

@@ -138,4 +138,15 @@ using a small, fixed-size buffer:
 
 
 
+[section:read_large_response_body Reading large response body __example__]
+
+This example presents how to increase the default limit of the response body size,
+thus the content larger than the default 8MB can be read.
+
+[example_read_large_response_body]
+
+[endsect]
+
+
+
 [endsect]

example/doc/http_examples.hpp

@@ -902,6 +902,42 @@ read_and_print_body(
 
 //]
 
+//------------------------------------------------------------------------------
+//
+// Example: Read large response body 
+//
+//------------------------------------------------------------------------------
+
+//[example_read_large_response_body
+
+/*  This function uses custom size limit of the resposne body.
+    The key method is 'body_limit' of the parser.
+    body_limit is expressed in bytes.
+*/
+template<
+    class SyncReadStream,
+    class DynamicBuffer,
+    bool isRequest, class Body, class Allocator>
+std::size_t
+read_large_response_body(
+    SyncReadStream& stream,
+    DynamicBuffer& buffer,
+    message<isRequest, Body, basic_fields<Allocator>>& msg,
+    std::size_t body_limit,
+    error_code& ec)
+{
+    parser<isRequest, Body, Allocator> p(std::move(msg));
+    p.eager(true);
+    p.body_limit(body_limit);
+    auto const bytes_transferred =
+        http::read(stream, buffer, p, ec);
+    if(ec)
+        return bytes_transferred;
+    msg = p.release();
+    return bytes_transferred;
+}
+
+//]
 
 //------------------------------------------------------------------------------
 //