stream_base::timeout::suggested is a nested function

CHANGELOG.md

@@ -1,3 +1,9 @@
+Version 222:
+
+* stream_base::timeout::suggested is a nested function
+
+--------------------------------------------------------------------------------
+
 Version 221:
 
 * Rename to async_base, stable_async_base

doc/qbk/06_websocket/04_messages.qbk

@@ -46,15 +46,15 @@ These stream members are used to write websocket messages:
 [[Function][Description]]
 [
     [
-        [link beast.ref.boost__beast__websocket__stream.write `write`],
+        [link beast.ref.boost__beast__websocket__stream.write.overload2 `write`],
         [link beast.ref.boost__beast__websocket__stream.async_write `async_write`]
     ][
         Send a buffer sequence as a complete message.
     ]
 ][
     [
-        [link beast.ref.boost__beast__websocket__stream.write_some `write_some`],
+        [link beast.ref.boost__beast__websocket__stream.write_some.overload2 `write_some`],
-        [link beast.ref.boost__beast__websocket__stream.async_write `async_write_some`]
+        [link beast.ref.boost__beast__websocket__stream.async_write_some `async_write_some`]
     ][
         Send a buffer sequence as part of a message.
     ]
@@ -72,7 +72,7 @@ The same message could be sent in two or more frames thusly.
 [[Function][Description]]
 [
     [
-        [link beast.ref.boost__beast__websocket__stream.read `read`],
+        [link beast.ref.boost__beast__websocket__stream.read.overload2 `read`],
         [link beast.ref.boost__beast__websocket__stream.async_read `async_read`]
     ][
         Read a complete message into a __DynamicBuffer__.
@@ -80,14 +80,14 @@ The same message could be sent in two or more frames thusly.
 ][
     [
         [link beast.ref.boost__beast__websocket__stream.read_some.overload2 `read_some`],
-        [link beast.ref.boost__beast__websocket__stream.async_read.overload1 `async_read_some`]
+        [link beast.ref.boost__beast__websocket__stream.async_read_some.overload1 `async_read_some`]
     ][
         Read part of a message into a __DynamicBuffer__.
     ]
 ][
     [
         [link beast.ref.boost__beast__websocket__stream.read_some.overload4 `read_some`],
-        [link beast.ref.boost__beast__websocket__stream.async_read.overload2 `async_read_some`]
+        [link beast.ref.boost__beast__websocket__stream.async_read_some.overload2 `async_read_some`]
     ][
         Read part of a message into a __MutableBufferSequence__.
     ]
@@ -117,6 +117,6 @@ message ahead of time:
 For these cases, the partial data oriented interface may be used. This
 example reads and echoes a complete message using this interface:
 
-[ws_snippet_16]
+[code_websocket_4_3]
 
 [endsect]

doc/qbk/06_websocket/06_timeouts.qbk

@@ -7,8 +7,42 @@
     Official repository: https://github.com/boostorg/beast
 ]
 
-[section Timeouts __new__]
-
 [/-----------------------------------------------------------------------------]
 
+[section Timeouts __new__]
+
+While
+[link beast.ref.boost__beast__basic_stream `basic_stream`] and
+[link beast.ref.boost__beast__basic_stream `tcp_stream`] support timeouts on
+general logical operations, the websocket stream has a more sophisticated timeout
+mechanism built-in which may be enabled and configured. The timeout features
+of the TCP or basic stream should not be used when working with a websocket
+stream. The interface to these timeout features is show in this table.
+
+[table WebSocket Timeout Interface
+[[Name][Description]]
+[[
+    [link beast.ref.boost__beast__websocket__stream_base__timeout `stream_base::timeout`]
+][
+    This represents configured timeout settings for a websocket stream.
+]]
+[[
+    [link beast.ref.boost__beast__websocket__stream_base__timeout `stream_base::timeout`]
+][
+    This is the type of the object passed to the decorator to
+    represent HTTP Upgrade response.
+]]
+[[
+    [link beast.ref.boost__beast__websocket__stream_base__decorator `stream_base::decorator`]
+][
+    Objects of this type are used to hold a decorator to be
+    set on the stream using `set_option`.
+]]
+[[
+    [link beast.ref.boost__beast__websocket__stream.set_option `stream::set_option`]
+][
+    This function is used to set a `stream_base::decorator` on the stream.
+]]
+]
+
 [endsect]

doc/qbk/main.qbk

@@ -138,7 +138,6 @@
 [import ../../test/doc/exemplars.cpp]
 [import ../../test/doc/core_snippets.cpp]
 [import ../../test/doc/http_snippets.cpp]
-[import ../../test/doc/websocket_snippets.cpp]
 
 [import ../../test/doc/core_1_refresher.cpp]
 [import ../../test/doc/core_3_timeouts.cpp]

doc/qbk/quickref.xml

@@ -303,7 +303,6 @@
         <bridgehead renderas="sect3">Options</bridgehead>
         <simplelist type="vert" columns="1">
           <member><link linkend="beast.ref.boost__beast__websocket__permessage_deflate">permessage_deflate</link></member>
-          <member><link linkend="beast.ref.boost__beast__websocket__stream_base.suggested_settings">suggested_settings</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
           <member><link linkend="beast.ref.boost__beast__websocket__stream_base__decorator">decorator</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
           <member><link linkend="beast.ref.boost__beast__websocket__stream_base__timeout">timeout</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
         </simplelist>

example/advanced/server-flex/advanced_server_flex.cpp

@@ -267,7 +267,7 @@ public:
     {
         // Set suggested timeout settings for the websocket
         derived().ws().set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake

example/advanced/server/advanced_server.cpp

@@ -237,7 +237,7 @@ public:
     {
         // Set suggested timeout settings for the websocket
         ws_.set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake

example/websocket/client/async-ssl/websocket_client_async_ssl.cpp

@@ -128,7 +128,7 @@ public:
 
         // Set suggested timeout settings for the websocket
         ws_.set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::client));
 
         // Set a decorator to change the User-Agent of the handshake

example/websocket/client/async/websocket_client_async.cpp

@@ -105,7 +105,7 @@ public:
 
         // Set suggested timeout settings for the websocket
         ws_.set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::client));
 
         // Set a decorator to change the User-Agent of the handshake

