read_size replaces read_size_helper:

* detail::read_size_helper is removed

* public function read_size helps determine the optimum
  size for calls to a DynamicBuffer's prepare function.

* special case for Asio types which don't conform to
  the concept but have their own helper function.

CHANGELOG.md

@@ -3,6 +3,7 @@ Version 55:
 * Don't allocate memory to handle obs-fold
 * Add Beast CMake interface target
 * Avoid a parser allocation using non-flat buffer
+* read_size replaces read_size_helper
 
 --------------------------------------------------------------------------------
 

doc/quickref.xml

@@ -189,6 +189,8 @@
             <member><link linkend="beast.ref.buffer_prefix">buffer_prefix</link></member>
             <member><link linkend="beast.ref.buffers">buffers</link></member>
             <member><link linkend="beast.ref.ostream">ostream</link></member>
+            <member><link linkend="beast.ref.read_size">read_size</link></member>
+            <member><link linkend="beast.ref.read_size_or_throw">read_size_or_throw</link></member>
             <member><link linkend="beast.ref.system_category">system_category</link></member>
             <member><link linkend="beast.ref.to_static_string">to_static_string</link></member>
           </simplelist>

include/beast/core/detail/ostream.hpp

@@ -9,7 +9,7 @@
 #define BEAST_DETAIL_OSTREAM_HPP
 
 #include <boost/asio/buffer.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
+#include <beast/core/read_size.hpp>
 #include <memory>
 #include <iosfwd>
 #include <streambuf>
