Doc work

doc/qbk/06_websocket/06_timeouts.qbk

@@ -27,22 +27,84 @@ stream. The interface to these timeout features is show in this table.
     This represents configured timeout settings for a websocket stream.
 ]]
 [[
-    [link beast.ref.boost__beast__websocket__stream_base__timeout `stream_base::timeout`]
+    [link beast.ref.boost__beast__websocket__stream_base__timeout.suggested `stream_base::timeout::suggested`]
 ][
-    This is the type of the object passed to the decorator to
+    This function returns the suggested timeout settings for a given role
-    represent HTTP Upgrade response.
+    (client or server).
-]]
-[[
-    [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.
+    This function sets timeout and other options on the stream.
 ]]
 ]
 
+There are three timeout settings which may be set independently on the stream:
+
+[table WebSocket Timeout Interface (2)
+[[Name][Type][Description]]
+[
+    [[link beast.ref.boost__beast__websocket__stream_base__timeout.handshake_timeout `timeout::handshake_timeout`]]
+    [`duration`]
+    [
+        This is the amount of time after which a handshake will time out.
+        The handshake timeout applies to client handshakes, server handshakes,
+        as well as the websocket closing handshake performed when either
+        end of the connection wish to shut down.
+        The value returned by
+        [link beast.ref.boost__beast__websocket__stream_base.none `stream_base::none()`]
+        may be assigned to disable this timeout.
+    ]
+][
+    [[link beast.ref.boost__beast__websocket__stream_base__timeout.idle_timeout `timeout::idle_timeout`]]
+    [`duration`]
+    [
+        If no data is received from the peer for a time equal to the idle
+        timeout, then the connection will time out.
+        The value returned by
+        [link beast.ref.boost__beast__websocket__stream_base.none `stream_base::none()`]
+        may be assigned to disable this timeout.
+    ]
+][
+    [[link beast.ref.boost__beast__websocket__stream_base__timeout.keep_alive_pings `timeout::keep_alive_pings`]]
+    [`bool`]
+    [
+        If the idle timeout is enabled, then the value of this setting
+        controls whether or not a ping frame will be sent to the peer if
+        no data is received for half of the idle timeout interval.
+    ]
+]
+]
+
+By default, timeouts on websocket streams are disabled. The easiest way
+to turn them on is to set the suggested timeout settings on the stream.
+
+[code_websocket_6_1]
+
+For manual control over the settings, a timeout options object may be
+constructed. Here we enable only the handshake timeout.
+
+[code_websocket_6_2]
+
+Timeout notifications are delivered to the caller by invoking the completion
+handler for an outstanding asynchronous read operation with the error code
+[link beast.ref.boost__beast__error `error::timeout`]. The implementation
+will close the socket or stream before delivering this error. It is not
+necessary to manually shut down the connection, as it will already be shut
+down. A read operation must be outstanding for the error to be delivered.
+
+[code_websocket_6_3]
+
+[note
+    Websocket timeout features are available only when using asynchronous I/O.
+]
+
+The timeouts on the websocket stream are incompatible with the timeouts
+used in the `tcp_stream`. When constructing a websocket stream from a tcp
+stream that has timeouts enabled, the timeout should be disabled first before
+constructing the websocket stream, as shown.
+
+[code_websocket_6_4]
+
+
 [endsect]

test/doc/websocket_6_timeouts.cpp

@@ -19,6 +19,8 @@
 #include <boost/asio.hpp>
 #include <boost/asio/ssl.hpp>
 
+#include <iostream>
+
 namespace {
 
 #include "websocket_common.ipp"
@@ -26,11 +28,58 @@ namespace {
 void
 snippets()
 {
+    {
+  
     stream<tcp_stream> ws(ioc);
 
     {
     //[code_websocket_6_1
 
+        // Apply suggested timeout options for the server role to the stream
+        ws.set_option(stream_base::timeout::suggested(role_type::server));
+
+    //]
+    }
+
+    {
+    //[code_websocket_6_2
+
+        stream_base::timeout opt{
+            std::chrono::seconds(30),   // handshake timeout
+            stream_base::none(),        // idle timeout
+            false
+        };
+
+        // Set the timeout options on the stream.
+        ws.set_option(opt);
+
+    //]
+    }
+
+    {
+        flat_buffer b;
+    //[code_websocket_6_3
+
+        ws.async_read(b,
+            [](error_code ec, std::size_t)
+            {
+                if(ec == beast::error::timeout)
+                    std::cerr << "timeout, connection closed!";
+            });
+    //]
+    }
+
+    }
+
+    {
+    //[code_websocket_6_4
+
+        // Disable any timeouts on the tcp_stream
+        sock.expires_never();
+
+        // Construct the websocket stream, taking ownership of the existing tcp_stream
+        stream<tcp_stream> ws(std::move(sock));
+
     //]
     }
 }

test/doc/websocket_common.ipp

@@ -10,6 +10,7 @@
 //[code_websocket_1b
 
 namespace net = boost::asio;
+namespace beast = boost::beast;
 using namespace boost::beast;
 using namespace boost::beast::websocket;