boost/beast/core/buffers_generator.hpp
//
// Copyright (c) 2022 Seth Heeren (sgheeren 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_BUFFERS_GENERATOR_HPP
#define BOOST_BEAST_CORE_BUFFERS_GENERATOR_HPP
#include <boost/beast/core/detail/config.hpp>
#include <boost/beast/core/detail/type_traits.hpp>
#include <boost/beast/core/error.hpp>
#include <boost/beast/core/stream_traits.hpp>
#include <boost/asio/async_result.hpp>
#include <type_traits>
namespace boost {
namespace beast {
/** Determine if type satisfies the <em>BuffersGenerator</em> requirements.
This metafunction is used to determine if the specified type meets the
requirements for a buffers generator.
The static member `value` will evaluate to `true` if so, `false` otherwise.
@tparam T a type to check
*/
#ifdef BOOST_BEAST_DOXYGEN
template <class T>
struct is_buffers_generator
: integral_constant<bool, automatically_determined>
{
};
#else
template<class T, class = void>
struct is_buffers_generator
: std::false_type
{
};
template<class T>
struct is_buffers_generator<
T, detail::void_t<decltype(
bool(std::declval<T const&>().is_done()),
typename T::const_buffers_type(
std::declval<T&>().prepare(
std::declval<error_code&>())),
std::declval<T&>().consume(
std::size_t{})
)>> : std::true_type
{
};
#endif
/** Write all output from a BuffersGenerator to a stream.
This function is used to write all of the buffers generated
by a caller-provided BuffersGenerator to a stream. The call
will block until one of the following conditions is true:
@li A call to the generator's `is_done` returns `false`.
@li An error occurs.
This operation is implemented in terms of one or more calls
to the stream's `write_some` function.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> concept.
@param generator The generator to use.
@param ec Set to the error, if any occurred.
@return The number of bytes written to the stream.
@see BuffersGenerator
*/
template<
class SyncWriteStream,
class BuffersGenerator
#if ! BOOST_BEAST_DOXYGEN
, typename std::enable_if<is_buffers_generator<
typename std::decay<BuffersGenerator>::
type>::value>::type* = nullptr
#endif
>
std::size_t
write(
SyncWriteStream& stream,
BuffersGenerator&& generator,
beast::error_code& ec);
/** Write all output from a BuffersGenerator to a stream.
This function is used to write all of the buffers generated
by a caller-provided BuffersGenerator to a stream. The call
will block until one of the following conditions is true:
@li A call to the generator's `is_done` returns `false`.
@li An error occurs.
This operation is implemented in terms of one or more calls
to the stream's `write_some` function.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> concept.
@param generator The generator to use.
@return The number of bytes written to the stream.
@throws system_error Thrown on failure.
@see BuffersGenerator
*/
template<
class SyncWriteStream,
class BuffersGenerator
#if ! BOOST_BEAST_DOXYGEN
, typename std::enable_if<is_buffers_generator<
typename std::decay<BuffersGenerator>::
type>::value>::type* = nullptr
#endif
>
std::size_t
write(
SyncWriteStream& stream,
BuffersGenerator&& generator);
/** Write all output from a BuffersGenerator asynchronously to a
stream.
This function is used to write all of the buffers generated
by a caller-provided `BuffersGenerator` to a stream. The
function call always returns immediately. The asynchronous
operation will continue until one of the following
conditions is true:
@li A call to the generator's `is_done` returns `false`.
@li An error occurs.
This operation is implemented in terms of zero or more calls
to the stream's `async_write_some` function, and is known as
a <em>composed operation</em>. The program must ensure that
the stream performs no other writes until this operation
completes.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> concept.
@param generator The generator to use.
@param token 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 // the number of bytes written to the stream
);
@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 `net::post`.
@see BuffersGenerator
*/
template<
class AsyncWriteStream,
class BuffersGenerator,
BOOST_BEAST_ASYNC_TPARAM2 CompletionToken
= net::default_completion_token_t<executor_type<AsyncWriteStream>>
#if !BOOST_BEAST_DOXYGEN
, typename std::enable_if<is_buffers_generator<
BuffersGenerator>::value>::type* = nullptr
#endif
>
BOOST_BEAST_ASYNC_RESULT2(CompletionToken)
async_write(
AsyncWriteStream& stream,
BuffersGenerator generator,
CompletionToken&& token
= net::default_completion_token_t<executor_type<AsyncWriteStream>>{});
} // beast
} // boost
#include <boost/beast/core/impl/buffers_generator.hpp>
#endif