1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Timeouts</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast"> 8<link rel="up" href="../using_websocket.html" title="WebSocket"> 9<link rel="prev" href="control_frames.html" title="Control Frames"> 10<link rel="next" href="teardown.html" title="Teardown"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="control_frames.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="teardown.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="beast.using_websocket.timeouts"></a><a class="link" href="timeouts.html" title="Timeouts">Timeouts</a> 28</h3></div></div></div> 29<p> 30 While <a class="link" href="../ref/boost__beast__basic_stream.html" title="basic_stream"><code class="computeroutput"><span class="identifier">basic_stream</span></code></a> and <a class="link" href="../ref/boost__beast__basic_stream.html" title="basic_stream"><code class="computeroutput"><span class="identifier">tcp_stream</span></code></a> support timeouts on general 31 logical operations, the websocket stream has a more sophisticated timeout 32 mechanism built-in which may be enabled and configured. The timeout features 33 of the TCP or basic stream should not be used when working with a websocket 34 stream. The interface to these timeout features is show in this table. 35 </p> 36<div class="table"> 37<a name="beast.using_websocket.timeouts.websocket_timeout_interface"></a><p class="title"><b>Table 1.35. WebSocket Timeout Interface</b></p> 38<div class="table-contents"><table class="table" summary="WebSocket Timeout Interface"> 39<colgroup> 40<col> 41<col> 42</colgroup> 43<thead><tr> 44<th> 45 <p> 46 Name 47 </p> 48 </th> 49<th> 50 <p> 51 Description 52 </p> 53 </th> 54</tr></thead> 55<tbody> 56<tr> 57<td> 58 <p> 59 <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout.html" title="websocket::stream_base::timeout"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span></code></a> 60 </p> 61 </td> 62<td> 63 <p> 64 This represents configured timeout settings for a websocket stream. 65 </p> 66 </td> 67</tr> 68<tr> 69<td> 70 <p> 71 <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/suggested.html" title="websocket::stream_base::timeout::suggested"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">suggested</span></code></a> 72 </p> 73 </td> 74<td> 75 <p> 76 This function returns the suggested timeout settings for a given 77 role (client or server). 78 </p> 79 </td> 80</tr> 81<tr> 82<td> 83 <p> 84 <a class="link" href="../ref/boost__beast__websocket__stream/set_option.html" title="websocket::stream::set_option"><code class="computeroutput"><span class="identifier">stream</span><span class="special">::</span><span class="identifier">set_option</span></code></a> 85 </p> 86 </td> 87<td> 88 <p> 89 This function sets timeout and other options on the stream. 90 </p> 91 </td> 92</tr> 93</tbody> 94</table></div> 95</div> 96<br class="table-break"><p> 97 There are three timeout settings which may be set independently on the stream: 98 </p> 99<div class="table"> 100<a name="beast.using_websocket.timeouts.websocket_timeout_interface_2"></a><p class="title"><b>Table 1.36. WebSocket Timeout Interface (2)</b></p> 101<div class="table-contents"><table class="table" summary="WebSocket Timeout Interface (2)"> 102<colgroup> 103<col> 104<col> 105<col> 106</colgroup> 107<thead><tr> 108<th> 109 <p> 110 Name 111 </p> 112 </th> 113<th> 114 <p> 115 Type 116 </p> 117 </th> 118<th> 119 <p> 120 Description 121 </p> 122 </th> 123</tr></thead> 124<tbody> 125<tr> 126<td> 127 <p> 128 <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/handshake_timeout.html" title="websocket::stream_base::timeout::handshake_timeout"><code class="computeroutput"><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">handshake_timeout</span></code></a> 129 </p> 130 </td> 131<td> 132 <p> 133 <code class="computeroutput"><span class="identifier">duration</span></code> 134 </p> 135 </td> 136<td> 137 <p> 138 This is the amount of time after which a handshake will time out. 139 The handshake timeout applies to client handshakes, server handshakes, 140 as well as the websocket closing handshake performed when either 141 end of the connection wish to shut down. The value returned by 142 <a class="link" href="../ref/boost__beast__websocket__stream_base/none.html" title="websocket::stream_base::none"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">none</span><span class="special">()</span></code></a> 143 may be assigned to disable this timeout. 144 </p> 145 </td> 146</tr> 147<tr> 148<td> 149 <p> 150 <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/idle_timeout.html" title="websocket::stream_base::timeout::idle_timeout"><code class="computeroutput"><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">idle_timeout</span></code></a> 151 </p> 152 </td> 153<td> 154 <p> 155 <code class="computeroutput"><span class="identifier">duration</span></code> 156 </p> 157 </td> 158<td> 159 <p> 160 If no data is received from the peer for a time equal to the idle 161 timeout, then the connection will time out. The value returned 162 by <a class="link" href="../ref/boost__beast__websocket__stream_base/none.html" title="websocket::stream_base::none"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">none</span><span class="special">()</span></code></a> 163 may be assigned to disable this timeout. 164 </p> 165 </td> 166</tr> 167<tr> 168<td> 169 <p> 170 <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/keep_alive_pings.html" title="websocket::stream_base::timeout::keep_alive_pings"><code class="computeroutput"><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">keep_alive_pings</span></code></a> 171 </p> 172 </td> 173<td> 174 <p> 175 <code class="computeroutput"><span class="keyword">bool</span></code> 176 </p> 177 </td> 178<td> 179 <p> 180 If the idle timeout is enabled, then the value of this setting 181 controls whether or not a ping frame will be sent to the peer if 182 no data is received for half of the idle timeout interval. 183 </p> 184 </td> 185</tr> 186</tbody> 187</table></div> 188</div> 189<br class="table-break"><p> 190 By default, timeouts on websocket streams are disabled. The easiest way to 191 turn them on is to set the suggested timeout settings on the stream. 192 </p> 193<pre class="programlisting"><span class="comment">// Apply suggested timeout options for the server role to the stream</span> 194<span class="identifier">ws</span><span class="special">.</span><span class="identifier">set_option</span><span class="special">(</span><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">suggested</span><span class="special">(</span><span class="identifier">role_type</span><span class="special">::</span><span class="identifier">server</span><span class="special">));</span> 195</pre> 196<p> 197 For manual control over the settings, a timeout options object may be constructed. 198 Here we enable only the handshake timeout. 199 </p> 200<pre class="programlisting"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span> <span class="identifier">opt</span><span class="special">{</span> 201 <span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">30</span><span class="special">),</span> <span class="comment">// handshake timeout</span> 202 <span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">none</span><span class="special">(),</span> <span class="comment">// idle timeout</span> 203 <span class="keyword">false</span> 204<span class="special">};</span> 205 206<span class="comment">// Set the timeout options on the stream.</span> 207<span class="identifier">ws</span><span class="special">.</span><span class="identifier">set_option</span><span class="special">(</span><span class="identifier">opt</span><span class="special">);</span> 208</pre> 209<p> 210 Timeout notifications are delivered to the caller by invoking the completion 211 handler for an outstanding asynchronous read operation with the error code 212 <a class="link" href="../ref/boost__beast__error.html" title="error"><code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">timeout</span></code></a>. 213 The implementation will close the socket or stream before delivering this 214 error. It is not necessary to manually shut down the connection, as it will 215 already be shut down. A read operation must be outstanding for the error 216 to be delivered. 217 </p> 218<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> 219 <span class="special">[](</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)</span> 220 <span class="special">{</span> 221 <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span> <span class="special">==</span> <span class="identifier">beast</span><span class="special">::</span><span class="identifier">error</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">)</span> 222 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="string">"timeout, connection closed!"</span><span class="special">;</span> 223 <span class="special">});</span> 224</pre> 225<div class="note"><table border="0" summary="Note"> 226<tr> 227<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 228<th align="left">Note</th> 229</tr> 230<tr><td align="left" valign="top"><p> 231 Websocket timeout features are available only when using asynchronous I/O. 232 </p></td></tr> 233</table></div> 234<p> 235 The timeouts on the websocket stream are incompatible with the timeouts used 236 in the <code class="computeroutput"><span class="identifier">tcp_stream</span></code>. When constructing 237 a websocket stream from a tcp stream that has timeouts enabled, the timeout 238 should be disabled first before constructing the websocket stream, as shown. 239 </p> 240<pre class="programlisting"><span class="comment">// Disable any timeouts on the tcp_stream</span> 241<span class="identifier">sock</span><span class="special">.</span><span class="identifier">expires_never</span><span class="special">();</span> 242 243<span class="comment">// Construct the websocket stream, taking ownership of the existing tcp_stream</span> 244<span class="identifier">stream</span><span class="special"><</span><span class="identifier">tcp_stream</span><span class="special">></span> <span class="identifier">ws</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sock</span><span class="special">));</span> 245</pre> 246</div> 247<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 248<td align="left"></td> 249<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 250 Falco<p> 251 Distributed under the Boost Software License, Version 1.0. (See accompanying 252 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 253 </p> 254</div></td> 255</tr></table> 256<hr> 257<div class="spirit-nav"> 258<a accesskey="p" href="control_frames.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="teardown.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 259</div> 260</body> 261</html> 262
