Remove lowest_layer, add get_lowest_layer (API Change):

fix #1417

* New get_lowest_layer free function works for any object
* New lowest_layer_type trait works for any object
* New examples and documentation on layered streams

API Changes:

* The member function lowest_layer is removed from all
  types provided by the library:

Actions Required:

* Call the free function get_lowest_layer instead of
  member lowest_layer.
This commit is contained in:
Vinnie Falco committed 2019-02-01 04:31:13 -08:00
1 parent ff32f44682
commit 6a658b5c3a
66 files changed
+1130 -125

No files matched your search

+2
View File
@@ -22,6 +22,7 @@
#include <boost/beast/core/buffers_range.hpp>
#include <boost/beast/core/buffers_suffix.hpp>
#include <boost/beast/core/buffers_to_string.hpp>
#include <boost/beast/core/close_socket.hpp>
#include <boost/beast/core/error.hpp>
#include <boost/beast/core/file.hpp>
#include <boost/beast/core/file_base.hpp>
@@ -30,6 +31,7 @@
#include <boost/beast/core/file_win32.hpp>
#include <boost/beast/core/flat_buffer.hpp>
#include <boost/beast/core/flat_static_buffer.hpp>
#include <boost/beast/core/get_lowest_layer.hpp>
#include <boost/beast/core/handler_ptr.hpp>
#include <boost/beast/core/make_printable.hpp>
#include <boost/beast/core/multi_buffer.hpp>
+47
View File
@@ -0,0 +1,47 @@
//
// Copyright (c) 2018 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
//
#ifndef BOOST_BEAST_CLOSE_SOCKET_HPP
#define BOOST_BEAST_CLOSE_SOCKET_HPP
#include <boost/beast/core/detail/config.hpp>
#include <boost/asio/basic_socket.hpp>
namespace boost {
namespace beast {
namespace detail {
template<class Protocol>
void
beast_close_socket(
net::basic_socket<Protocol>& sock)
{
boost::system::error_code ec;
sock.close(ec);
}
} // detail
/** Close a socket.
@param sock The socket to close.
*/
template<class Socket>
void
close_socket(Socket& sock)
{
using detail::beast_close_socket;
beast_close_socket(sock);
}
} // beast
} // boost
#endif
@@ -0,0 +1,73 @@
//
// Copyright (c) 2018 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
//
#ifndef BOOST_BEAST_DETAIL_GET_LOWEST_LAYER_HPP
#define BOOST_BEAST_DETAIL_GET_LOWEST_LAYER_HPP
#include <boost/type_traits/make_void.hpp>
#include <type_traits>
namespace boost {
namespace beast {
namespace detail {
template<class T, class = void>
struct has_next_layer : std::false_type
{
};
template<class T>
struct has_next_layer<T, boost::void_t<
decltype(std::declval<T>().next_layer())>>
: std::true_type
{
};
template<class T, class = void>
struct lowest_layer_type_impl
{
using type = typename std::remove_reference<T>::type;
};
template<class T>
struct lowest_layer_type_impl<T, boost::void_t<
decltype(std::declval<T>().next_layer())>>
{
using type = typename lowest_layer_type_impl<
decltype(std::declval<T>().next_layer())>::type;
};
template<class T>
using lowest_layer_type = typename
lowest_layer_type_impl<T>::type;
template<class T>
lowest_layer_type<T>&
get_lowest_layer_impl(
T& t, std::true_type) noexcept
{
using type = typename std::decay<
decltype(t.next_layer())>::type;
return get_lowest_layer_impl(t.next_layer(),
has_next_layer<type>{});
}
template<class T>
T&
get_lowest_layer_impl(
T& t, std::false_type) noexcept
{
return t;
}
} // detail
} // beast
} // boost
#endif
@@ -0,0 +1,88 @@
//
// Copyright (c) 2018 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
//
#ifndef BOOST_BEAST_GET_LOWEST_LAYER_HPP
#define BOOST_BEAST_GET_LOWEST_LAYER_HPP
#include <boost/beast/core/detail/config.hpp>
#include <boost/beast/core/detail/get_lowest_layer.hpp>
namespace boost {
namespace beast {
/** Return the type of the lowest layer of a type representing a stack of stream layers.
This type alias will return the type of lowest layer object for a type
which defines a stack of stream layers.
@param T The type determine the lowest layer type of.
@return The type of the lowest layer.
*/
template<class T>
#if BOOST_BEAST_DOXYGEN
using lowest_layer_type = __see_below__;
#else
using lowest_layer_type = detail::lowest_layer_type<T>;
#endif
/** Return the lowest layer in a stack of stream layers.
If `t.next_layer()` is well-defined, returns
`lowest_layer(t.next_layer())`. Otherwise, it returns `t`.
A stream layer is an object of class type which wraps another object through
composition, and meets some or all of the named requirements of the wrapped
type while optionally changing behavior. Examples of stream layers include
`net::ssl::stream` or @ref beast::websocket::stream. The owner of a stream
layer can interact directly with the wrapper, by passing it to stream
algorithms. Or, the owner can obtain a reference to the wrapped object by
calling `next_layer()` and accessing its members. This is necessary when it is
desired to access functionality in the next layer which is not available
in the wrapper. For example, @ref websocket::stream permits reading and
writing, but in order to establish the underlying connection, members
of the wrapped stream (such as `connect`) must be invoked directly.
Usually the last object in the chain of composition is the concrete socket
object (for example, a `net::basic_socket` or a class derived from it).
The function @ref get_lowest_layer exists to easily obtain the concrete
socket when it is desired to perform an action that is not prescribed by
a named requirement, such as changing a socket option, cancelling all
pending asynchronous I/O, or closing the socket (perhaps by using
@ref close_socket).
@par Example
@code
// Set non-blocking mode on a stack of stream
// layers with a regular socket at the lowest layer.
template <class Stream>
void set_non_blocking (Stream& stream)
{
error_code ec;
// A compile error here means your lowest layer is not the right type!
get_lowest_layer(stream).non_blocking(true, ec);
if(ec)
throw system_error{ec};
}
@endcode
@param t The layer in a stack of layered objects for which the lowest layer is returned.
*/
template<class T>
lowest_layer_type<T>&
get_lowest_layer(T& t) noexcept
{
return detail::get_lowest_layer_impl(
t, detail::has_next_layer<T>{});
}
} // beast
} // boost
#endif