Fixes and documentation for teardown and use with SSL:

This solves a problem where clang and gcc locate the deleted
version of teardown and async_teardown instead of the overloaded
version. It requires overloads to add `teardown_tag` into the signature
so that the rules for argument dependent lookup can find the
right function. Improve documentation of teardown requirements

The documentation is updated to clearly explain the need for including
<beast/websocket/ssl.hpp> to use SSL streams with WebSocket.

The default implementations of teardown and async_teardown now use
static_assert to alert the user of improper usage, with comments
providing guidance for resolving the error.

include/beast/websocket/impl/ssl.ipp

@@ -129,7 +129,7 @@ operator()(error_code ec, bool again)
 
 template<class AsyncStream>
 void
-teardown(
+teardown(teardown_tag,
     boost::asio::ssl::stream<AsyncStream>& stream,
         error_code& ec)
 {
@@ -138,7 +138,7 @@ teardown(
 
 template<class AsyncStream, class TeardownHandler>
 void
-async_teardown(
+async_teardown(teardown_tag,
     boost::asio::ssl::stream<AsyncStream>& stream,
         TeardownHandler&& handler)
 {

include/beast/websocket/impl/teardown.ipp

@@ -128,7 +128,7 @@ operator()(error_code ec, std::size_t, bool again)
 
 inline
 void
-teardown(
+teardown(teardown_tag,
     boost::asio::ip::tcp::socket& socket,
         error_code& ec)
 {
@@ -151,7 +151,7 @@ teardown(
 template<class TeardownHandler>
 inline
 void
-async_teardown(
+async_teardown(teardown_tag,
     boost::asio::ip::tcp::socket& socket,
         TeardownHandler&& handler)
 {

include/beast/websocket/ssl.hpp

@@ -31,7 +31,7 @@ namespace websocket {
 */
 template<class SyncStream>
 void
-teardown(
+teardown(teardown_tag,
     boost::asio::ssl::stream<SyncStream>& stream,
         error_code& ec);
 
@@ -62,7 +62,7 @@ teardown(
 template<class AsyncStream, class TeardownHandler>
 inline
 void
-async_teardown(
+async_teardown(teardown_tag,
     boost::asio::ssl::stream<AsyncStream>& stream,
         TeardownHandler&& handler);
 

include/beast/websocket/teardown.hpp

@@ -13,8 +13,17 @@
 #include <type_traits>
 
 namespace beast {
+
 namespace websocket {
 
+/** Tag type used to find teardown and async_teardown overloads
+    
+    Overloads of @ref teardown and @async_teardown for user defined
+    types must take a value of type @ref teardown_tag in the first
+    argument in order to be found by the implementation.
+*/
+struct teardown_tag {};
+
 /** Tear down a connection.
 
     This tears down a connection. The implementation will call
@@ -30,7 +39,19 @@ namespace websocket {
 */
 template<class Socket>
 void
-teardown(Socket& socket, error_code& ec) = delete;
+teardown(teardown_tag, Socket& socket, error_code& ec)
+{
+/*
+    If you are trying to use OpenSSL and this goes off, you need to
+    add an include for <beast/websocket/ssl.hpp>.
+
+    If you are creating an instance of beast::websocket::stream with your
+    own user defined type, you must provide an overload of teardown with
+    the corresponding signature (including the teardown_tag).
+*/
+    static_assert(sizeof(Socket)==-1,
+        "Unknown Socket type in teardown.");
+};
 
 /** Start tearing down a connection.
 
@@ -49,7 +70,8 @@ teardown(Socket& socket, error_code& ec) = delete;
     function signature of the handler must be:
     @code void handler(
         error_code const& error // result of operation
-    ); @endcode
+    );
+    @endcode
     Regardless of whether the asynchronous operation completes
     immediately or not, the handler will not be invoked from within
     this function. Invocation of the handler will be performed in a
@@ -58,57 +80,19 @@ teardown(Socket& socket, error_code& ec) = delete;
 */
 template<class Socket, class TeardownHandler>
 void
-async_teardown(Socket& socket, TeardownHandler&& handler) = delete;
+async_teardown(teardown_tag, Socket& socket, TeardownHandler&& handler)
+{
+/*
+    If you are trying to use OpenSSL and this goes off, you need to
+    add an include for <beast/websocket/ssl.hpp>.
 
-//------------------------------------------------------------------------------
-
-/** Tear down a `boost::asio::ip::tcp::socket`.
-
-    This tears down a connection. The implementation will call
-    the overload of this function based on the `Stream` parameter
-    used to consruct the socket. When `Stream` is a user defined
-    type, and not a `boost::asio::ip::tcp::socket` or any
-    `boost::asio::ssl::stream`, callers are responsible for
-    providing a suitable overload of this function.
-
-    @param socket The socket to tear down.
-
-    @param ec Set to the error if any occurred.
+    If you are creating an instance of beast::websocket::stream with your
+    own user defined type, you must provide an overload of teardown with
+    the corresponding signature (including the teardown_tag).
 */
-void
-teardown(
-    boost::asio::ip::tcp::socket& socket,
-        error_code& ec);
-
-/** Start tearing down a `boost::asio::ip::tcp::socket`.
-
-    This begins tearing down a connection asynchronously.
-    The implementation will call the overload of this function
-    based on the `Stream` parameter used to consruct the socket.
-    When `Stream` is a user defined type, and not a
-    `boost::asio::ip::tcp::socket` or any `boost::asio::ssl::stream`,
-    callers are responsible for providing a suitable overload
-    of this function.
-
-    @param socket The socket to tear down.
-
-    @param handler The handler to be called when the request completes.
-    Copies will be made of the handler as required. The equivalent
-    function signature of the handler must be:
-    @code void handler(
-        error_code const& error // result of operation
-    ); @endcode
-    Regardless of whether the asynchronous operation completes
-    immediately or not, the handler will not be invoked from within
-    this function. Invocation of the handler will be performed in a
-    manner equivalent to using boost::asio::io_service::post().
-
-*/
-template<class TeardownHandler>
-void
-async_teardown(
-    boost::asio::ip::tcp::socket& socket,
-        TeardownHandler&& handler);
+    static_assert(sizeof(Socket)==-1,
+        "Unknown Socket type in async_teardown.");
+}
 
 } // websocket
 
@@ -127,7 +111,7 @@ void
 call_teardown(Socket& socket, error_code& ec)
 {
     using websocket::teardown;
-    teardown(socket, ec);
+    teardown(websocket::teardown_tag{}, socket, ec);
 }
 
 template<class Socket, class TeardownHandler>
@@ -136,12 +120,65 @@ void
 call_async_teardown(Socket& socket, TeardownHandler&& handler)
 {
     using websocket::async_teardown;
-    async_teardown(socket,
+    async_teardown(websocket::teardown_tag{}, socket,
         std::forward<TeardownHandler>(handler));
 }
 
 } // websocket_helpers
 
+//------------------------------------------------------------------------------
+
+namespace websocket {
+
+/** Tear down a `boost::asio::ip::tcp::socket`.
+
+    This tears down a connection. The implementation will call
+    the overload of this function based on the `Stream` parameter
+    used to consruct the socket. When `Stream` is a user defined
+    type, and not a `boost::asio::ip::tcp::socket` or any
+    `boost::asio::ssl::stream`, callers are responsible for
+    providing a suitable overload of this function.
+
+    @param socket The socket to tear down.
+
+    @param ec Set to the error if any occurred.
+*/
+void
+teardown(teardown_tag,
+    boost::asio::ip::tcp::socket& socket, error_code& ec);
+
+/** Start tearing down a `boost::asio::ip::tcp::socket`.
+
+    This begins tearing down a connection asynchronously.
+    The implementation will call the overload of this function
+    based on the `Stream` parameter used to consruct the socket.
+    When `Stream` is a user defined type, and not a
+    `boost::asio::ip::tcp::socket` or any `boost::asio::ssl::stream`,
+    callers are responsible for providing a suitable overload
+    of this function.
+
+    @param socket The socket to tear down.
+
+    @param handler The handler to be called when the request completes.
+    Copies will be made of the handler as required. The equivalent
+    function signature of the handler must be:
+    @code void handler(
+        error_code const& error // result of operation
+    );
+    @endcode
+    Regardless of whether the asynchronous operation completes
+    immediately or not, the handler will not be invoked from within
+    this function. Invocation of the handler will be performed in a
+    manner equivalent to using boost::asio::io_service::post().
+
+*/
+template<class TeardownHandler>
+void
+async_teardown(teardown_tag,
+    boost::asio::ip::tcp::socket& socket, TeardownHandler&& handler);
+
+} // websocket
+
 } // beast
 
 #include <beast/websocket/impl/teardown.ipp>