example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp

@@ -94,7 +94,7 @@ do_session(
 
     // Set suggested timeout settings for the websocket
     ws.set_option(
-        websocket::stream_base::suggested_settings(
+        websocket::stream_base::timeout::suggested(
             beast::role_type::client));
 
     // Perform the websocket handshake

example/websocket/client/coro/websocket_client_coro.cpp

@@ -70,7 +70,7 @@ do_session(
 
     // Set suggested timeout settings for the websocket
     ws.set_option(
-        websocket::stream_base::suggested_settings(
+        websocket::stream_base::timeout::suggested(
             beast::role_type::client));
 
     // Set a decorator to change the User-Agent of the handshake

example/websocket/server/async-ssl/websocket_server_async_ssl.cpp

@@ -86,7 +86,7 @@ public:
 
         // Set suggested timeout settings for the websocket
         ws_.set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake

example/websocket/server/async/websocket_server_async.cpp

@@ -60,7 +60,7 @@ public:
     {
         // Set suggested timeout settings for the websocket
         ws_.set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake

example/websocket/server/chat-multi/websocket_session.hpp

@@ -63,7 +63,7 @@ run(http::request<Body, http::basic_fields<Allocator>> req)
 {
     // Set suggested timeout settings for the websocket
     ws_.set_option(
-        websocket::stream_base::suggested_settings(
+        websocket::stream_base::timeout::suggested(
             beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake

example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp

@@ -68,7 +68,7 @@ do_session(
 
     // Set suggested timeout settings for the websocket
     ws.set_option(
-        websocket::stream_base::suggested_settings(
+        websocket::stream_base::timeout::suggested(
             beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake

example/websocket/server/coro/websocket_server_coro.cpp

@@ -50,7 +50,7 @@ do_session(
 
     // Set suggested timeout settings for the websocket
     ws.set_option(
-        websocket::stream_base::suggested_settings(
+        websocket::stream_base::timeout::suggested(
             beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake

example/websocket/server/fast/websocket_server_fast.cpp

@@ -158,7 +158,7 @@ public:
     {
         // Set suggested timeout settings for the websocket
         ws_.set_option(
-            websocket::stream_base::suggested_settings(
+            websocket::stream_base::timeout::suggested(
                 beast::role_type::server));
 
         // Set a decorator to change the Server of the handshake
@@ -338,7 +338,7 @@ do_coro_session(
 
     // Set suggested timeout settings for the websocket
     ws.set_option(
-        websocket::stream_base::suggested_settings(
+        websocket::stream_base::timeout::suggested(
             beast::role_type::server));
 
     // Set a decorator to change the Server of the handshake

example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp

@@ -98,7 +98,7 @@ public:
 
             // Set suggested timeout settings for the websocket
             ws_.set_option(
-                websocket::stream_base::suggested_settings(
+                websocket::stream_base::timeout::suggested(
                     beast::role_type::server));
 
             // Set a decorator to change the Server of the handshake

example/websocket/server/stackless/websocket_server_stackless.cpp

@@ -75,7 +75,7 @@ public:
         {
             // Set suggested timeout settings for the websocket
             ws_.set_option(
-                websocket::stream_base::suggested_settings(
+                websocket::stream_base::timeout::suggested(
                     beast::role_type::server));
 
             // Set a decorator to change the Server of the handshake

include/boost/beast/core/async_base.hpp

@@ -465,7 +465,7 @@ public:
     storage, the class @ref stable_async_base is provided which offers
     additional functionality:
 
-    @li The free function @ref allocate_stable may be used to allocate
+    @li The free function @ref beast::allocate_stable may be used to allocate
     one or more temporary objects associated with the composed operation.
 
     @li Memory for stable temporary objects is allocated using the allocator
@@ -482,7 +482,7 @@ public:
     assist authoring an asynchronous initiating function, by providing all of
     the boilerplate to manage the final completion handler in a way that maintains
     the allocator and executor associations. Furthermore, the operation shown
-    allocates temporary memory using @ref allocate_stable for the timer and
+    allocates temporary memory using @ref beast::allocate_stable for the timer and
     message, whose addresses must not change between intermediate operations:
 
     @code
@@ -592,7 +592,7 @@ public:
     not default constructible, an instance of the type must be provided
     upon construction.
 
-    @see @ref allocate_stable, @ref async_base
+    @see allocate_stable, async_base
 */
 template<
     class Handler,

include/boost/beast/websocket/stream_base.hpp

@@ -105,45 +105,46 @@ struct stream_base
             complete immediately the error @ref beast::error::timeout.
         */
         bool keep_alive_pings;
-    };
 
-    /** Construct timeout settings with suggested values for a role.
+        /** Construct timeout settings with suggested values for a role.
 
-        This constructs the timeout settings with a predefined set
+            This constructs the timeout settings with a predefined set
-        of values which varies depending on the desired role. The
+            of values which varies depending on the desired role. The
-        values are selected upon construction, regardless of the
+            values are selected upon construction, regardless of the
-        current or actual role in use on the stream.
+            current or actual role in use on the stream.
 
-        @par Example
+            @par Example
-        This statement sets the timeout settings of the stream to
+            This statement sets the timeout settings of the stream to
-        the suggested values for the server role:
+            the suggested values for the server role:
-        @code
+            @code
-        @endcode
+            @endcode
 
-        @param role The role of the websocket stream
+            @param role The role of the websocket stream
-        (@ref role_type::client or @ref role_type::server).
+            (@ref role_type::client or @ref role_type::server).
-    */
+        */
-    static
+        static
-    timeout
+        timeout
-    suggested_settings(role_type role) noexcept
+        suggested(role_type role) noexcept
-    {
-        timeout opt{};
-        switch(role)
         {
-        case role_type::client:
+            timeout opt{};
-            opt.handshake_timeout = std::chrono::seconds(30);
+            switch(role)
-            opt.idle_timeout = none();
+            {
-            opt.keep_alive_pings = false;
+            case role_type::client:
-            break;
+                opt.handshake_timeout = std::chrono::seconds(30);
+                opt.idle_timeout = none();
+                opt.keep_alive_pings = false;
+                break;
 
-        case role_type::server:
+            case role_type::server:
-            opt.handshake_timeout = std::chrono::seconds(30);
+                opt.handshake_timeout = std::chrono::seconds(30);
-            opt.idle_timeout = std::chrono::seconds(300);
+                opt.idle_timeout = std::chrono::seconds(300);
-            opt.keep_alive_pings = true;
+                opt.keep_alive_pings = true;
-            break;
+                break;
+            }
+            return opt;
         }
-        return opt;
+
-    }
+    };
 
 protected:
     enum class status

test/beast/websocket/stream.cpp

@@ -45,11 +45,11 @@ public:
 
         {
             ws.set_option(
-                stream_base::suggested_settings(
+                stream_base::timeout::suggested(
                     role_type::client));
 
             ws.set_option(
-                stream_base::suggested_settings(
+                stream_base::timeout::suggested(
                     role_type::server));
 
             ws.set_option({

test/doc/websocket_7_teardown.cpp

@@ -88,7 +88,7 @@ snippets()
     //stream<tcp_stream> ws(ioc);
 
     {
-    //[code_websocket_7_1
+    //[code_websocket_7_3
 
     //]
     }