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

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