123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110 |
- [/
- Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- Official repository: https://github.com/boostorg/beast
- ]
- [/-----------------------------------------------------------------------------]
- [section:timeouts Timeouts]
- 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.suggested `stream_base::timeout::suggested`]
- ][
- This function returns the suggested timeout settings for a given role
- (client or server).
- ]]
- [[
- [link beast.ref.boost__beast__websocket__stream.set_option `stream::set_option`]
- ][
- 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]
|