1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[/-----------------------------------------------------------------------------] 11 12[section:timeouts Timeouts] 13 14While 15[link beast.ref.boost__beast__basic_stream `basic_stream`] and 16[link beast.ref.boost__beast__basic_stream `tcp_stream`] support timeouts on 17general logical operations, the websocket stream has a more sophisticated timeout 18mechanism built-in which may be enabled and configured. The timeout features 19of the TCP or basic stream should not be used when working with a websocket 20stream. The interface to these timeout features is show in this table. 21 22[table WebSocket Timeout Interface 23[[Name][Description]] 24[[ 25 [link beast.ref.boost__beast__websocket__stream_base__timeout `stream_base::timeout`] 26][ 27 This represents configured timeout settings for a websocket stream. 28]] 29[[ 30 [link beast.ref.boost__beast__websocket__stream_base__timeout.suggested `stream_base::timeout::suggested`] 31][ 32 This function returns the suggested timeout settings for a given role 33 (client or server). 34]] 35[[ 36 [link beast.ref.boost__beast__websocket__stream.set_option `stream::set_option`] 37][ 38 This function sets timeout and other options on the stream. 39]] 40] 41 42There are three timeout settings which may be set independently on the stream: 43 44[table WebSocket Timeout Interface (2) 45[[Name][Type][Description]] 46[ 47 [[link beast.ref.boost__beast__websocket__stream_base__timeout.handshake_timeout `timeout::handshake_timeout`]] 48 [`duration`] 49 [ 50 This is the amount of time after which a handshake will time out. 51 The handshake timeout applies to client handshakes, server handshakes, 52 as well as the websocket closing handshake performed when either 53 end of the connection wish to shut down. 54 The value returned by 55 [link beast.ref.boost__beast__websocket__stream_base.none `stream_base::none()`] 56 may be assigned to disable this timeout. 57 ] 58][ 59 [[link beast.ref.boost__beast__websocket__stream_base__timeout.idle_timeout `timeout::idle_timeout`]] 60 [`duration`] 61 [ 62 If no data is received from the peer for a time equal to the idle 63 timeout, then the connection will time out. 64 The value returned by 65 [link beast.ref.boost__beast__websocket__stream_base.none `stream_base::none()`] 66 may be assigned to disable this timeout. 67 ] 68][ 69 [[link beast.ref.boost__beast__websocket__stream_base__timeout.keep_alive_pings `timeout::keep_alive_pings`]] 70 [`bool`] 71 [ 72 If the idle timeout is enabled, then the value of this setting 73 controls whether or not a ping frame will be sent to the peer if 74 no data is received for half of the idle timeout interval. 75 ] 76] 77] 78 79By default, timeouts on websocket streams are disabled. The easiest way 80to turn them on is to set the suggested timeout settings on the stream. 81 82[code_websocket_6_1] 83 84For manual control over the settings, a timeout options object may be 85constructed. Here we enable only the handshake timeout. 86 87[code_websocket_6_2] 88 89Timeout notifications are delivered to the caller by invoking the completion 90handler for an outstanding asynchronous read operation with the error code 91[link beast.ref.boost__beast__error `error::timeout`]. The implementation 92will close the socket or stream before delivering this error. It is not 93necessary to manually shut down the connection, as it will already be shut 94down. A read operation must be outstanding for the error to be delivered. 95 96[code_websocket_6_3] 97 98[note 99 Websocket timeout features are available only when using asynchronous I/O. 100] 101 102The timeouts on the websocket stream are incompatible with the timeouts 103used in the `tcp_stream`. When constructing a websocket stream from a tcp 104stream that has timeouts enabled, the timeout should be disabled first before 105constructing the websocket stream, as shown. 106 107[code_websocket_6_4] 108 109 110[endsect] 111