diff --git a/CHANGELOG.md b/CHANGELOG.md index 116766f1..2507f90c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/doc/qbk/06_websocket/04_messages.qbk b/doc/qbk/06_websocket/04_messages.qbk index 32f6acd8..016ea1a7 100644 --- a/doc/qbk/06_websocket/04_messages.qbk +++ b/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.async_write `async_write_some`] + [link beast.ref.boost__beast__websocket__stream.write_some.overload2 `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] diff --git a/doc/qbk/06_websocket/06_timeouts.qbk b/doc/qbk/06_websocket/06_timeouts.qbk index 5c31ff32..bd726a1f 100644 --- a/doc/qbk/06_websocket/06_timeouts.qbk +++ b/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] diff --git a/doc/qbk/main.qbk b/doc/qbk/main.qbk index 92535c82..e52a909a 100644 --- a/doc/qbk/main.qbk +++ b/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] diff --git a/doc/qbk/quickref.xml b/doc/qbk/quickref.xml index d94c8ec5..3eaf71f7 100644 --- a/doc/qbk/quickref.xml +++ b/doc/qbk/quickref.xml @@ -303,7 +303,6 @@ Options permessage_deflate - suggested_settings ★ decorator ★ timeout ★ diff --git a/example/advanced/server-flex/advanced_server_flex.cpp b/example/advanced/server-flex/advanced_server_flex.cpp index 668bf183..44c89d93 100644 --- a/example/advanced/server-flex/advanced_server_flex.cpp +++ b/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 diff --git a/example/advanced/server/advanced_server.cpp b/example/advanced/server/advanced_server.cpp index e5c9e0c3..aff62c30 100644 --- a/example/advanced/server/advanced_server.cpp +++ b/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 diff --git a/example/websocket/client/async-ssl/websocket_client_async_ssl.cpp b/example/websocket/client/async-ssl/websocket_client_async_ssl.cpp index 26852f1c..6e7a1bbb 100644 --- a/example/websocket/client/async-ssl/websocket_client_async_ssl.cpp +++ b/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 diff --git a/example/websocket/client/async/websocket_client_async.cpp b/example/websocket/client/async/websocket_client_async.cpp index d644a89e..eda86911 100644 --- a/example/websocket/client/async/websocket_client_async.cpp +++ b/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 diff --git a/example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp b/example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp index e7d154ee..a8525214 100644 --- a/example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp +++ b/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 diff --git a/example/websocket/client/coro/websocket_client_coro.cpp b/example/websocket/client/coro/websocket_client_coro.cpp index 310be162..424697b8 100644 --- a/example/websocket/client/coro/websocket_client_coro.cpp +++ b/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 diff --git a/example/websocket/server/async-ssl/websocket_server_async_ssl.cpp b/example/websocket/server/async-ssl/websocket_server_async_ssl.cpp index 24b4042d..e45afd67 100644 --- a/example/websocket/server/async-ssl/websocket_server_async_ssl.cpp +++ b/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 diff --git a/example/websocket/server/async/websocket_server_async.cpp b/example/websocket/server/async/websocket_server_async.cpp index 545279f1..39f47895 100644 --- a/example/websocket/server/async/websocket_server_async.cpp +++ b/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 diff --git a/example/websocket/server/chat-multi/websocket_session.hpp b/example/websocket/server/chat-multi/websocket_session.hpp index 250ded5b..c47d48ac 100644 --- a/example/websocket/server/chat-multi/websocket_session.hpp +++ b/example/websocket/server/chat-multi/websocket_session.hpp @@ -63,7 +63,7 @@ run(http::request> 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 diff --git a/example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp b/example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp index 6cd603e9..cb9e08eb 100644 --- a/example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp +++ b/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 diff --git a/example/websocket/server/coro/websocket_server_coro.cpp b/example/websocket/server/coro/websocket_server_coro.cpp index 45a9b5db..b1c875f8 100644 --- a/example/websocket/server/coro/websocket_server_coro.cpp +++ b/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 diff --git a/example/websocket/server/fast/websocket_server_fast.cpp b/example/websocket/server/fast/websocket_server_fast.cpp index 14a8d9be..ad4857ad 100644 --- a/example/websocket/server/fast/websocket_server_fast.cpp +++ b/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 diff --git a/example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp b/example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp index cc77b2c0..5f5c840c 100644 --- a/example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp +++ b/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 diff --git a/example/websocket/server/stackless/websocket_server_stackless.cpp b/example/websocket/server/stackless/websocket_server_stackless.cpp index f9058a55..5d3e5e0b 100644 --- a/example/websocket/server/stackless/websocket_server_stackless.cpp +++ b/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 diff --git a/include/boost/beast/core/async_base.hpp b/include/boost/beast/core/async_base.hpp index 5124abe7..a301ccc2 100644 --- a/include/boost/beast/core/async_base.hpp +++ b/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, diff --git a/include/boost/beast/websocket/stream_base.hpp b/include/boost/beast/websocket/stream_base.hpp index 51600b40..2986eb25 100644 --- a/include/boost/beast/websocket/stream_base.hpp +++ b/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 - of values which varies depending on the desired role. The - values are selected upon construction, regardless of the - current or actual role in use on the stream. + This constructs the timeout settings with a predefined set + of values which varies depending on the desired role. The + values are selected upon construction, regardless of the + current or actual role in use on the stream. - @par Example - This statement sets the timeout settings of the stream to - the suggested values for the server role: - @code - @endcode + @par Example + This statement sets the timeout settings of the stream to + the suggested values for the server role: + @code + @endcode - @param role The role of the websocket stream - (@ref role_type::client or @ref role_type::server). - */ - static - timeout - suggested_settings(role_type role) noexcept - { - timeout opt{}; - switch(role) + @param role The role of the websocket stream + (@ref role_type::client or @ref role_type::server). + */ + static + timeout + suggested(role_type role) noexcept { - case role_type::client: - opt.handshake_timeout = std::chrono::seconds(30); - opt.idle_timeout = none(); - opt.keep_alive_pings = false; - break; + timeout opt{}; + switch(role) + { + case role_type::client: + opt.handshake_timeout = std::chrono::seconds(30); + opt.idle_timeout = none(); + opt.keep_alive_pings = false; + break; - case role_type::server: - opt.handshake_timeout = std::chrono::seconds(30); - opt.idle_timeout = std::chrono::seconds(300); - opt.keep_alive_pings = true; - break; + case role_type::server: + opt.handshake_timeout = std::chrono::seconds(30); + opt.idle_timeout = std::chrono::seconds(300); + opt.keep_alive_pings = true; + break; + } + return opt; } - return opt; - } + + }; protected: enum class status diff --git a/test/beast/websocket/stream.cpp b/test/beast/websocket/stream.cpp index 984c7ebb..5214bd79 100644 --- a/test/beast/websocket/stream.cpp +++ b/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({ diff --git a/test/doc/websocket_7_teardown.cpp b/test/doc/websocket_7_teardown.cpp index 363c742b..8b81a02b 100644 --- a/test/doc/websocket_7_teardown.cpp +++ b/test/doc/websocket_7_teardown.cpp @@ -88,7 +88,7 @@ snippets() //stream ws(ioc); { - //[code_websocket_7_1 + //[code_websocket_7_3 //] }