boost/asio/buffered_write_stream.hpp

0001 //
0002 // buffered_write_stream.hpp
0003 // ~~~~~~~~~~~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2023 Christopher M. Kohlhoff (chris at kohlhoff dot com)
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009 //
0010
0011 #ifndef BOOST_ASIO_BUFFERED_WRITE_STREAM_HPP
0012 #define BOOST_ASIO_BUFFERED_WRITE_STREAM_HPP
0013
0014 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
0015 # pragma once
0016 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
0017
0018 #include <boost/asio/detail/config.hpp>
0019 #include <cstddef>
0020 #include <boost/asio/buffered_write_stream_fwd.hpp>
0021 #include <boost/asio/buffer.hpp>
0022 #include <boost/asio/completion_condition.hpp>
0023 #include <boost/asio/detail/bind_handler.hpp>
0024 #include <boost/asio/detail/buffered_stream_storage.hpp>
0025 #include <boost/asio/detail/noncopyable.hpp>
0026 #include <boost/asio/detail/type_traits.hpp>
0027 #include <boost/asio/error.hpp>
0028 #include <boost/asio/write.hpp>
0029
0030 #include <boost/asio/detail/push_options.hpp>
0031
0032 namespace boost {
0033 namespace asio {
0034 namespace detail {
0035
0036 template <typename> class initiate_async_buffered_flush;
0037 template <typename> class initiate_async_buffered_write_some;
0038
0039 } // namespace detail
0040
0041 /// Adds buffering to the write-related operations of a stream.
0042 /**
0043  * The buffered_write_stream class template can be used to add buffering to the
0044  * synchronous and asynchronous write operations of a stream.
0045  *
0046  * @par Thread Safety
0047  * @e Distinct @e objects: Safe.@n
0048  * @e Shared @e objects: Unsafe.
0049  *
0050  * @par Concepts:
0051  * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream.
0052  */
0053 template <typename Stream>
0054 class buffered_write_stream
0055   : private noncopyable
0056 {
0057 public:
0058   /// The type of the next layer.
0059   typedef remove_reference_t<Stream> next_layer_type;
0060
0061   /// The type of the lowest layer.
0062   typedef typename next_layer_type::lowest_layer_type lowest_layer_type;
0063
0064   /// The type of the executor associated with the object.
0065   typedef typename lowest_layer_type::executor_type executor_type;
0066
0067 #if defined(GENERATING_DOCUMENTATION)
0068   /// The default buffer size.
0069   static const std::size_t default_buffer_size = implementation_defined;
0070 #else
0071   BOOST_ASIO_STATIC_CONSTANT(std::size_t, default_buffer_size = 1024);
0072 #endif
0073
0074   /// Construct, passing the specified argument to initialise the next layer.
0075   template <typename Arg>
0076   explicit buffered_write_stream(Arg&& a)
0077     : next_layer_(static_cast<Arg&&>(a)),
0078       storage_(default_buffer_size)
0079   {
0080   }
0081
0082   /// Construct, passing the specified argument to initialise the next layer.
0083   template <typename Arg>
0084   buffered_write_stream(Arg&& a,
0085       std::size_t buffer_size)
0086     : next_layer_(static_cast<Arg&&>(a)),
0087       storage_(buffer_size)
0088   {
0089   }
0090
0091   /// Get a reference to the next layer.
0092   next_layer_type& next_layer()
0093   {
0094     return next_layer_;
0095   }
0096
0097   /// Get a reference to the lowest layer.
0098   lowest_layer_type& lowest_layer()
0099   {
0100     return next_layer_.lowest_layer();
0101   }
0102
0103   /// Get a const reference to the lowest layer.
0104   const lowest_layer_type& lowest_layer() const
0105   {
0106     return next_layer_.lowest_layer();
0107   }
0108
0109   /// Get the executor associated with the object.
0110   executor_type get_executor() noexcept
0111   {
0112     return next_layer_.lowest_layer().get_executor();
0113   }
0114
0115   /// Close the stream.
0116   void close()
0117   {
0118     next_layer_.close();
0119   }
0120
0121   /// Close the stream.
0122   BOOST_ASIO_SYNC_OP_VOID close(boost::system::error_code& ec)
0123   {
0124     next_layer_.close(ec);
0125     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
0126   }
0127
0128   /// Flush all data from the buffer to the next layer. Returns the number of
0129   /// bytes written to the next layer on the last write operation. Throws an
0130   /// exception on failure.
0131   std::size_t flush();
0132
0133   /// Flush all data from the buffer to the next layer. Returns the number of
0134   /// bytes written to the next layer on the last write operation, or 0 if an
0135   /// error occurred.
0136   std::size_t flush(boost::system::error_code& ec);
0137
0138   /// Start an asynchronous flush.
0139   /**
0140    * @par Completion Signature
0141    * @code void(boost::system::error_code, std::size_t) @endcode
0142    */
0143   template <
0144       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
0145         std::size_t)) WriteHandler = default_completion_token_t<executor_type>>
0146   auto async_flush(
0147       WriteHandler&& handler = default_completion_token_t<executor_type>())
0148     -> decltype(
0149       async_initiate<WriteHandler,
0150         void (boost::system::error_code, std::size_t)>(
0151           declval<detail::initiate_async_buffered_flush<Stream>>(),
0152           handler, declval<detail::buffered_stream_storage*>()));
0153
0154   /// Write the given data to the stream. Returns the number of bytes written.
0155   /// Throws an exception on failure.
0156   template <typename ConstBufferSequence>
0157   std::size_t write_some(const ConstBufferSequence& buffers);
0158
0159   /// Write the given data to the stream. Returns the number of bytes written,
0160   /// or 0 if an error occurred and the error handler did not throw.
0161   template <typename ConstBufferSequence>
0162   std::size_t write_some(const ConstBufferSequence& buffers,
0163       boost::system::error_code& ec);
0164
0165   /// Start an asynchronous write. The data being written must be valid for the
0166   /// lifetime of the asynchronous operation.
0167   /**
0168    * @par Completion Signature
0169    * @code void(boost::system::error_code, std::size_t) @endcode
0170    */
0171   template <typename ConstBufferSequence,
0172       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
0173         std::size_t)) WriteHandler = default_completion_token_t<executor_type>>
0174   auto async_write_some(const ConstBufferSequence& buffers,
0175       WriteHandler&& handler = default_completion_token_t<executor_type>())
0176     -> decltype(
0177       async_initiate<WriteHandler,
0178         void (boost::system::error_code, std::size_t)>(
0179           declval<detail::initiate_async_buffered_write_some<Stream>>(),
0180           handler, declval<detail::buffered_stream_storage*>(), buffers));
0181
0182   /// Read some data from the stream. Returns the number of bytes read. Throws
0183   /// an exception on failure.
0184   template <typename MutableBufferSequence>
0185   std::size_t read_some(const MutableBufferSequence& buffers)
0186   {
0187     return next_layer_.read_some(buffers);
0188   }
0189
0190   /// Read some data from the stream. Returns the number of bytes read or 0 if
0191   /// an error occurred.
0192   template <typename MutableBufferSequence>
0193   std::size_t read_some(const MutableBufferSequence& buffers,
0194       boost::system::error_code& ec)
0195   {
0196     return next_layer_.read_some(buffers, ec);
0197   }
0198
0199   /// Start an asynchronous read. The buffer into which the data will be read
0200   /// must be valid for the lifetime of the asynchronous operation.
0201   /**
0202    * @par Completion Signature
0203    * @code void(boost::system::error_code, std::size_t) @endcode
0204    */
0205   template <typename MutableBufferSequence,
0206       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
0207         std::size_t)) ReadHandler = default_completion_token_t<executor_type>>
0208   auto async_read_some(const MutableBufferSequence& buffers,
0209       ReadHandler&& handler = default_completion_token_t<executor_type>())
0210     -> decltype(
0211       declval<conditional_t<true, Stream&, ReadHandler>>().async_read_some(
0212         buffers, static_cast<ReadHandler&&>(handler)))
0213   {
0214     return next_layer_.async_read_some(buffers,
0215         static_cast<ReadHandler&&>(handler));
0216   }
0217
0218   /// Peek at the incoming data on the stream. Returns the number of bytes read.
0219   /// Throws an exception on failure.
0220   template <typename MutableBufferSequence>
0221   std::size_t peek(const MutableBufferSequence& buffers)
0222   {
0223     return next_layer_.peek(buffers);
0224   }
0225
0226   /// Peek at the incoming data on the stream. Returns the number of bytes read,
0227   /// or 0 if an error occurred.
0228   template <typename MutableBufferSequence>
0229   std::size_t peek(const MutableBufferSequence& buffers,
0230       boost::system::error_code& ec)
0231   {
0232     return next_layer_.peek(buffers, ec);
0233   }
0234
0235   /// Determine the amount of data that may be read without blocking.
0236   std::size_t in_avail()
0237   {
0238     return next_layer_.in_avail();
0239   }
0240
0241   /// Determine the amount of data that may be read without blocking.
0242   std::size_t in_avail(boost::system::error_code& ec)
0243   {
0244     return next_layer_.in_avail(ec);
0245   }
0246
0247 private:
0248   /// Copy data into the internal buffer from the specified source buffer.
0249   /// Returns the number of bytes copied.
0250   template <typename ConstBufferSequence>
0251   std::size_t copy(const ConstBufferSequence& buffers);
0252
0253   /// The next layer.
0254   Stream next_layer_;
0255
0256   // The data in the buffer.
0257   detail::buffered_stream_storage storage_;
0258 };
0259
0260 } // namespace asio
0261 } // namespace boost
0262
0263 #include <boost/asio/detail/pop_options.hpp>
0264
0265 #include <boost/asio/impl/buffered_write_stream.hpp>
0266
0267 #endif // BOOST_ASIO_BUFFERED_WRITE_STREAM_HPP