ceph/src/boost/boost/asio/write_at.hpp

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