write_buffer_size is a member of stream (API Change):

fix #446

* The write_buffer_size option struct is removed.

Actions Required:

* Change call sites which use write_buffer_size with set_option to
  call stream::write_buffer_size instead.

CHANGELOG.md

@@ -6,6 +6,7 @@ API Changes:
 * binary, text are members of stream
 * read_buffer_size is a member of stream
 * read_message_max is a member of stream
+* write_buffer_size is a member of stream
 
 Actions Required:
 
@@ -21,6 +22,9 @@ Actions Required:
 * Change call sites which use read_message_max with set_option to
   call stream::read_message_max instead.
 
+* Change call sites which use write_buffer_size with set_option to
+  call stream::write_buffer_size instead.
+
 --------------------------------------------------------------------------------
 
 Version 51

doc/quickref.xml

@@ -125,7 +125,6 @@
           <simplelist type="vert" columns="1">
             <member><link linkend="beast.ref.websocket__permessage_deflate">permessage_deflate</link></member>
             <member><link linkend="beast.ref.websocket__ping_callback">ping_callback</link></member>
-            <member><link linkend="beast.ref.websocket__write_buffer_size">write_buffer_size</link></member>
           </simplelist>
           <bridgehead renderas="sect3">Constants</bridgehead>
           <simplelist type="vert" columns="1">

include/beast/websocket/option.hpp

@@ -124,51 +124,6 @@ struct ping_callback
 };
 #endif
 
-/** Write buffer size option.
-
-    Sets the size of the write buffer used by the implementation to
-    send frames. The write buffer is needed when masking payload data
-    in the client role, compressing frames, or auto-fragmenting message
-    data.
-
-    Lowering the size of the buffer can decrease the memory requirements
-    for each connection, while increasing the size of the buffer can reduce
-    the number of calls made to the next layer to write data.
-
-    The default setting is 4096. The minimum value is 8.
-
-    The write buffer size can only be changed when the stream is not
-    open. Undefined behavior results if the option is modified after a
-    successful WebSocket handshake.
-
-    @note Objects of this type are used with
-          @ref beast::websocket::stream::set_option.
-
-    @par Example
-    Setting the write buffer size.
-    @code
-    ...
-    websocket::stream<ip::tcp::socket> ws(ios);
-    ws.set_option(write_buffer_size{8192});
-    @endcode
-*/
-#if BEAST_DOXYGEN
-using write_buffer_size = implementation_defined;
-#else
-struct write_buffer_size
-{
-    std::size_t value;
-
-    explicit
-    write_buffer_size(std::size_t n)
-        : value(n)
-    {
-        if(n < 8)
-            BOOST_THROW_EXCEPTION(std::invalid_argument{
-                "write buffer size is too small"});
-    }
-};
-#endif
 
 } // websocket
 } // beast

include/beast/websocket/stream.hpp

@@ -263,13 +263,6 @@ public:
         ping_cb_ = std::move(o.value);
     }
 
-    /// Set the size of the write buffer
-    void
-    set_option(write_buffer_size const& o)
-    {
-        wr_buf_size_ = o.value;
-    }
-
     /** Set the automatic fragmentation option.
 
         Determines if outgoing message payloads are broken up into
@@ -281,6 +274,8 @@ public:
 
         The default setting is to fragment messages.
 
+        @param v A `bool` indicating if auto fragmentation should be on.
+
         @par Example
         Setting the automatic fragmentation option:
         @code
@@ -310,15 +305,15 @@ public:
 
         The default setting is to send text messages.
 
+        @param v `true` if outgoing messages should indicate
+        binary, or `false` if they should indicate text.
+
         @par Example
         Setting the message type to binary.
         @code
             ws.binary(true);
         @endcode
-
+        */
-        @param v `true` if outgoing messages should indicate
-        binary, or `false` if they should indicate text.
-    */
     void
     binary(bool v)
     {
@@ -344,22 +339,22 @@ public:
 
         The default setting is 4096. The minimum value is 8.
 
+        @param n The size of the read buffer.
+
+        @throw std::invalid_argument If the buffer size is less than 8.
+
         @par Example
         Setting the read buffer size.
         @code
             ws.read_buffer_size(16 * 1024);
         @endcode
-
-        @param n The size of the read buffer.
-
-        @throw std::invalid_argument If the buffer size is less than 8.
     */
     void
     read_buffer_size(std::size_t n)
     {
         if(n < 8)
             BOOST_THROW_EXCEPTION(std::invalid_argument{
-                "read buffer size is too small"});
+                "read buffer size underflow"});
         rd_buf_size_ = n;
     }
 
