358 lines
13 KiB
C++
358 lines
13 KiB
C++
//
|
|
// 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
|
|
//
|
|
|
|
#ifndef BOOST_BEAST_CORE_FLAT_STREAM_HPP
|
|
#define BOOST_BEAST_CORE_FLAT_STREAM_HPP
|
|
|
|
#include <boost/beast/core/detail/config.hpp>
|
|
#include <boost/beast/core/error.hpp>
|
|
#include <boost/beast/core/flat_buffer.hpp>
|
|
#include <boost/beast/core/stream_traits.hpp>
|
|
#include <boost/beast/core/detail/flat_stream.hpp>
|
|
#include <boost/asio/async_result.hpp>
|
|
#include <cstdlib>
|
|
#include <utility>
|
|
|
|
namespace boost {
|
|
namespace beast {
|
|
|
|
/** (Deprecated: This wrapper is no longer needed; Asio linearizes
|
|
scatter/gather I/O in ssl::stream.) Stream wrapper to improve write
|
|
performance.
|
|
|
|
This wrapper flattens writes for buffer sequences having length
|
|
greater than 1 and total size below a predefined amount, using
|
|
a dynamic memory allocation. It is primarily designed to overcome
|
|
a performance limitation of the current version of `net::ssl::stream`,
|
|
which does not use OpenSSL's scatter/gather interface for its
|
|
low-level read some and write some operations.
|
|
|
|
It is normally not necessary to use this class directly if you
|
|
are already using @ref ssl_stream. The following examples shows
|
|
how to use this class with the ssl stream that comes with
|
|
networking:
|
|
|
|
@par Example
|
|
|
|
To use the @ref flat_stream template with SSL streams, declare
|
|
a variable of the correct type. Parameters passed to the constructor
|
|
will be forwarded to the next layer's constructor:
|
|
|
|
@code
|
|
flat_stream<net::ssl::stream<ip::tcp::socket>> fs{ioc, ctx};
|
|
@endcode
|
|
Alternatively you can write
|
|
@code
|
|
ssl::stream<ip::tcp::socket> ss{ioc, ctx};
|
|
flat_stream<net::ssl::stream<ip::tcp::socket>&> fs{ss};
|
|
@endcode
|
|
|
|
The resulting stream may be passed to any stream algorithms which
|
|
operate on synchronous or asynchronous read or write streams,
|
|
examples include:
|
|
|
|
@li `net::read`, `net::async_read`
|
|
|
|
@li `net::write`, `net::async_write`
|
|
|
|
@li `net::read_until`, `net::async_read_until`
|
|
|
|
The stream may also be used as a template parameter in other
|
|
stream wrappers, such as for websocket:
|
|
@code
|
|
websocket::stream<flat_stream<net::ssl::stream<ip::tcp::socket>>> ws{ioc, ctx};
|
|
@endcode
|
|
|
|
@tparam NextLayer The type representing the next layer, to which
|
|
data will be read and written during operations. For synchronous
|
|
operations, the type must support the @b SyncStream concept. For
|
|
asynchronous operations, the type must support the @b AsyncStream
|
|
concept. This type will usually be some variation of
|
|
`net::ssl::stream`.
|
|
|
|
@par Concepts
|
|
@li SyncStream
|
|
@li AsyncStream
|
|
|
|
@see
|
|
@li https://github.com/boostorg/asio/issues/100
|
|
@li https://github.com/boostorg/beast/issues/1108
|
|
@li https://stackoverflow.com/questions/38198638/openssl-ssl-write-from-multiple-buffers-ssl-writev
|
|
@li https://stackoverflow.com/questions/50026167/performance-drop-on-port-from-beast-1-0-0-b66-to-boost-1-67-0-beast
|
|
*/
|
|
template<class NextLayer>
|
|
class flat_stream
|
|
#if ! BOOST_BEAST_DOXYGEN
|
|
: private detail::flat_stream_base
|
|
#endif
|
|
{
|
|
NextLayer stream_;
|
|
flat_buffer buffer_;
|
|
|
|
BOOST_STATIC_ASSERT(has_get_executor<NextLayer>::value);
|
|
|
|
struct ops;
|
|
|
|
template<class ConstBufferSequence>
|
|
std::size_t
|
|
stack_write_some(
|
|
std::size_t size,
|
|
ConstBufferSequence const& buffers,
|
|
error_code& ec);
|
|
|
|
public:
|
|
/// The type of the next layer.
|
|
using next_layer_type =
|
|
typename std::remove_reference<NextLayer>::type;
|
|
|
|
/// The type of the executor associated with the object.
|
|
using executor_type = beast::executor_type<next_layer_type>;
|
|
|
|
flat_stream(flat_stream&&) = default;
|
|
flat_stream(flat_stream const&) = default;
|
|
flat_stream& operator=(flat_stream&&) = default;
|
|
flat_stream& operator=(flat_stream const&) = default;
|
|
|
|
/** Destructor
|
|
|
|
The treatment of pending operations will be the same as that
|
|
of the next layer.
|
|
*/
|
|
~flat_stream() = default;
|
|
|
|
/** Constructor
|
|
|
|
Arguments, if any, are forwarded to the next layer's constructor.
|
|
*/
|
|
template<class... Args>
|
|
explicit
|
|
flat_stream(Args&&... args);
|
|
|
|
//--------------------------------------------------------------------------
|
|
|
|
/** Get the executor associated with the object.
|
|
|
|
This function may be used to obtain the executor object that the
|
|
stream uses to dispatch handlers for asynchronous operations.
|
|
|
|
@return A copy of the executor that stream will use to dispatch handlers.
|
|
*/
|
|
executor_type
|
|
get_executor() noexcept
|
|
{
|
|
return stream_.get_executor();
|
|
}
|
|
|
|
/** Get a reference to the next layer
|
|
|
|
This function returns a reference to the next layer
|
|
in a stack of stream layers.
|
|
|
|
@return A reference to the next layer in the stack of
|
|
stream layers.
|
|
*/
|
|
next_layer_type&
|
|
next_layer() noexcept
|
|
{
|
|
return stream_;
|
|
}
|
|
|
|
/** Get a reference to the next layer
|
|
|
|
This function returns a reference to the next layer in a
|
|
stack of stream layers.
|
|
|
|
@return A reference to the next layer in the stack of
|
|
stream layers.
|
|
*/
|
|
next_layer_type const&
|
|
next_layer() const noexcept
|
|
{
|
|
return stream_;
|
|
}
|
|
|
|
//--------------------------------------------------------------------------
|
|
|
|
/** Read some data from the stream.
|
|
|
|
This function is used to read data from the stream. The function call will
|
|
block until one or more bytes of data has been read successfully, or until
|
|
an error occurs.
|
|
|
|
@param buffers The buffers into which the data will be read.
|
|
|
|
@returns The number of bytes read.
|
|
|
|
@throws boost::system::system_error Thrown on failure.
|
|
|
|
@note The `read_some` operation may not read all of the requested number of
|
|
bytes. Consider using the function `net::read` if you need to ensure
|
|
that the requested amount of data is read before the blocking operation
|
|
completes.
|
|
*/
|
|
template<class MutableBufferSequence>
|
|
std::size_t
|
|
read_some(MutableBufferSequence const& buffers);
|
|
|
|
/** Read some data from the stream.
|
|
|
|
This function is used to read data from the stream. The function call will
|
|
block until one or more bytes of data has been read successfully, or until
|
|
an error occurs.
|
|
|
|
@param buffers The buffers into which the data will be read.
|
|
|
|
@param ec Set to indicate what error occurred, if any.
|
|
|
|
@returns The number of bytes read.
|
|
|
|
@note The `read_some` operation may not read all of the requested number of
|
|
bytes. Consider using the function `net::read` if you need to ensure
|
|
that the requested amount of data is read before the blocking operation
|
|
completes.
|
|
*/
|
|
template<class MutableBufferSequence>
|
|
std::size_t
|
|
read_some(
|
|
MutableBufferSequence const& buffers,
|
|
error_code& ec);
|
|
|
|
/** Start an asynchronous read.
|
|
|
|
This function is used to asynchronously read one or more bytes of data from
|
|
the stream. The function call always returns immediately.
|
|
|
|
@param buffers The buffers into which the data will be read. Although the
|
|
buffers object may be copied as necessary, ownership of the underlying
|
|
buffers is retained by the caller, which must guarantee that they remain
|
|
valid until the handler is called.
|
|
|
|
@param handler The completion handler to invoke when the operation
|
|
completes. The implementation takes ownership of the handler by
|
|
performing a decay-copy. The equivalent function signature of
|
|
the handler must be:
|
|
@code
|
|
void handler(
|
|
error_code const& error, // Result of operation.
|
|
std::size_t bytes_transferred // Number of bytes read.
|
|
);
|
|
@endcode
|
|
If the handler has an associated immediate executor,
|
|
an immediate completion will be dispatched to it.
|
|
Otherwise, the handler will not be invoked from within
|
|
this function. Invocation of the handler will be performed
|
|
by dispatching to the immediate executor. If no
|
|
immediate executor is specified, this is equivalent
|
|
to using `net::post`.
|
|
@note The `read_some` operation may not read all of the requested number of
|
|
bytes. Consider using the function `net::async_read` if you need
|
|
to ensure that the requested amount of data is read before the asynchronous
|
|
operation completes.
|
|
*/
|
|
template<
|
|
class MutableBufferSequence,
|
|
BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
|
|
net::default_completion_token_t<executor_type>>
|
|
BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
|
|
async_read_some(
|
|
MutableBufferSequence const& buffers,
|
|
ReadHandler&& handler =
|
|
net::default_completion_token_t<executor_type>{});
|
|
|
|
/** Write some data to the stream.
|
|
|
|
This function is used to write data on the stream. The function call will
|
|
block until one or more bytes of data has been written successfully, or
|
|
until an error occurs.
|
|
|
|
@param buffers The data to be written.
|
|
|
|
@returns The number of bytes written.
|
|
|
|
@throws boost::system::system_error Thrown on failure.
|
|
|
|
@note The `write_some` operation may not transmit all of the data to the
|
|
peer. Consider using the function `net::write` if you need to
|
|
ensure that all data is written before the blocking operation completes.
|
|
*/
|
|
template<class ConstBufferSequence>
|
|
std::size_t
|
|
write_some(ConstBufferSequence const& buffers);
|
|
|
|
/** Write some data to the stream.
|
|
|
|
This function is used to write data on the stream. The function call will
|
|
block until one or more bytes of data has been written successfully, or
|
|
until an error occurs.
|
|
|
|
@param buffers The data to be written.
|
|
|
|
@param ec Set to indicate what error occurred, if any.
|
|
|
|
@returns The number of bytes written.
|
|
|
|
@note The `write_some` operation may not transmit all of the data to the
|
|
peer. Consider using the function `net::write` if you need to
|
|
ensure that all data is written before the blocking operation completes.
|
|
*/
|
|
template<class ConstBufferSequence>
|
|
std::size_t
|
|
write_some(
|
|
ConstBufferSequence const& buffers,
|
|
error_code& ec);
|
|
|
|
/** Start an asynchronous write.
|
|
|
|
This function is used to asynchronously write one or more bytes of data to
|
|
the stream. The function call always returns immediately.
|
|
|
|
@param buffers The data to be written to the stream. Although the buffers
|
|
object may be copied as necessary, ownership of the underlying buffers is
|
|
retained by the caller, which must guarantee that they remain valid until
|
|
the handler is called.
|
|
|
|
@param handler The completion handler to invoke when the operation
|
|
completes. The implementation takes ownership of the handler by
|
|
performing a decay-copy. The equivalent function signature of
|
|
the handler must be:
|
|
@code
|
|
void handler(
|
|
error_code const& ec, // Result of operation.
|
|
std::size_t bytes_transferred // Number of bytes written.
|
|
);
|
|
@endcode
|
|
If the handler has an associated immediate executor,
|
|
an immediate completion will be dispatched to it.
|
|
Otherwise, the handler will not be invoked from within
|
|
this function. Invocation of the handler will be performed
|
|
by dispatching to the immediate executor. If no
|
|
immediate executor is specified, this is equivalent
|
|
to using `net::post`.
|
|
@note The `async_write_some` operation may not transmit all of the data to
|
|
the peer. Consider using the function `net::async_write` if you need
|
|
to ensure that all data is written before the asynchronous operation completes.
|
|
*/
|
|
template<
|
|
class ConstBufferSequence,
|
|
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
|
|
net::default_completion_token_t<executor_type>>
|
|
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
|
|
async_write_some(
|
|
ConstBufferSequence const& buffers,
|
|
WriteHandler&& handler =
|
|
net::default_completion_token_t<executor_type>{});
|
|
};
|
|
|
|
} // beast
|
|
} // boost
|
|
|
|
#include <boost/beast/core/impl/flat_stream.hpp>
|
|
|
|
#endif
|