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

   1 //
   2 // read_at.hpp
   3 // ~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2022 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. It is an
 408  * initiating function for an @ref asynchronous_operation, and always returns
 409  * immediately. The asynchronous operation will continue until one of the
 410  * following conditions is true:
 411  *
 412  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 413  * the sum of the buffer sizes.
 414  *
 415  * @li An error occurred.
 416  *
 417  * This operation is implemented in terms of zero or more calls to the device's
 418  * async_read_some_at function.
 419  *
 420  * @param d The device from which the data is to be read. The type must support
 421  * the AsyncRandomAccessReadDevice concept.
 422  *
 423  * @param offset The offset at which the data will be read.
 424  *
 425  * @param buffers One or more buffers into which the data will be read. The sum
 426  * of the buffer sizes indicates the maximum number of bytes to read from the
 427  * device. Although the buffers object may be copied as necessary, ownership of
 428  * the underlying memory blocks is retained by the caller, which must guarantee
 429  * that they remain valid until the completion handler is called.
 430  *
 431  * @param token The @ref completion_token that will be used to produce a
 432  * completion handler, which will be called when the read completes.
 433  * Potential completion tokens include @ref use_future, @ref use_awaitable,
 434  * @ref yield_context, or a function object with the correct completion
 435  * signature. The function signature of the completion handler must be:
 436  * @code void handler(
 437  *   // Result of operation.
 438  *   const boost::system::error_code& error,
 439  *
 440  *   // Number of bytes copied into the buffers. If an error
 441  *   // occurred, this will be the number of bytes successfully
 442  *   // transferred prior to the error.
 443  *   std::size_t bytes_transferred
 444  * ); @endcode
 445  * Regardless of whether the asynchronous operation completes immediately or
 446  * not, the completion handler will not be invoked from within this function.
 447  * On immediate completion, invocation of the handler will be performed in a
 448  * manner equivalent to using boost::asio::post().
 449  *
 450  * @par Completion Signature
 451  * @code void(boost::system::error_code, std::size_t) @endcode
 452  *
 453  * @par Example
 454  * To read into a single data buffer use the @ref buffer function as follows:
 455  * @code
 456  * boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler);
 457  * @endcode
 458  * See the @ref buffer documentation for information on reading into multiple
 459  * buffers in one go, and how to use it with arrays, boost::array or
 460  * std::vector.
 461  *
 462  * @note This overload is equivalent to calling:
 463  * @code boost::asio::async_read_at(
 464  *     d, 42, buffers,
 465  *     boost::asio::transfer_all(),
 466  *     handler); @endcode
 467  *
 468  * @par Per-Operation Cancellation
 469  * This asynchronous operation supports cancellation for the following
 470  * boost::asio::cancellation_type values:
 471  *
 472  * @li @c cancellation_type::terminal
 473  *
 474  * @li @c cancellation_type::partial
 475  *
 476  * if they are also supported by the @c AsyncRandomAccessReadDevice type's
 477  * async_read_some_at operation.
 478  */
 479 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
 480     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 481       std::size_t)) ReadToken
 482         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 483           typename AsyncRandomAccessReadDevice::executor_type)>
 484 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
 485     void (boost::system::error_code, std::size_t))
 486 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
 487     const MutableBufferSequence& buffers,
 488     BOOST_ASIO_MOVE_ARG(ReadToken) token
 489       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 490         typename AsyncRandomAccessReadDevice::executor_type));
 491
 492 /// Start an asynchronous operation to read a certain amount of data at the
 493 /// specified offset.
 494 /**
 495  * This function is used to asynchronously read a certain number of bytes of
 496  * data from a random access device at the specified offset. It is an
 497  * initiating function for an @ref asynchronous_operation, and always returns
 498  * immediately. The asynchronous operation will continue until one of the
 499  * following conditions is true:
 500  *
 501  * @li The supplied buffers are full. That is, the bytes transferred is equal to
 502  * the sum of the buffer sizes.
 503  *
 504  * @li The completion_condition function object returns 0.
 505  *
 506  * @param d The device from which the data is to be read. The type must support
 507  * the AsyncRandomAccessReadDevice concept.
 508  *
 509  * @param offset The offset at which the data will be read.
 510  *
 511  * @param buffers One or more buffers into which the data will be read. The sum
 512  * of the buffer sizes indicates the maximum number of bytes to read from the
 513  * device. Although the buffers object may be copied as necessary, ownership of
 514  * the underlying memory blocks is retained by the caller, which must guarantee
 515  * that they remain valid until the completion handler is called.
 516  *
 517  * @param completion_condition The function object to be called to determine
 518  * whether the read operation is complete. The signature of the function object
 519  * must be:
 520  * @code std::size_t completion_condition(
 521  *   // Result of latest async_read_some_at operation.
 522  *   const boost::system::error_code& error,
 523  *
 524  *   // Number of bytes transferred so far.
 525  *   std::size_t bytes_transferred
 526  * ); @endcode
 527  * A return value of 0 indicates that the read operation is complete. A non-zero
 528  * return value indicates the maximum number of bytes to be read on the next
 529  * call to the device's async_read_some_at function.
 530  *
 531  * @param token The @ref completion_token that will be used to produce a
 532  * completion handler, which will be called when the read completes.
 533  * Potential completion tokens include @ref use_future, @ref use_awaitable,
 534  * @ref yield_context, or a function object with the correct completion
 535  * signature. The function signature of the completion handler must be:
 536  * @code void handler(
 537  *   // Result of operation.
 538  *   const boost::system::error_code& error,
 539  *
 540  *   // Number of bytes copied into the buffers. If an error
 541  *   // occurred, this will be the number of bytes successfully
 542  *   // transferred prior to the error.
 543  *   std::size_t bytes_transferred
 544  * ); @endcode
 545  * Regardless of whether the asynchronous operation completes immediately or
 546  * not, the completion handler will not be invoked from within this function.
 547  * On immediate completion, invocation of the handler will be performed in a
 548  * manner equivalent to using boost::asio::post().
 549  *
 550  * @par Completion Signature
 551  * @code void(boost::system::error_code, std::size_t) @endcode
 552  *
 553  * @par Example
 554  * To read into a single data buffer use the @ref buffer function as follows:
 555  * @code boost::asio::async_read_at(d, 42,
 556  *     boost::asio::buffer(data, size),
 557  *     boost::asio::transfer_at_least(32),
 558  *     handler); @endcode
 559  * See the @ref buffer documentation for information on reading into multiple
 560  * buffers in one go, and how to use it with arrays, boost::array or
 561  * std::vector.
 562  *
 563  * @par Per-Operation Cancellation
 564  * This asynchronous operation supports cancellation for the following
 565  * boost::asio::cancellation_type values:
 566  *
 567  * @li @c cancellation_type::terminal
 568  *
 569  * @li @c cancellation_type::partial
 570  *
 571  * if they are also supported by the @c AsyncRandomAccessReadDevice type's
 572  * async_read_some_at operation.
 573  */
 574 template <typename AsyncRandomAccessReadDevice,
 575     typename MutableBufferSequence, typename CompletionCondition,
 576     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 577       std::size_t)) ReadToken
 578         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 579           typename AsyncRandomAccessReadDevice::executor_type)>
 580 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
 581     void (boost::system::error_code, std::size_t))
 582 async_read_at(AsyncRandomAccessReadDevice& d,
 583     uint64_t offset, const MutableBufferSequence& buffers,
 584     CompletionCondition completion_condition,
 585     BOOST_ASIO_MOVE_ARG(ReadToken) token
 586       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 587         typename AsyncRandomAccessReadDevice::executor_type));
 588
 589 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 590 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 591
 592 /// Start an asynchronous operation to read a certain amount of data at the
 593 /// specified offset.
 594 /**
 595  * This function is used to asynchronously read a certain number of bytes of
 596  * data from a random access device at the specified offset. It is an
 597  * initiating function for an @ref asynchronous_operation, and always returns
 598  * immediately. The asynchronous operation will continue until one of the
 599  * following conditions is true:
 600  *
 601  * @li An error occurred.
 602  *
 603  * This operation is implemented in terms of zero or more calls to the device's
 604  * async_read_some_at function.
 605  *
 606  * @param d The device from which the data is to be read. The type must support
 607  * the AsyncRandomAccessReadDevice concept.
 608  *
 609  * @param offset The offset at which the data will be read.
 610  *
 611  * @param b A basic_streambuf object into which the data will be read. Ownership
 612  * of the streambuf is retained by the caller, which must guarantee that it
 613  * remains valid until the completion handler is called.
 614  *
 615  * @param token The @ref completion_token that will be used to produce a
 616  * completion handler, which will be called when the read completes.
 617  * Potential completion tokens include @ref use_future, @ref use_awaitable,
 618  * @ref yield_context, or a function object with the correct completion
 619  * signature. The function signature of the completion handler must be:
 620  * @code void handler(
 621  *   // Result of operation.
 622  *   const boost::system::error_code& error,
 623  *
 624  *   // Number of bytes copied into the buffers. If an error
 625  *   // occurred, this will be the number of bytes successfully
 626  *   // transferred prior to the error.
 627  *   std::size_t bytes_transferred
 628  * ); @endcode
 629  * Regardless of whether the asynchronous operation completes immediately or
 630  * not, the completion handler will not be invoked from within this function.
 631  * On immediate completion, invocation of the handler will be performed in a
 632  * manner equivalent to using boost::asio::post().
 633  *
 634  * @par Completion Signature
 635  * @code void(boost::system::error_code, std::size_t) @endcode
 636  *
 637  * @note This overload is equivalent to calling:
 638  * @code boost::asio::async_read_at(
 639  *     d, 42, b,
 640  *     boost::asio::transfer_all(),
 641  *     handler); @endcode
 642  *
 643  * @par Per-Operation Cancellation
 644  * This asynchronous operation supports cancellation for the following
 645  * boost::asio::cancellation_type values:
 646  *
 647  * @li @c cancellation_type::terminal
 648  *
 649  * @li @c cancellation_type::partial
 650  *
 651  * if they are also supported by the @c AsyncRandomAccessReadDevice type's
 652  * async_read_some_at operation.
 653  */
 654 template <typename AsyncRandomAccessReadDevice, typename Allocator,
 655     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 656       std::size_t)) ReadToken
 657         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 658           typename AsyncRandomAccessReadDevice::executor_type)>
 659 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
 660     void (boost::system::error_code, std::size_t))
 661 async_read_at(AsyncRandomAccessReadDevice& d,
 662     uint64_t offset, basic_streambuf<Allocator>& b,
 663     BOOST_ASIO_MOVE_ARG(ReadToken) token
 664       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 665         typename AsyncRandomAccessReadDevice::executor_type));
 666
 667 /// Start an asynchronous operation to read a certain amount of data at the
 668 /// specified offset.
 669 /**
 670  * This function is used to asynchronously read a certain number of bytes of
 671  * data from a random access device at the specified offset. It is an
 672  * initiating function for an @ref asynchronous_operation, and always returns
 673  * immediately. The asynchronous operation will continue until one of the
 674  * following conditions is true:
 675  *
 676  * @li The completion_condition function object returns 0.
 677  *
 678  * This operation is implemented in terms of zero or more calls to the device's
 679  * async_read_some_at function.
 680  *
 681  * @param d The device from which the data is to be read. The type must support
 682  * the AsyncRandomAccessReadDevice concept.
 683  *
 684  * @param offset The offset at which the data will be read.
 685  *
 686  * @param b A basic_streambuf object into which the data will be read. Ownership
 687  * of the streambuf is retained by the caller, which must guarantee that it
 688  * remains valid until the completion handler is called.
 689  *
 690  * @param completion_condition The function object to be called to determine
 691  * whether the read operation is complete. The signature of the function object
 692  * must be:
 693  * @code std::size_t completion_condition(
 694  *   // Result of latest async_read_some_at operation.
 695  *   const boost::system::error_code& error,
 696  *
 697  *   // Number of bytes transferred so far.
 698  *   std::size_t bytes_transferred
 699  * ); @endcode
 700  * A return value of 0 indicates that the read operation is complete. A non-zero
 701  * return value indicates the maximum number of bytes to be read on the next
 702  * call to the device's async_read_some_at function.
 703  *
 704  * @param token The @ref completion_token that will be used to produce a
 705  * completion handler, which will be called when the read completes.
 706  * Potential completion tokens include @ref use_future, @ref use_awaitable,
 707  * @ref yield_context, or a function object with the correct completion
 708  * signature. The function signature of the completion handler must be:
 709  * @code void handler(
 710  *   // Result of operation.
 711  *   const boost::system::error_code& error,
 712  *
 713  *   // Number of bytes copied into the buffers. If an error
 714  *   // occurred, this will be the number of bytes successfully
 715  *   // transferred prior to the error.
 716  *   std::size_t bytes_transferred
 717  * ); @endcode
 718  * Regardless of whether the asynchronous operation completes immediately or
 719  * not, the completion handler will not be invoked from within this function.
 720  * On immediate completion, invocation of the handler will be performed in a
 721  * manner equivalent to using boost::asio::post().
 722  *
 723  * @par Completion Signature
 724  * @code void(boost::system::error_code, std::size_t) @endcode
 725  *
 726  * @par Per-Operation Cancellation
 727  * This asynchronous operation supports cancellation for the following
 728  * boost::asio::cancellation_type values:
 729  *
 730  * @li @c cancellation_type::terminal
 731  *
 732  * @li @c cancellation_type::partial
 733  *
 734  * if they are also supported by the @c AsyncRandomAccessReadDevice type's
 735  * async_read_some_at operation.
 736  */
 737 template <typename AsyncRandomAccessReadDevice,
 738     typename Allocator, typename CompletionCondition,
 739     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 740       std::size_t)) ReadToken
 741         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 742           typename AsyncRandomAccessReadDevice::executor_type)>
 743 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
 744     void (boost::system::error_code, std::size_t))
 745 async_read_at(AsyncRandomAccessReadDevice& d,
 746     uint64_t offset, basic_streambuf<Allocator>& b,
 747     CompletionCondition completion_condition,
 748     BOOST_ASIO_MOVE_ARG(ReadToken) token
 749       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 750         typename AsyncRandomAccessReadDevice::executor_type));
 751
 752 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 753 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 754
 755 /*@}*/
 756
 757 } // namespace asio
 758 } // namespace boost
 759
 760 #include <boost/asio/detail/pop_options.hpp>
 761
 762 #include <boost/asio/impl/read_at.hpp>
 763
 764 #endif // BOOST_ASIO_READ_AT_HPP