ceph/src/boost/boost/asio/windows/basic_random_access_handle.hpp

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