@@ -129,7 +129,7 @@ private:
         using boost::asio::buffer_cast;
         using boost::asio::buffer_size;
         auto mbs = buf_.prepare(
-            maybe_read_size_helper(buf_, max_size));
+            read_size_or_throw(buf_, max_size));
         auto const mb = *mbs.begin();
         auto const p = buffer_cast<CharT*>(mb);
         this->setp(p,
@@ -209,7 +209,7 @@ private:
         using boost::asio::buffer_cast;
         using boost::asio::buffer_size;
         auto mbs = buf_.prepare(
-            maybe_read_size_helper(buf_, max_size));
+            read_size_or_throw(buf_, max_size));
         auto const mb = *mbs.begin();
         auto const p = buffer_cast<CharT*>(mb);
         this->setp(p,

include/beast/core/detail/read_size_helper.hpp

@@ -1,72 +0,0 @@
-//
-// Copyright (c) 2013-2017 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)
-//
-
-#ifndef BEAST_DETAIL_READ_SIZE_HELPER_HPP
-#define BEAST_DETAIL_READ_SIZE_HELPER_HPP
-
-#include <beast/core/type_traits.hpp>
-#include <boost/assert.hpp>
-#include <boost/throw_exception.hpp>
-#include <algorithm>
-#include <cstddef>
-
-namespace beast {
-namespace detail {
-
-/** Returns a natural read size.
-
-    This function inspects the capacity, size, and maximum
-    size of the dynamic buffer. Then it computes a natural
-    read size given the passed-in upper limit. It favors
-    a read size that does not require a reallocation, subject
-    to a reasonable minimum to avoid tiny reads.
-
-    Calls to @ref read_size_helper should be made without
-    namespace qualification, i.e. allowing argument dependent
-    lookup to take effect, so that overloads of this function
-    for specific buffer types may be found.
-
-    @param buffer The dynamic buffer to inspect.
-
-    @param max_size An upper limit on the returned value.
-*/
-template<class DynamicBuffer>
-std::size_t
-read_size_helper(
-    DynamicBuffer const& buffer, std::size_t max_size)
-{
-    static_assert(beast::is_dynamic_buffer<DynamicBuffer>::value,
-        "DynamicBuffer requirements not met");
-    BOOST_ASSERT(max_size >= 1);
-    auto const size = buffer.size();
-    auto const limit = buffer.max_size() - size;
-    BOOST_ASSERT(size <= buffer.max_size());
-    return std::min<std::size_t>(
-        std::max<std::size_t>(512, buffer.capacity() - size),
-        std::min<std::size_t>(max_size, limit));
-}
-
-/** Return a non-zero natural read size.
-*/
-template<class DynamicBuffer>
-std::size_t
-maybe_read_size_helper(
-    DynamicBuffer const& buffer, std::size_t max_size)
-{
-    static_assert(beast::is_dynamic_buffer<DynamicBuffer>::value,
-        "DynamicBuffer requirements not met");
-    auto const n = read_size_helper(buffer, max_size);
-    if(n == 0)
-        BOOST_THROW_EXCEPTION(std::length_error{
-            "buffer overflow"});
-    return n;
-}
-
-} // detail
-} // beast
-
-#endif

include/beast/core/impl/read_size.ipp

@@ -0,0 +1,75 @@
+//
+// Copyright (c) 2013-2017 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)
+//
+
+#ifndef BEAST_IMPL_READ_SIZE_IPP
+#define BEAST_IMPL_READ_SIZE_IPP
+
+namespace beast {
+
+namespace detail {
+
+template<class T, class = void>
+struct has_read_size_helper : std::false_type {};
+
+template<class T>
+struct has_read_size_helper<T, decltype(
+    read_size_helper(std::declval<T&>(), 512),
+    (void)0)> : std::true_type
+{
+};
+
+template<class DynamicBuffer>
+std::size_t
+read_size(DynamicBuffer& buffer,
+    std::size_t max_size, std::true_type)
+{
+    return read_size_helper(buffer, max_size);
+}
+
+template<class DynamicBuffer>
+std::size_t
+read_size(DynamicBuffer& buffer,
+    std::size_t max_size, std::false_type)
+{
+    static_assert(is_dynamic_buffer<DynamicBuffer>::value,
+        "DynamicBuffer requirements not met");
+    BOOST_ASSERT(max_size >= 1);
+    auto const size = buffer.size();
+    auto const limit = buffer.max_size() - size;
+    BOOST_ASSERT(size <= buffer.max_size());
+    return std::min<std::size_t>(
+        std::max<std::size_t>(512, buffer.capacity() - size),
+        std::min<std::size_t>(max_size, limit));
+}
+
+} // detail
+
+template<class DynamicBuffer>
+inline
+std::size_t
+read_size(
+    DynamicBuffer& buffer, std::size_t max_size)
+{
+    return detail::read_size(buffer, max_size,
+        detail::has_read_size_helper<DynamicBuffer>{});
+}
+
+template<class DynamicBuffer>
+std::size_t
+read_size_or_throw(
+    DynamicBuffer& buffer, std::size_t max_size)
+{
+    auto const n = read_size(buffer, max_size);
+    if(n == 0)
+        BOOST_THROW_EXCEPTION(std::length_error{
+            "buffer overflow"});
+    return n;
+}
+
+} // beast
+
+#endif

include/beast/core/read_size.hpp

@@ -0,0 +1,59 @@
+//
+// Copyright (c) 2013-2017 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)
+//
+
+#ifndef BEAST_READ_SIZE_HELPER_HPP
+#define BEAST_READ_SIZE_HELPER_HPP
+
+#include <beast/core/type_traits.hpp>
+#include <boost/throw_exception.hpp>
+
+namespace beast {
+
+/** Returns a natural read size.
+
+    This function inspects the capacity, size, and maximum
+    size of the dynamic buffer. Then it computes a natural
+    read size given the passed-in upper limit. It favors
+    a read size that does not require a reallocation, subject
+    to a reasonable minimum to avoid tiny reads.
+
+    @param buffer The dynamic buffer to inspect.
+
+    @param max_size An upper limit on the returned value.
+
+    @note If the buffer is already at its maximum size, zero
+    is returned.
+*/
+template<class DynamicBuffer>
+std::size_t
+read_size(DynamicBuffer& buffer, std::size_t max_size);
+
+/** Returns a natural read size or throw if the buffer is full.
+
+    This function inspects the capacity, size, and maximum
+    size of the dynamic buffer. Then it computes a natural
+    read size given the passed-in upper limit. It favors
+    a read size that does not require a reallocation, subject
+    to a reasonable minimum to avoid tiny reads.
+
+    @param buffer The dynamic buffer to inspect.
+
+    @param max_size An upper limit on the returned value.
+
+    @throws std::length_error if `max_size > 0` and the buffer
+    is full.
+*/
+template<class DynamicBuffer>
+std::size_t
+read_size_or_throw(DynamicBuffer& buffer,
+    std::size_t max_size);
+
+} // beast
+
+#include <beast/core/impl/read_size.ipp>
+
+#endif

include/beast/http/impl/read.ipp

@@ -14,8 +14,8 @@
 #include <beast/http/read.hpp>
 #include <beast/core/bind_handler.hpp>
 #include <beast/core/handler_ptr.hpp>
+#include <beast/core/read_size.hpp>
 #include <beast/core/type_traits.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
 #include <boost/asio/handler_alloc_hook.hpp>
 #include <boost/asio/handler_continuation_hook.hpp>
 #include <boost/asio/handler_invoke_hook.hpp>
@@ -145,7 +145,7 @@ operator()(error_code ec, std::size_t bytes_transferred)
         try
         {
             mb_.emplace(b_.prepare(
-                maybe_read_size_helper(b_, 65536)));
+                read_size_or_throw(b_, 65536)));
         }
         catch(std::length_error const&)
         {
@@ -474,8 +474,7 @@ read_some(
         try
         {
             b.emplace(buffer.prepare(
-                beast::detail::maybe_read_size_helper(
+                read_size_or_throw(buffer, 65536)));
-                    buffer, 65536)));
         }
         catch(std::length_error const&)
         {

include/beast/websocket/detail/pmd_extension.hpp

@@ -10,8 +10,8 @@
 
 #include <beast/core/error.hpp>
 #include <beast/core/consuming_buffers.hpp>
+#include <beast/core/read_size.hpp>
 #include <beast/core/detail/ci_char_traits.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
 #include <beast/zlib/deflate_stream.hpp>
 #include <beast/zlib/inflate_stream.hpp>
 #include <beast/websocket/option.hpp>
@@ -370,7 +370,7 @@ inflate(
     {
         // VFALCO we could be smarter about the size
         auto const bs = buffer.prepare(
-            maybe_read_size_helper(buffer, 65536));
+            read_size_or_throw(buffer, 65536));
         auto const out = *bs.begin();
         zs.avail_out = buffer_size(out);
         zs.next_out = buffer_cast<void*>(out);

test/Jamfile

@@ -34,6 +34,7 @@ unit-test core-tests :
     core/handler_ptr.cpp
     core/multi_buffer.cpp
     core/ostream.cpp
+    core/read_size.cpp
     core/static_buffer.cpp
     core/static_string.cpp
     core/string_param.cpp

test/core/CMakeLists.txt

@@ -29,6 +29,7 @@ add_executable (core-tests
     handler_ptr.cpp
     multi_buffer.cpp
     ostream.cpp
+    read_size.cpp
     static_buffer.cpp
     static_string.cpp
     string_param.cpp

test/core/buffer_bench.cpp

@@ -7,8 +7,8 @@
 
 #include <beast/core/flat_buffer.hpp>
 #include <beast/core/multi_buffer.hpp>
+#include <beast/core/read_size.hpp>
 #include <beast/core/string_view.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
 #include <beast/unit_test/suite.hpp>
 #include <boost/asio/streambuf.hpp>
 #include <algorithm>
@@ -111,9 +111,8 @@ public:
             {
                 for(auto remain = size; remain;)
                 {
-                    using beast::detail::read_size_helper;
                     auto const n = fill(b.prepare(
-                        read_size_helper(b, remain)));
+                        read_size(b, remain)));
                     b.commit(n);
                     remain -= n;
                     total += n;

test/core/buffer_test.hpp

@@ -9,8 +9,8 @@
 #define BEAST_TEST_BUFFER_TEST_HPP
 
 #include <beast/core/string_view.hpp>
+#include <beast/core/read_size.hpp>
 #include <beast/core/type_traits.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
 #include <beast/core/detail/type_traits.hpp>
 #include <boost/asio/buffer.hpp>
 #include <algorithm>
@@ -112,37 +112,6 @@ size_rev_post(ConstBufferSequence const& buffers)
     return n;
 }
 
-namespace has_read_size_helper
-{
-    using beast::detail::read_size_helper;
-
-    template<class T, class = void>
-    struct trait : std::false_type {};
-
-    template<class T>
-    struct trait<T, decltype(
-        std::declval<std::size_t&>() =
-            read_size_helper(std::declval<T>(), 0),
-        (void)0)> : std::true_type
-    {
-    };
-}
-
-//------------------------------------------------------------------------------
-
-// Make sure read_size_helper works
-template<class DynamicBuffer>
-inline
-void
-check_read_size_helper()
-{
-    static_assert(is_dynamic_buffer<DynamicBuffer>::value,
-        "DynamicBuffer requirements not met ");
-
-    static_assert(has_read_size_helper::trait<DynamicBuffer>::value,
-        "Missing read_size_helper for dynamic buffer");
-}
-
 } // test
 } // beast
 

