ceph/src/boost/boost/asio/read_at.hpp

   1 //
   2 // read_at.hpp
   3 // ~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 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_READ_AT_HPP
  12 #define BOOST_ASIO_READ_AT_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 <cstddef>
  20 #include <boost/asio/async_result.hpp>
  21 #include <boost/asio/detail/cstdint.hpp>
  22 #include <boost/asio/error.hpp>
  23
  24 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  25 # include <boost/asio/basic_streambuf_fwd.hpp>
  26 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  27
  28 #include <boost/asio/detail/push_options.hpp>
  29
  30 namespace boost {
  31 namespace asio {
  32
  33 /**
  34  * @defgroup read_at boost::asio::read_at
  35  *
  36  * @brief The @c read_at function is a composed operation that reads a certain
  37  * amount of data at the specified offset before returning.
  38  */
  39 /*@{*/
  40
  41 /// Attempt to read a certain amount of data at the specified offset before
  42 /// returning.
  43 /**
  44  * This function is used to read a certain number of bytes of data from a
  45  * random access device at the specified offset. The call will block until one
  46  * of the following conditions is true:
  47  *
  48  * @li The supplied buffers are full. That is, the bytes transferred is equal to
  49  * the sum of the buffer sizes.
  50  *
  51  * @li An error occurred.
  52  *
  53  * This operation is implemented in terms of zero or more calls to the device's
  54  * read_some_at function.
  55  *
  56  * @param d The device from which the data is to be read. The type must support
  57  * the SyncRandomAccessReadDevice concept.
  58  *
  59  * @param offset The offset at which the data will be read.
  60  *
  61  * @param buffers One or more buffers into which the data will be read. The sum
  62  * of the buffer sizes indicates the maximum number of bytes to read from the
  63  * device.
  64  *
  65  * @returns The number of bytes transferred.
  66  *
  67  * @throws boost::system::system_error Thrown on failure.
  68  *
  69  * @par Example
  70  * To read into a single data buffer use the @ref buffer function as follows:
  71  * @code boost::asio::read_at(d, 42, boost::asio::buffer(data, size)); @endcode
  72  * See the @ref buffer documentation for information on reading into multiple
  73  * buffers in one go, and how to use it with arrays, boost::array or
  74  * std::vector.
  75  *
  76  * @note This overload is equivalent to calling:
  77  * @code boost::asio::read_at(
  78  *     d, 42, buffers,
  79  *     boost::asio::transfer_all()); @endcode
  80  */
  81 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
  82 std::size_t read_at(SyncRandomAccessReadDevice& d,
  83     uint64_t offset, const MutableBufferSequence& buffers);
  84
  85 /// Attempt to read a certain amount of data at the specified offset before
  86 /// returning.
  87 /**
  88  * This function is used to read a certain number of bytes of data from a
  89  * random access device at the specified offset. The call will block until one
  90  * of the following conditions is true:
  91  *
  92  * @li The supplied buffers are full. That is, the bytes transferred is equal to
  93  * the sum of the buffer sizes.
  94  *
  95  * @li An error occurred.
  96  *
  97  * This operation is implemented in terms of zero or more calls to the device's
  98  * read_some_at function.
  99  *
 100  * @param d The device from which the data is to be read. The type must support
 101  * the SyncRandomAccessReadDevice concept.
 102  *
 103  * @param offset The offset at which the data will be read.
 104  *
 105  * @param buffers One or more buffers into which the data will be read. The sum
 106  * of the buffer sizes indicates the maximum number of bytes to read from the
 107  * device.
 108  *
 109  * @param ec Set to indicate what error occurred, if any.
 110  *
 111  * @returns The number of bytes transferred.
 112  *
 113  * @par Example
 114  * To read into a single data buffer use the @ref buffer function as follows:
 115  * @code boost::asio::read_at(d, 42,
 116  *     boost::asio::buffer(data, size), ec); @endcode
 117  * See the @ref buffer documentation for information on reading into multiple
 118  * buffers in one go, and how to use it with arrays, boost::array or
 119  * std::vector.
 120  *
 121  * @note This overload is equivalent to calling:
 122  * @code boost::asio::read_at(
 123  *     d, 42, buffers,
 124  *     boost::asio::transfer_all(), ec); @endcode
 125  */
 126 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
 127 std::size_t read_at(SyncRandomAccessReadDevice& d,
 128     uint64_t offset, const MutableBufferSequence& buffers,
 129     boost::system::error_code& ec);
 130
 131 /// Attempt to read a certain amount of data at the specified offset before
 132 /// returning.
 133 /**
 134  * This function is used to read a certain number of bytes of data from a
 135  * random access device at the specified offset. The call will block until one
 136  * of the following conditions is true:
 137  *
 138  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 139  * the sum of the buffer sizes.
 140  *
 141  * @li The completion_condition function object returns 0.
 142  *
 143  * This operation is implemented in terms of zero or more calls to the device's
 144  * read_some_at function.
 145  *
 146  * @param d The device from which the data is to be read. The type must support
 147  * the SyncRandomAccessReadDevice concept.
 148  *
 149  * @param offset The offset at which the data will be read.
 150  *
 151  * @param buffers One or more buffers into which the data will be read. The sum
 152  * of the buffer sizes indicates the maximum number of bytes to read from the
 153  * device.
 154  *
 155  * @param completion_condition The function object to be called to determine
 156  * whether the read operation is complete. The signature of the function object
 157  * must be:
 158  * @code std::size_t completion_condition(
 159  *   // Result of latest read_some_at operation.
 160  *   const boost::system::error_code& error,
 161  *
 162  *   // Number of bytes transferred so far.
 163  *   std::size_t bytes_transferred
 164  * ); @endcode
 165  * A return value of 0 indicates that the read operation is complete. A non-zero
 166  * return value indicates the maximum number of bytes to be read on the next
 167  * call to the device's read_some_at function.
 168  *
 169  * @returns The number of bytes transferred.
 170  *
 171  * @throws boost::system::system_error Thrown on failure.
 172  *
 173  * @par Example
 174  * To read into a single data buffer use the @ref buffer function as follows:
 175  * @code boost::asio::read_at(d, 42, boost::asio::buffer(data, size),
 176  *     boost::asio::transfer_at_least(32)); @endcode
 177  * See the @ref buffer documentation for information on reading into multiple
 178  * buffers in one go, and how to use it with arrays, boost::array or
 179  * std::vector.
 180  */
 181 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
 182     typename CompletionCondition>
 183 std::size_t read_at(SyncRandomAccessReadDevice& d,
 184     uint64_t offset, const MutableBufferSequence& buffers,
 185     CompletionCondition completion_condition);
 186
 187 /// Attempt to read a certain amount of data at the specified offset before
 188 /// returning.
 189 /**
 190  * This function is used to read a certain number of bytes of data from a
 191  * random access device at the specified offset. The call will block until one
 192  * of the following conditions is true:
 193  *
 194  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 195  * the sum of the buffer sizes.
 196  *
 197  * @li The completion_condition function object returns 0.
 198  *
 199  * This operation is implemented in terms of zero or more calls to the device's
 200  * read_some_at function.
 201  *
 202  * @param d The device from which the data is to be read. The type must support
 203  * the SyncRandomAccessReadDevice concept.
 204  *
 205  * @param offset The offset at which the data will be read.
 206  *
 207  * @param buffers One or more buffers into which the data will be read. The sum
 208  * of the buffer sizes indicates the maximum number of bytes to read from the
 209  * device.
 210  *
 211  * @param completion_condition The function object to be called to determine
 212  * whether the read operation is complete. The signature of the function object
 213  * must be:
 214  * @code std::size_t completion_condition(
 215  *   // Result of latest read_some_at operation.
 216  *   const boost::system::error_code& error,
 217  *
 218  *   // Number of bytes transferred so far.
 219  *   std::size_t bytes_transferred
 220  * ); @endcode
 221  * A return value of 0 indicates that the read operation is complete. A non-zero
 222  * return value indicates the maximum number of bytes to be read on the next
 223  * call to the device's read_some_at function.
 224  *
 225  * @param ec Set to indicate what error occurred, if any.
 226  *
 227  * @returns The number of bytes read. If an error occurs, returns the total
 228  * number of bytes successfully transferred prior to the error.
 229  */
 230 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
 231     typename CompletionCondition>
 232 std::size_t read_at(SyncRandomAccessReadDevice& d,
 233     uint64_t offset, const MutableBufferSequence& buffers,
 234     CompletionCondition completion_condition, boost::system::error_code& ec);
 235
 236 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 237 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 238
 239 /// Attempt to read a certain amount of data at the specified offset before
 240 /// returning.
 241 /**
 242  * This function is used to read a certain number of bytes of data from a
 243  * random access device at the specified offset. The call will block until one
 244  * of the following conditions is true:
 245  *
 246  * @li An error occurred.
 247  *
 248  * This operation is implemented in terms of zero or more calls to the device's
 249  * read_some_at function.
 250  *
 251  * @param d The device from which the data is to be read. The type must support
 252  * the SyncRandomAccessReadDevice concept.
 253  *
 254  * @param offset The offset at which the data will be read.
 255  *
 256  * @param b The basic_streambuf object into which the data will be read.
 257  *
 258  * @returns The number of bytes transferred.
 259  *
 260  * @throws boost::system::system_error Thrown on failure.
 261  *
 262  * @note This overload is equivalent to calling:
 263  * @code boost::asio::read_at(
 264  *     d, 42, b,
 265  *     boost::asio::transfer_all()); @endcode
 266  */
 267 template <typename SyncRandomAccessReadDevice, typename Allocator>
 268 std::size_t read_at(SyncRandomAccessReadDevice& d,
 269     uint64_t offset, basic_streambuf<Allocator>& b);
 270
 271 /// Attempt to read a certain amount of data at the specified offset before
 272 /// returning.
 273 /**
 274  * This function is used to read a certain number of bytes of data from a
 275  * random access device at the specified offset. The call will block until one
 276  * of the following conditions is true:
 277  *
 278  * @li An error occurred.
 279  *
 280  * This operation is implemented in terms of zero or more calls to the device's
 281  * read_some_at function.
 282  *
 283  * @param d The device from which the data is to be read. The type must support
 284  * the SyncRandomAccessReadDevice concept.
 285  *
 286  * @param offset The offset at which the data will be read.
 287  *
 288  * @param b The basic_streambuf object into which the data will be read.
 289  *
 290  * @param ec Set to indicate what error occurred, if any.
 291  *
 292  * @returns The number of bytes transferred.
 293  *
 294  * @note This overload is equivalent to calling:
 295  * @code boost::asio::read_at(
 296  *     d, 42, b,
 297  *     boost::asio::transfer_all(), ec); @endcode
 298  */
 299 template <typename SyncRandomAccessReadDevice, typename Allocator>
 300 std::size_t read_at(SyncRandomAccessReadDevice& d,
 301     uint64_t offset, basic_streambuf<Allocator>& b,
 302     boost::system::error_code& ec);
 303
 304 /// Attempt to read a certain amount of data at the specified offset before
 305 /// returning.
 306 /**
 307  * This function is used to read a certain number of bytes of data from a
 308  * random access device at the specified offset. The call will block until one
 309  * of the following conditions is true:
 310  *
 311  * @li The completion_condition function object returns 0.
 312  *
 313  * This operation is implemented in terms of zero or more calls to the device's
 314  * read_some_at function.
 315  *
 316  * @param d The device from which the data is to be read. The type must support
 317  * the SyncRandomAccessReadDevice concept.
 318  *
 319  * @param offset The offset at which the data will be read.
 320  *
 321  * @param b The basic_streambuf object into which the data will be read.
 322  *
 323  * @param completion_condition The function object to be called to determine
 324  * whether the read operation is complete. The signature of the function object
 325  * must be:
 326  * @code std::size_t completion_condition(
 327  *   // Result of latest read_some_at operation.
 328  *   const boost::system::error_code& error,
 329  *
 330  *   // Number of bytes transferred so far.
 331  *   std::size_t bytes_transferred
 332  * ); @endcode
 333  * A return value of 0 indicates that the read operation is complete. A non-zero
 334  * return value indicates the maximum number of bytes to be read on the next
 335  * call to the device's read_some_at function.
 336  *
 337  * @returns The number of bytes transferred.
 338  *
 339  * @throws boost::system::system_error Thrown on failure.
 340  */
 341 template <typename SyncRandomAccessReadDevice, typename Allocator,
 342     typename CompletionCondition>
 343 std::size_t read_at(SyncRandomAccessReadDevice& d,
 344     uint64_t offset, basic_streambuf<Allocator>& b,
 345     CompletionCondition completion_condition);
 346
 347 /// Attempt to read a certain amount of data at the specified offset before
 348 /// returning.
 349 /**
 350  * This function is used to read a certain number of bytes of data from a
 351  * random access device at the specified offset. The call will block until one
 352  * of the following conditions is true:
 353  *
 354  * @li The completion_condition function object returns 0.
 355  *
 356  * This operation is implemented in terms of zero or more calls to the device's
 357  * read_some_at function.
 358  *
 359  * @param d The device from which the data is to be read. The type must support
 360  * the SyncRandomAccessReadDevice concept.
 361  *
 362  * @param offset The offset at which the data will be read.
 363  *
 364  * @param b The basic_streambuf object into which the data will be read.
 365  *
 366  * @param completion_condition The function object to be called to determine
 367  * whether the read operation is complete. The signature of the function object
 368  * must be:
 369  * @code std::size_t completion_condition(
 370  *   // Result of latest read_some_at operation.
 371  *   const boost::system::error_code& error,
 372  *
 373  *   // Number of bytes transferred so far.
 374  *   std::size_t bytes_transferred
 375  * ); @endcode
 376  * A return value of 0 indicates that the read operation is complete. A non-zero
 377  * return value indicates the maximum number of bytes to be read on the next
 378  * call to the device's read_some_at function.
 379  *
 380  * @param ec Set to indicate what error occurred, if any.
 381  *
 382  * @returns The number of bytes read. If an error occurs, returns the total
 383  * number of bytes successfully transferred prior to the error.
 384  */
 385 template <typename SyncRandomAccessReadDevice, typename Allocator,
 386     typename CompletionCondition>
 387 std::size_t read_at(SyncRandomAccessReadDevice& d,
 388     uint64_t offset, basic_streambuf<Allocator>& b,
 389     CompletionCondition completion_condition, boost::system::error_code& ec);
 390
 391 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 392 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 393
 394 /*@}*/
 395 /**
 396  * @defgroup async_read_at boost::asio::async_read_at
 397  *
 398  * @brief The @c async_read_at function is a composed asynchronous operation
 399  * that reads a certain amount of data at the specified offset.
 400  */
 401 /*@{*/
 402
 403 /// Start an asynchronous operation to read a certain amount of data at the
 404 /// specified offset.
 405 /**
 406  * This function is used to asynchronously read a certain number of bytes of
 407  * data from a random access device at the specified offset. The function call
 408  * always returns immediately. The asynchronous operation will continue until
 409  * one of the following conditions is true:
 410  *
 411  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 412  * the sum of the buffer sizes.
 413  *
 414  * @li An error occurred.
 415  *
 416  * This operation is implemented in terms of zero or more calls to the device's
 417  * async_read_some_at function.
 418  *
 419  * @param d The device from which the data is to be read. The type must support
 420  * the AsyncRandomAccessReadDevice concept.
 421  *
 422  * @param offset The offset at which the data will be read.
 423  *
 424  * @param buffers One or more buffers into which the data will be read. The sum
 425  * of the buffer sizes indicates the maximum number of bytes to read from the
 426  * device. Although the buffers object may be copied as necessary, ownership of
 427  * the underlying memory blocks is retained by the caller, which must guarantee
 428  * that they remain valid until the handler is called.
 429  *
 430  * @param handler The handler to be called when the read operation completes.
 431  * Copies will be made of the handler as required. The function signature of the
 432  * handler must be:
 433  * @code void handler(
 434  *   // Result of operation.
 435  *   const boost::system::error_code& error,
 436  *
 437  *   // Number of bytes copied into the buffers. If an error
 438  *   // occurred, this will be the number of bytes successfully
 439  *   // transferred prior to the error.
 440  *   std::size_t bytes_transferred
 441  * ); @endcode
 442  * Regardless of whether the asynchronous operation completes immediately or
 443  * not, the handler will not be invoked from within this function. On
 444  * immediate completion, invocation of the handler will be performed in a
 445  * manner equivalent to using boost::asio::post().
 446  *
 447  * @par Example
 448  * To read into a single data buffer use the @ref buffer function as follows:
 449  * @code
 450  * boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler);
 451  * @endcode
 452  * See the @ref buffer documentation for information on reading into multiple
 453  * buffers in one go, and how to use it with arrays, boost::array or
 454  * std::vector.
 455  *
 456  * @note This overload is equivalent to calling:
 457  * @code boost::asio::async_read_at(
 458  *     d, 42, buffers,
 459  *     boost::asio::transfer_all(),
 460  *     handler); @endcode
 461  */
 462 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
 463     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 464       std::size_t)) ReadHandler
 465         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 466           typename AsyncRandomAccessReadDevice::executor_type)>
 467 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
 468     void (boost::system::error_code, std::size_t))
 469 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
 470     const MutableBufferSequence& buffers,
 471     BOOST_ASIO_MOVE_ARG(ReadHandler) handler
 472       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 473         typename AsyncRandomAccessReadDevice::executor_type));
 474
 475 /// Start an asynchronous operation to read a certain amount of data at the
 476 /// specified offset.
 477 /**
 478  * This function is used to asynchronously read a certain number of bytes of
 479  * data from a random access device at the specified offset. The function call
 480  * always returns immediately. The asynchronous operation will continue until
 481  * one of the following conditions is true:
 482  *
 483  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 484  * the sum of the buffer sizes.
 485  *
 486  * @li The completion_condition function object returns 0.
 487  *
 488  * @param d The device from which the data is to be read. The type must support
 489  * the AsyncRandomAccessReadDevice concept.
 490  *
 491  * @param offset The offset at which the data will be read.
 492  *
 493  * @param buffers One or more buffers into which the data will be read. The sum
 494  * of the buffer sizes indicates the maximum number of bytes to read from the
 495  * device. Although the buffers object may be copied as necessary, ownership of
 496  * the underlying memory blocks is retained by the caller, which must guarantee
 497  * that they remain valid until the handler is called.
 498  *
 499  * @param completion_condition The function object to be called to determine
 500  * whether the read operation is complete. The signature of the function object
 501  * must be:
 502  * @code std::size_t completion_condition(
 503  *   // Result of latest async_read_some_at operation.
 504  *   const boost::system::error_code& error,
 505  *
 506  *   // Number of bytes transferred so far.
 507  *   std::size_t bytes_transferred
 508  * ); @endcode
 509  * A return value of 0 indicates that the read operation is complete. A non-zero
 510  * return value indicates the maximum number of bytes to be read on the next
 511  * call to the device's async_read_some_at function.
 512  *
 513  * @param handler The handler to be called when the read operation completes.
 514  * Copies will be made of the handler as required. The function signature of the
 515  * handler must be:
 516  * @code void handler(
 517  *   // Result of operation.
 518  *   const boost::system::error_code& error,
 519  *
 520  *   // Number of bytes copied into the buffers. If an error
 521  *   // occurred, this will be the number of bytes successfully
 522  *   // transferred prior to the error.
 523  *   std::size_t bytes_transferred
 524  * ); @endcode
 525  * Regardless of whether the asynchronous operation completes immediately or
 526  * not, the handler will not be invoked from within this function. On
 527  * immediate completion, invocation of the handler will be performed in a
 528  * manner equivalent to using boost::asio::post().
 529  *
 530  * @par Example
 531  * To read into a single data buffer use the @ref buffer function as follows:
 532  * @code boost::asio::async_read_at(d, 42,
 533  *     boost::asio::buffer(data, size),
 534  *     boost::asio::transfer_at_least(32),
 535  *     handler); @endcode
 536  * See the @ref buffer documentation for information on reading into multiple
 537  * buffers in one go, and how to use it with arrays, boost::array or
 538  * std::vector.
 539  */
 540 template <typename AsyncRandomAccessReadDevice,
 541     typename MutableBufferSequence, typename CompletionCondition,
 542     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 543       std::size_t)) ReadHandler
 544         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 545           typename AsyncRandomAccessReadDevice::executor_type)>
 546 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
 547     void (boost::system::error_code, std::size_t))
 548 async_read_at(AsyncRandomAccessReadDevice& d,
 549     uint64_t offset, const MutableBufferSequence& buffers,
 550     CompletionCondition completion_condition,
 551     BOOST_ASIO_MOVE_ARG(ReadHandler) handler
 552       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 553         typename AsyncRandomAccessReadDevice::executor_type));
 554
 555 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 556 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 557
 558 /// Start an asynchronous operation to read a certain amount of data at the
 559 /// specified offset.
 560 /**
 561  * This function is used to asynchronously read a certain number of bytes of
 562  * data from a random access device at the specified offset. The function call
 563  * always returns immediately. The asynchronous operation will continue until
 564  * one of the following conditions is true:
 565  *
 566  * @li An error occurred.
 567  *
 568  * This operation is implemented in terms of zero or more calls to the device's
 569  * async_read_some_at function.
 570  *
 571  * @param d The device from which the data is to be read. The type must support
 572  * the AsyncRandomAccessReadDevice concept.
 573  *
 574  * @param offset The offset at which the data will be read.
 575  *
 576  * @param b A basic_streambuf object into which the data will be read. Ownership
 577  * of the streambuf is retained by the caller, which must guarantee that it
 578  * remains valid until the handler is called.
 579  *
 580  * @param handler The handler to be called when the read operation completes.
 581  * Copies will be made of the handler as required. The function signature of the
 582  * handler must be:
 583  * @code void handler(
 584  *   // Result of operation.
 585  *   const boost::system::error_code& error,
 586  *
 587  *   // Number of bytes copied into the buffers. If an error
 588  *   // occurred, this will be the number of bytes successfully
 589  *   // transferred prior to the error.
 590  *   std::size_t bytes_transferred
 591  * ); @endcode
 592  * Regardless of whether the asynchronous operation completes immediately or
 593  * not, the handler will not be invoked from within this function. On
 594  * immediate completion, invocation of the handler will be performed in a
 595  * manner equivalent to using boost::asio::post().
 596  *
 597  * @note This overload is equivalent to calling:
 598  * @code boost::asio::async_read_at(
 599  *     d, 42, b,
 600  *     boost::asio::transfer_all(),
 601  *     handler); @endcode
 602  */
 603 template <typename AsyncRandomAccessReadDevice, typename Allocator,
 604     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 605       std::size_t)) ReadHandler
 606         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 607           typename AsyncRandomAccessReadDevice::executor_type)>
 608 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
 609     void (boost::system::error_code, std::size_t))
 610 async_read_at(AsyncRandomAccessReadDevice& d,
 611     uint64_t offset, basic_streambuf<Allocator>& b,
 612     BOOST_ASIO_MOVE_ARG(ReadHandler) handler
 613       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 614         typename AsyncRandomAccessReadDevice::executor_type));
 615
 616 /// Start an asynchronous operation to read a certain amount of data at the
 617 /// specified offset.
 618 /**
 619  * This function is used to asynchronously read a certain number of bytes of
 620  * data from a random access device at the specified offset. The function call
 621  * always returns immediately. The asynchronous operation will continue until
 622  * one of the following conditions is true:
 623  *
 624  * @li The completion_condition function object returns 0.
 625  *
 626  * This operation is implemented in terms of zero or more calls to the device's
 627  * async_read_some_at function.
 628  *
 629  * @param d The device from which the data is to be read. The type must support
 630  * the AsyncRandomAccessReadDevice concept.
 631  *
 632  * @param offset The offset at which the data will be read.
 633  *
 634  * @param b A basic_streambuf object into which the data will be read. Ownership
 635  * of the streambuf is retained by the caller, which must guarantee that it
 636  * remains valid until the handler is called.
 637  *
 638  * @param completion_condition The function object to be called to determine
 639  * whether the read operation is complete. The signature of the function object
 640  * must be:
 641  * @code std::size_t completion_condition(
 642  *   // Result of latest async_read_some_at operation.
 643  *   const boost::system::error_code& error,
 644  *
 645  *   // Number of bytes transferred so far.
 646  *   std::size_t bytes_transferred
 647  * ); @endcode
 648  * A return value of 0 indicates that the read operation is complete. A non-zero
 649  * return value indicates the maximum number of bytes to be read on the next
 650  * call to the device's async_read_some_at function.
 651  *
 652  * @param handler The handler to be called when the read operation completes.
 653  * Copies will be made of the handler as required. The function signature of the
 654  * handler must be:
 655  * @code void handler(
 656  *   // Result of operation.
 657  *   const boost::system::error_code& error,
 658  *
 659  *   // Number of bytes copied into the buffers. If an error
 660  *   // occurred, this will be the number of bytes successfully
 661  *   // transferred prior to the error.
 662  *   std::size_t bytes_transferred
 663  * ); @endcode
 664  * Regardless of whether the asynchronous operation completes immediately or
 665  * not, the handler will not be invoked from within this function. On
 666  * immediate completion, invocation of the handler will be performed in a
 667  * manner equivalent to using boost::asio::post().
 668  */
 669 template <typename AsyncRandomAccessReadDevice,
 670     typename Allocator, typename CompletionCondition,
 671     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 672       std::size_t)) ReadHandler
 673         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 674           typename AsyncRandomAccessReadDevice::executor_type)>
 675 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
 676     void (boost::system::error_code, std::size_t))
 677 async_read_at(AsyncRandomAccessReadDevice& d,
 678     uint64_t offset, basic_streambuf<Allocator>& b,
 679     CompletionCondition completion_condition,
 680     BOOST_ASIO_MOVE_ARG(ReadHandler) handler
 681       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 682         typename AsyncRandomAccessReadDevice::executor_type));
 683
 684 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 685 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 686
 687 /*@}*/
 688
 689 } // namespace asio
 690 } // namespace boost
 691
 692 #include <boost/asio/detail/pop_options.hpp>
 693
 694 #include <boost/asio/impl/read_at.hpp>
 695
 696 #endif // BOOST_ASIO_READ_AT_HPP