67 lines
2.8 KiB
Plaintext
67 lines
2.8 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 Teardown]
|
|
|
|
The WebSocket protocol requirements described in rfc6455 section 7.1.1
|
|
outline an operation described as
|
|
[@https://tools.ietf.org/html/rfc6455#section-7.1.1 ['Close the WebSocket Connection]].
|
|
This operation cleanly discards bytes remaining at receiving endpoints
|
|
and also closes the underlying TCP/IP connection. Orderly shutdowns are
|
|
always preferred; for TLS or SSL streams, a protocol-level shutdown is
|
|
desired. This presents a small issue for the
|
|
[link beast.ref.boost__beast__websocket__stream `stream`]
|
|
implementation: the stream's `NextLayer` template type requires only
|
|
__SyncStream__ or __AsyncStream__, but those concepts do not support
|
|
the operations to shut down the connection.
|
|
|
|
To enable the implementation to perform the shutdown components of the
|
|
close operation, the library exposes two customization points expressed
|
|
as free functions associated with the next layer type:
|
|
|
|
* [link beast.ref.boost__beast__websocket__teardown `teardown`]: Overloads
|
|
of this function drain and shut down a stream synchronously.
|
|
|
|
* [link beast.ref.boost__beast__websocket__teardown `async_teardown`]:
|
|
Overloads of this function drain and shut down a stream asynchronously.
|
|
|
|
The implementation provides suitable overloads of the teardown
|
|
customization points when websocket streams are instantiated using the
|
|
Asio types __socket__ or __ssl_stream__ for the next layer. In this
|
|
case no user action is required. However, when the websocket stream is
|
|
instantiated for a user-defined type, compile errors will result if the
|
|
customization points are not provided for the user defined type.
|
|
Furthermore, user-defined types that wrap one of the Asio objects
|
|
mentioned earlier may wish to invoke a teardown customization point
|
|
for the wrapped object. This is how those tasks are accomplished.
|
|
|
|
[heading User-defined Teardown]
|
|
|
|
To provide overloads of teardown for a user-defined type, simply declare
|
|
the two free functions with the correct signature, accepting a reference
|
|
to the user-defined type as the stream parameter:
|
|
|
|
[code_websocket_7_1]
|
|
|
|
When the implementation invokes the asynchronous teardown function, it
|
|
always uses an invokable completion handler. It is not necessary
|
|
to specify the return type customization when creating user-defined
|
|
overloads of `async_teardown`.
|
|
|
|
[heading Invoking Teardown]
|
|
|
|
To invoke the customization point, first bring the default implementation
|
|
into scope with a `using` statement. Then call the customization point
|
|
without namespace qualification, allowing argument-dependent lookup to
|
|
take effect:
|
|
|
|
[code_websocket_7_2]
|
|
|
|
[endsect]
|