test/core/buffers_adapter.cpp

@@ -183,15 +183,11 @@ public:
         type buffer;
         buffers_adapter<
             type::mutable_buffers_type> ba{buffer.prepare(512)};
-        using beast::detail::read_size_helper;
+        read_size(ba, 1024);
-        read_size_helper(ba, 1024);
     }
 
     void run() override
     {
-        test::check_read_size_helper<buffers_adapter<
-            boost::asio::mutable_buffers_1>>();
-
         testBuffersAdapter();
         testCommit();
         testIssue386();

test/core/flat_buffer.cpp

@@ -11,8 +11,8 @@
 #include "buffer_test.hpp"
 
 #include <beast/core/ostream.hpp>
+#include <beast/core/read_size.hpp>
 #include <beast/core/string_view.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
 #include <beast/test/test_allocator.hpp>
 #include <beast/unit_test/suite.hpp>
 #include <boost/lexical_cast.hpp>
@@ -261,19 +261,18 @@ public:
             BEAST_EXPECT(to_string(b.data()) == "4567890123");
         }
 
-        // read_size_helper
+        // read_size
         {
-            using detail::read_size_helper;
             flat_buffer b{10};
-            BEAST_EXPECT(read_size_helper(b, 512) == 10);
+            BEAST_EXPECT(read_size(b, 512) == 10);
             b.prepare(4);
             b.commit(4);
-            BEAST_EXPECT(read_size_helper(b, 512) == 6);
+            BEAST_EXPECT(read_size(b, 512) == 6);
             b.consume(2);
-            BEAST_EXPECT(read_size_helper(b, 512) == 8);
+            BEAST_EXPECT(read_size(b, 512) == 8);
             b.prepare(8);
             b.commit(8);
-            BEAST_EXPECT(read_size_helper(b, 512) == 0);
+            BEAST_EXPECT(read_size(b, 512) == 0);
         }
 
         // swap