@@ -400,6 +395,47 @@ public:
         return rd_msg_max_;
     }
 
+    /** Set the write buffer size option.
+
+        Sets the size of the write buffer used by the implementation to
+        send frames. The write buffer is needed when masking payload data
+        in the client role, compressing frames, or auto-fragmenting message
+        data.
+
+        Lowering the size of the buffer can decrease the memory requirements
+        for each connection, while increasing the size of the buffer can reduce
+        the number of calls made to the next layer to write data.
+
+        The default setting is 4096. The minimum value is 8.
+
+        The write buffer size can only be changed when the stream is not
+        open. Undefined behavior results if the option is modified after a
+        successful WebSocket handshake.
+
+        @par Example
+        Setting the write buffer size.
+        @code
+            ws.write_buffer_size(8192);
+        @endcode
+
+        @param n The size of the write buffer in bytes.
+    */
+    void
+    write_buffer_size(std::size_t n)
+    {
+        if(n < 8)
+            BOOST_THROW_EXCEPTION(std::invalid_argument{
+                "write buffer size underflow"});
+        wr_buf_size_ = n;
+    };
+
+    /// Returns the size of the write buffer.
+    std::size_t
+    write_buffer_size() const
+    {
+        return wr_buf_size_;
+    }
+
     /** Returns the close reason received from the peer.
 
         This is only valid after a read completes with error::closed.

test/websocket/doc_snippets.cpp

@@ -206,7 +206,7 @@ boost::asio::ip::tcp::socket sock{ios};
 
 //[ws_snippet_19
     ws.auto_fragment(true);
-    ws.set_option(write_buffer_size{16384});
+    ws.write_buffer_size(16384);
 //]
 
 //[ws_snippet_20

test/websocket/stream.cpp

@@ -554,13 +554,13 @@ public:
     {
         stream<socket_type> ws(ios_);
         ws.auto_fragment(true);
-        ws.set_option(write_buffer_size{2048});
+        ws.write_buffer_size(2048);
         ws.binary(false);
         ws.read_buffer_size(8192);
         ws.read_message_max(1 * 1024 * 1024);
         try
         {
-            ws.set_option(write_buffer_size{7});
+            ws.write_buffer_size(7);
             fail();
         }
         catch(std::exception const&)
@@ -1720,7 +1720,7 @@ public:
 
                 // send auto fragmented message
                 ws.auto_fragment(true);
-                ws.set_option(write_buffer_size{8});
+                ws.write_buffer_size(8);
                 c.write(ws, sbuf("Now is the time for all good men"));
                 {
                     // receive echoed message
@@ -1730,12 +1730,12 @@ public:
                     BEAST_EXPECT(to_string(b.data()) == "Now is the time for all good men");
                 }
                 ws.auto_fragment(false);
-                ws.set_option(write_buffer_size{4096});
+                ws.write_buffer_size(4096);
 
                 // send message with write buffer limit
                 {
                     std::string s(2000, '*');
-                    ws.set_option(write_buffer_size(1200));
+                    ws.write_buffer_size(1200);
                     c.write(ws, buffer(s.data(), s.size()));
                     {
                         // receive echoed message