[/
    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]