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

   1 //
   2 // read_at.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_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 Attempt to read a certain amount of data at the specified offset
  37  * 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 Start an asynchronous operation to read a certain amount of data at
 399  * 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. Invocation of
 444  * the handler will be performed in a manner equivalent to using
 445  * boost::asio::io_context::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     typename ReadHandler>
 464 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 465     void (boost::system::error_code, std::size_t))
 466 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
 467     const MutableBufferSequence& buffers,
 468     BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 469
 470 /// Start an asynchronous operation to read a certain amount of data at the
 471 /// specified offset.
 472 /**
 473  * This function is used to asynchronously read a certain number of bytes of
 474  * data from a random access device at the specified offset. The function call
 475  * always returns immediately. The asynchronous operation will continue until
 476  * one of the following conditions is true:
 477  *
 478  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 479  * the sum of the buffer sizes.
 480  *
 481  * @li The completion_condition function object returns 0.
 482  *
 483  * @param d The device from which the data is to be read. The type must support
 484  * the AsyncRandomAccessReadDevice concept.
 485  *
 486  * @param offset The offset at which the data will be read.
 487  *
 488  * @param buffers One or more buffers into which the data will be read. The sum
 489  * of the buffer sizes indicates the maximum number of bytes to read from the
 490  * device. Although the buffers object may be copied as necessary, ownership of
 491  * the underlying memory blocks is retained by the caller, which must guarantee
 492  * that they remain valid until the handler is called.
 493  *
 494  * @param completion_condition The function object to be called to determine
 495  * whether the read operation is complete. The signature of the function object
 496  * must be:
 497  * @code std::size_t completion_condition(
 498  *   // Result of latest async_read_some_at operation.
 499  *   const boost::system::error_code& error,
 500  *
 501  *   // Number of bytes transferred so far.
 502  *   std::size_t bytes_transferred
 503  * ); @endcode
 504  * A return value of 0 indicates that the read operation is complete. A non-zero
 505  * return value indicates the maximum number of bytes to be read on the next
 506  * call to the device's async_read_some_at function.
 507  *
 508  * @param handler The handler to be called when the read operation completes.
 509  * Copies will be made of the handler as required. The function signature of the
 510  * handler must be:
 511  * @code void handler(
 512  *   // Result of operation.
 513  *   const boost::system::error_code& error,
 514  *
 515  *   // Number of bytes copied into the buffers. If an error
 516  *   // occurred, this will be the number of bytes successfully
 517  *   // transferred prior to the error.
 518  *   std::size_t bytes_transferred
 519  * ); @endcode
 520  * Regardless of whether the asynchronous operation completes immediately or
 521  * not, the handler will not be invoked from within this function. Invocation of
 522  * the handler will be performed in a manner equivalent to using
 523  * boost::asio::io_context::post().
 524  *
 525  * @par Example
 526  * To read into a single data buffer use the @ref buffer function as follows:
 527  * @code boost::asio::async_read_at(d, 42,
 528  *     boost::asio::buffer(data, size),
 529  *     boost::asio::transfer_at_least(32),
 530  *     handler); @endcode
 531  * See the @ref buffer documentation for information on reading into multiple
 532  * buffers in one go, and how to use it with arrays, boost::array or
 533  * std::vector.
 534  */
 535 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
 536     typename CompletionCondition, typename ReadHandler>
 537 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 538     void (boost::system::error_code, std::size_t))
 539 async_read_at(AsyncRandomAccessReadDevice& d,
 540     uint64_t offset, const MutableBufferSequence& buffers,
 541     CompletionCondition completion_condition,
 542     BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 543
 544 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 545 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 546
 547 /// Start an asynchronous operation to read a certain amount of data at the
 548 /// specified offset.
 549 /**
 550  * This function is used to asynchronously read a certain number of bytes of
 551  * data from a random access device at the specified offset. The function call
 552  * always returns immediately. The asynchronous operation will continue until
 553  * one of the following conditions is true:
 554  *
 555  * @li An error occurred.
 556  *
 557  * This operation is implemented in terms of zero or more calls to the device's
 558  * async_read_some_at function.
 559  *
 560  * @param d The device from which the data is to be read. The type must support
 561  * the AsyncRandomAccessReadDevice concept.
 562  *
 563  * @param offset The offset at which the data will be read.
 564  *
 565  * @param b A basic_streambuf object into which the data will be read. Ownership
 566  * of the streambuf is retained by the caller, which must guarantee that it
 567  * remains valid until the handler is called.
 568  *
 569  * @param handler The handler to be called when the read operation completes.
 570  * Copies will be made of the handler as required. The function signature of the
 571  * handler must be:
 572  * @code void handler(
 573  *   // Result of operation.
 574  *   const boost::system::error_code& error,
 575  *
 576  *   // Number of bytes copied into the buffers. If an error
 577  *   // occurred, this will be the number of bytes successfully
 578  *   // transferred prior to the error.
 579  *   std::size_t bytes_transferred
 580  * ); @endcode
 581  * Regardless of whether the asynchronous operation completes immediately or
 582  * not, the handler will not be invoked from within this function. Invocation of
 583  * the handler will be performed in a manner equivalent to using
 584  * boost::asio::io_context::post().
 585  *
 586  * @note This overload is equivalent to calling:
 587  * @code boost::asio::async_read_at(
 588  *     d, 42, b,
 589  *     boost::asio::transfer_all(),
 590  *     handler); @endcode
 591  */
 592 template <typename AsyncRandomAccessReadDevice, typename Allocator,
 593     typename ReadHandler>
 594 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 595     void (boost::system::error_code, std::size_t))
 596 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
 597     basic_streambuf<Allocator>& b, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 598
 599 /// Start an asynchronous operation to read a certain amount of data at the
 600 /// specified offset.
 601 /**
 602  * This function is used to asynchronously read a certain number of bytes of
 603  * data from a random access device at the specified offset. The function call
 604  * always returns immediately. The asynchronous operation will continue until
 605  * one of the following conditions is true:
 606  *
 607  * @li The completion_condition function object returns 0.
 608  *
 609  * This operation is implemented in terms of zero or more calls to the device's
 610  * async_read_some_at function.
 611  *
 612  * @param d The device from which the data is to be read. The type must support
 613  * the AsyncRandomAccessReadDevice concept.
 614  *
 615  * @param offset The offset at which the data will be read.
 616  *
 617  * @param b A basic_streambuf object into which the data will be read. Ownership
 618  * of the streambuf is retained by the caller, which must guarantee that it
 619  * remains valid until the handler is called.
 620  *
 621  * @param completion_condition The function object to be called to determine
 622  * whether the read operation is complete. The signature of the function object
 623  * must be:
 624  * @code std::size_t completion_condition(
 625  *   // Result of latest async_read_some_at operation.
 626  *   const boost::system::error_code& error,
 627  *
 628  *   // Number of bytes transferred so far.
 629  *   std::size_t bytes_transferred
 630  * ); @endcode
 631  * A return value of 0 indicates that the read operation is complete. A non-zero
 632  * return value indicates the maximum number of bytes to be read on the next
 633  * call to the device's async_read_some_at function.
 634  *
 635  * @param handler The handler to be called when the read operation completes.
 636  * Copies will be made of the handler as required. The function signature of the
 637  * handler must be:
 638  * @code void handler(
 639  *   // Result of operation.
 640  *   const boost::system::error_code& error,
 641  *
 642  *   // Number of bytes copied into the buffers. If an error
 643  *   // occurred, this will be the number of bytes successfully
 644  *   // transferred prior to the error.
 645  *   std::size_t bytes_transferred
 646  * ); @endcode
 647  * Regardless of whether the asynchronous operation completes immediately or
 648  * not, the handler will not be invoked from within this function. Invocation of
 649  * the handler will be performed in a manner equivalent to using
 650  * boost::asio::io_context::post().
 651  */
 652 template <typename AsyncRandomAccessReadDevice, typename Allocator,
 653     typename CompletionCondition, typename ReadHandler>
 654 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 655     void (boost::system::error_code, std::size_t))
 656 async_read_at(AsyncRandomAccessReadDevice& d,
 657     uint64_t offset, basic_streambuf<Allocator>& b,
 658     CompletionCondition completion_condition,
 659     BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
 660
 661 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 662 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 663
 664 /*@}*/
 665
 666 } // namespace asio
 667 } // namespace boost
 668
 669 #include <boost/asio/detail/pop_options.hpp>
 670
 671 #include <boost/asio/impl/read_at.hpp>
 672
 673 #endif // BOOST_ASIO_READ_AT_HPP