ceph/src/boost/boost/asio/posix/stream_descriptor.hpp

   1 //
   2 // posix/stream_descriptor.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 //
   7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10
  11 #ifndef BOOST_ASIO_POSIX_STREAM_DESCRIPTOR_HPP
  12 #define BOOST_ASIO_POSIX_STREAM_DESCRIPTOR_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/config.hpp>
  19 #include <boost/asio/posix/descriptor.hpp>
  20
  21 #if defined(BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR) \
  22   || defined(GENERATING_DOCUMENTATION)
  23
  24 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  25 # include <boost/asio/posix/basic_stream_descriptor.hpp>
  26 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  27
  28 namespace boost {
  29 namespace asio {
  30 namespace posix {
  31
  32 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  33 // Typedef for the typical usage of a stream-oriented descriptor.
  34 typedef basic_stream_descriptor<> stream_descriptor;
  35 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  36 /// Provides stream-oriented descriptor functionality.
  37 /**
  38  * The posix::stream_descriptor class template provides asynchronous and
  39  * blocking stream-oriented descriptor functionality.
  40  *
  41  * @par Thread Safety
  42  * @e Distinct @e objects: Safe.@n
  43  * @e Shared @e objects: Unsafe.
  44  *
  45  * @par Concepts:
  46  * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream.
  47  */
  48 class stream_descriptor
  49   : public descriptor
  50 {
  51 public:
  52   /// Construct a stream_descriptor without opening it.
  53   /**
  54    * This constructor creates a stream descriptor without opening it. The
  55    * descriptor needs to be opened and then connected or accepted before data
  56    * can be sent or received on it.
  57    *
  58    * @param io_context The io_context object that the stream descriptor will
  59    * use to dispatch handlers for any asynchronous operations performed on the
  60    * descriptor.
  61    */
  62   explicit stream_descriptor(boost::asio::io_context& io_context)
  63     : descriptor(io_context)
  64   {
  65   }
  66
  67   /// Construct a stream_descriptor on an existing native descriptor.
  68   /**
  69    * This constructor creates a stream descriptor object to hold an existing
  70    * native descriptor.
  71    *
  72    * @param io_context The io_context object that the stream descriptor will
  73    * use to dispatch handlers for any asynchronous operations performed on the
  74    * descriptor.
  75    *
  76    * @param native_descriptor The new underlying descriptor implementation.
  77    *
  78    * @throws boost::system::system_error Thrown on failure.
  79    */
  80   stream_descriptor(boost::asio::io_context& io_context,
  81       const native_handle_type& native_descriptor)
  82     : descriptor(io_context, native_descriptor)
  83   {
  84   }
  85
  86 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  87   /// Move-construct a stream_descriptor from another.
  88   /**
  89    * This constructor moves a stream descriptor from one object to another.
  90    *
  91    * @param other The other stream_descriptor object from which the move
  92    * will occur.
  93    *
  94    * @note Following the move, the moved-from object is in the same state as if
  95    * constructed using the @c stream_descriptor(io_context&) constructor.
  96    */
  97   stream_descriptor(stream_descriptor&& other)
  98     : descriptor(std::move(other))
  99   {
 100   }
 101
 102   /// Move-assign a stream_descriptor from another.
 103   /**
 104    * This assignment operator moves a stream descriptor from one object to
 105    * another.
 106    *
 107    * @param other The other stream_descriptor object from which the move
 108    * will occur.
 109    *
 110    * @note Following the move, the moved-from object is in the same state as if
 111    * constructed using the @c stream_descriptor(io_context&) constructor.
 112    */
 113   stream_descriptor& operator=(stream_descriptor&& other)
 114   {
 115     descriptor::operator=(std::move(other));
 116     return *this;
 117   }
 118 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 119
 120   /// Write some data to the descriptor.
 121   /**
 122    * This function is used to write data to the stream descriptor. The function
 123    * call will block until one or more bytes of the data has been written
 124    * successfully, or until an error occurs.
 125    *
 126    * @param buffers One or more data buffers to be written to the descriptor.
 127    *
 128    * @returns The number of bytes written.
 129    *
 130    * @throws boost::system::system_error Thrown on failure. An error code of
 131    * boost::asio::error::eof indicates that the connection was closed by the
 132    * peer.
 133    *
 134    * @note The write_some operation may not transmit all of the data to the
 135    * peer. Consider using the @ref write function if you need to ensure that
 136    * all data is written before the blocking operation completes.
 137    *
 138    * @par Example
 139    * To write a single data buffer use the @ref buffer function as follows:
 140    * @code
 141    * descriptor.write_some(boost::asio::buffer(data, size));
 142    * @endcode
 143    * See the @ref buffer documentation for information on writing multiple
 144    * buffers in one go, and how to use it with arrays, boost::array or
 145    * std::vector.
 146    */
 147   template <typename ConstBufferSequence>
 148   std::size_t write_some(const ConstBufferSequence& buffers)
 149   {
 150     boost::system::error_code ec;
 151     std::size_t s = this->get_service().write_some(
 152         this->get_implementation(), buffers, ec);
 153     boost::asio::detail::throw_error(ec, "write_some");
 154     return s;
 155   }
 156
 157   /// Write some data to the descriptor.
 158   /**
 159    * This function is used to write data to the stream descriptor. The function
 160    * call will block until one or more bytes of the data has been written
 161    * successfully, or until an error occurs.
 162    *
 163    * @param buffers One or more data buffers to be written to the descriptor.
 164    *
 165    * @param ec Set to indicate what error occurred, if any.
 166    *
 167    * @returns The number of bytes written. Returns 0 if an error occurred.
 168    *
 169    * @note The write_some operation may not transmit all of the data to the
 170    * peer. Consider using the @ref write function if you need to ensure that
 171    * all data is written before the blocking operation completes.
 172    */
 173   template <typename ConstBufferSequence>
 174   std::size_t write_some(const ConstBufferSequence& buffers,
 175       boost::system::error_code& ec)
 176   {
 177     return this->get_service().write_some(
 178         this->get_implementation(), buffers, ec);
 179   }
 180
 181   /// Start an asynchronous write.
 182   /**
 183    * This function is used to asynchronously write data to the stream
 184    * descriptor. The function call always returns immediately.
 185    *
 186    * @param buffers One or more data buffers to be written to the descriptor.
 187    * Although the buffers object may be copied as necessary, ownership of the
 188    * underlying memory blocks is retained by the caller, which must guarantee
 189    * that they remain valid until the handler is called.
 190    *
 191    * @param handler The handler to be called when the write operation completes.
 192    * Copies will be made of the handler as required. The function signature of
 193    * the handler must be:
 194    * @code void handler(
 195    *   const boost::system::error_code& error, // Result of operation.
 196    *   std::size_t bytes_transferred           // Number of bytes written.
 197    * ); @endcode
 198    * Regardless of whether the asynchronous operation completes immediately or
 199    * not, the handler will not be invoked from within this function. Invocation
 200    * of the handler will be performed in a manner equivalent to using
 201    * boost::asio::io_context::post().
 202    *
 203    * @note The write operation may not transmit all of the data to the peer.
 204    * Consider using the @ref async_write function if you need to ensure that all
 205    * data is written before the asynchronous operation completes.
 206    *
 207    * @par Example
 208    * To write a single data buffer use the @ref buffer function as follows:
 209    * @code
 210    * descriptor.async_write_some(boost::asio::buffer(data, size), handler);
 211    * @endcode
 212    * See the @ref buffer documentation for information on writing multiple
 213    * buffers in one go, and how to use it with arrays, boost::array or
 214    * std::vector.
 215    */
 216   template <typename ConstBufferSequence, typename WriteHandler>
 217   BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 218       void (boost::system::error_code, std::size_t))
 219   async_write_some(const ConstBufferSequence& buffers,
 220       BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
 221   {
 222     // If you get an error on the following line it means that your handler does
 223     // not meet the documented type requirements for a WriteHandler.
 224     BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
 225
 226     boost::asio::async_completion<WriteHandler,
 227       void (boost::system::error_code, std::size_t)> init(handler);
 228
 229     this->get_service().async_write_some(
 230         this->get_implementation(), buffers, init.completion_handler);
 231
 232     return init.result.get();
 233   }
 234
 235   /// Read some data from the descriptor.
 236   /**
 237    * This function is used to read data from the stream descriptor. The function
 238    * call will block until one or more bytes of data has been read successfully,
 239    * or until an error occurs.
 240    *
 241    * @param buffers One or more buffers into which the data will be read.
 242    *
 243    * @returns The number of bytes read.
 244    *
 245    * @throws boost::system::system_error Thrown on failure. An error code of
 246    * boost::asio::error::eof indicates that the connection was closed by the
 247    * peer.
 248    *
 249    * @note The read_some operation may not read all of the requested number of
 250    * bytes. Consider using the @ref read function if you need to ensure that
 251    * the requested amount of data is read before the blocking operation
 252    * completes.
 253    *
 254    * @par Example
 255    * To read into a single data buffer use the @ref buffer function as follows:
 256    * @code
 257    * descriptor.read_some(boost::asio::buffer(data, size));
 258    * @endcode
 259    * See the @ref buffer documentation for information on reading into multiple
 260    * buffers in one go, and how to use it with arrays, boost::array or
 261    * std::vector.
 262    */
 263   template <typename MutableBufferSequence>
 264   std::size_t read_some(const MutableBufferSequence& buffers)
 265   {
 266     boost::system::error_code ec;
 267     std::size_t s = this->get_service().read_some(
 268         this->get_implementation(), buffers, ec);
 269     boost::asio::detail::throw_error(ec, "read_some");
 270     return s;
 271   }
 272
 273   /// Read some data from the descriptor.
 274   /**
 275    * This function is used to read data from the stream descriptor. The function
 276    * call will block until one or more bytes of data has been read successfully,
 277    * or until an error occurs.
 278    *
 279    * @param buffers One or more buffers into which the data will be read.
 280    *
 281    * @param ec Set to indicate what error occurred, if any.
 282    *
 283    * @returns The number of bytes read. Returns 0 if an error occurred.
 284    *
 285    * @note The read_some operation may not read all of the requested number of
 286    * bytes. Consider using the @ref read function if you need to ensure that
 287    * the requested amount of data is read before the blocking operation
 288    * completes.
 289    */
 290   template <typename MutableBufferSequence>
 291   std::size_t read_some(const MutableBufferSequence& buffers,
 292       boost::system::error_code& ec)
 293   {
 294     return this->get_service().read_some(
 295         this->get_implementation(), buffers, ec);
 296   }
 297
 298   /// Start an asynchronous read.
 299   /**
 300    * This function is used to asynchronously read data from the stream
 301    * descriptor. The function call always returns immediately.
 302    *
 303    * @param buffers One or more buffers into which the data will be read.
 304    * Although the buffers object may be copied as necessary, ownership of the
 305    * underlying memory blocks is retained by the caller, which must guarantee
 306    * that they remain valid until the handler is called.
 307    *
 308    * @param handler The handler to be called when the read operation completes.
 309    * Copies will be made of the handler as required. The function signature of
 310    * the handler must be:
 311    * @code void handler(
 312    *   const boost::system::error_code& error, // Result of operation.
 313    *   std::size_t bytes_transferred           // Number of bytes read.
 314    * ); @endcode
 315    * Regardless of whether the asynchronous operation completes immediately or
 316    * not, the handler will not be invoked from within this function. Invocation
 317    * of the handler will be performed in a manner equivalent to using
 318    * boost::asio::io_context::post().
 319    *
 320    * @note The read operation may not read all of the requested number of bytes.
 321    * Consider using the @ref async_read function if you need to ensure that the
 322    * requested amount of data is read before the asynchronous operation
 323    * completes.
 324    *
 325    * @par Example
 326    * To read into a single data buffer use the @ref buffer function as follows:
 327    * @code
 328    * descriptor.async_read_some(boost::asio::buffer(data, size), handler);
 329    * @endcode
 330    * See the @ref buffer documentation for information on reading into multiple
 331    * buffers in one go, and how to use it with arrays, boost::array or
 332    * std::vector.
 333    */
 334   template <typename MutableBufferSequence, typename ReadHandler>
 335   BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 336       void (boost::system::error_code, std::size_t))
 337   async_read_some(const MutableBufferSequence& buffers,
 338       BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
 339   {
 340     // If you get an error on the following line it means that your handler does
 341     // not meet the documented type requirements for a ReadHandler.
 342     BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
 343
 344     boost::asio::async_completion<ReadHandler,
 345       void (boost::system::error_code, std::size_t)> init(handler);
 346
 347     this->get_service().async_read_some(
 348         this->get_implementation(), buffers, init.completion_handler);
 349
 350     return init.result.get();
 351   }
 352 };
 353 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 354
 355 } // namespace posix
 356 } // namespace asio
 357 } // namespace boost
 358
 359 #endif // defined(BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR)
 360        //   || defined(GENERATING_DOCUMENTATION)
 361
 362 #endif // BOOST_ASIO_POSIX_STREAM_DESCRIPTOR_HPP