111 lines
4.1 KiB
Plaintext
111 lines
4.1 KiB
Plaintext
[/
|
|
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]
|