@@ -344,8 +343,6 @@ public:
     void
     run() override
     {
-        test::check_read_size_helper<flat_buffer>();
-
         testBuffer();
     }
 };

test/core/multi_buffer.cpp

@@ -562,27 +562,24 @@ public:
             }
         }
 
-        // read_size_helper
+        // read_size
         {
-            using detail::read_size_helper;
             multi_buffer b{10};
-            BEAST_EXPECT(read_size_helper(b, 512) == 10);
+            BEAST_EXPECT(read_size(b, 512) == 10);
             b.prepare(4);
             b.commit(4);
-            BEAST_EXPECT(read_size_helper(b, 512) == 6);
+            BEAST_EXPECT(read_size(b, 512) == 6);
             b.consume(2);
-            BEAST_EXPECT(read_size_helper(b, 512) == 8);
+            BEAST_EXPECT(read_size(b, 512) == 8);
             b.prepare(8);
             b.commit(8);
-            BEAST_EXPECT(read_size_helper(b, 512) == 0);
+            BEAST_EXPECT(read_size(b, 512) == 0);
         }
     }
 
     void
     run() override
     {
-        test::check_read_size_helper<multi_buffer>();
-
         testMatrix1();
         testMatrix2();
         testIterators();

test/core/read_size.cpp

@@ -0,0 +1,44 @@
+//
+// Copyright (c) 2013-2017 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)
+//
+
+// Test that header file is self-contained.
+#include <beast/core/read_size.hpp>
+
+#include <beast/core/drain_buffer.hpp>
+#include <beast/core/flat_buffer.hpp>
+#include <beast/core/multi_buffer.hpp>
+#include <beast/unit_test/suite.hpp>
+
+#include <boost/asio/streambuf.hpp>
+
+namespace beast {
+
+class read_size_test : public beast::unit_test::suite
+{
+public:
+    template<class DynamicBuffer>
+    void
+    check()
+    {
+        DynamicBuffer buffer;
+        read_size(buffer, 65536);
+        pass();
+    }
+
+    void
+    run() override
+    {
+        check<drain_buffer>();
+        check<flat_buffer>();
+        check<multi_buffer>();
+        check<boost::asio::streambuf>();
+    }
+};
+
+BEAST_DEFINE_TESTSUITE(read_size,core,beast);
+
+} // beast

test/core/static_buffer.cpp

@@ -190,19 +190,18 @@ public:
             }
         }
 
-        // read_size_helper
+        // read_size
         {
-            using detail::read_size_helper;
             static_buffer_n<10> b;
-            BEAST_EXPECT(read_size_helper(b, 512) == 10);
+            BEAST_EXPECT(read_size(b, 512) == 10);
             b.prepare(4);
             b.commit(4);
-            BEAST_EXPECT(read_size_helper(b, 512) == 6);
+            BEAST_EXPECT(read_size(b, 512) == 6);
             b.consume(2);
-            BEAST_EXPECT(read_size_helper(b, 512) == 8);
+            BEAST_EXPECT(read_size(b, 512) == 8);
             b.prepare(8);
             b.commit(8);
-            BEAST_EXPECT(read_size_helper(b, 512) == 0);
+            BEAST_EXPECT(read_size(b, 512) == 0);
         }
 
         // base
@@ -224,8 +223,6 @@ public:
 
     void run() override
     {
-        test::check_read_size_helper<static_buffer_n<32>>();
-
         testBuffer();
         //testStaticBuffer();
     }

test/http/doc_http_samples.cpp

@@ -8,8 +8,8 @@
 #include <examples/doc_http_samples.hpp>
 #include <examples/file_body.hpp>
 
+#include <beast/core/read_size.hpp>
 #include <beast/core/detail/clamp.hpp>
-#include <beast/core/detail/read_size_helper.hpp>
 #include <beast/test/pipe_stream.hpp>
 #include <beast/test/string_istream.hpp>
 #include <beast/test/string_ostream.hpp>