ceph/src/boost/boost/asio/write.hpp

   1 //
   2 // write.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_HPP
  12 #define BOOST_ASIO_WRITE_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/buffer.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 boost::asio::write
  35  *
  36  * @brief Write a certain amount of data to a stream before returning.
  37  */
  38 /*@{*/
  39
  40 /// Write all of the supplied data to a stream before returning.
  41 /**
  42  * This function is used to write a certain number of bytes of data to a stream.
  43  * The call will block until one of the following conditions is true:
  44  *
  45  * @li All of the data in the supplied buffers has been written. That is, the
  46  * bytes transferred is equal to the sum of the buffer sizes.
  47  *
  48  * @li An error occurred.
  49  *
  50  * This operation is implemented in terms of zero or more calls to the stream's
  51  * write_some function.
  52  *
  53  * @param s The stream to which the data is to be written. The type must support
  54  * the SyncWriteStream concept.
  55  *
  56  * @param buffers One or more buffers containing the data to be written. The sum
  57  * of the buffer sizes indicates the maximum number of bytes to write to the
  58  * stream.
  59  *
  60  * @returns The number of bytes transferred.
  61  *
  62  * @throws boost::system::system_error Thrown on failure.
  63  *
  64  * @par Example
  65  * To write a single data buffer use the @ref buffer function as follows:
  66  * @code boost::asio::write(s, boost::asio::buffer(data, size)); @endcode
  67  * See the @ref buffer documentation for information on writing multiple
  68  * buffers in one go, and how to use it with arrays, boost::array or
  69  * std::vector.
  70  *
  71  * @note This overload is equivalent to calling:
  72  * @code boost::asio::write(
  73  *     s, buffers,
  74  *     boost::asio::transfer_all()); @endcode
  75  */
  76 template <typename SyncWriteStream, typename ConstBufferSequence>
  77 std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
  78     typename enable_if<
  79       is_const_buffer_sequence<ConstBufferSequence>::value
  80     >::type* = 0);
  81
  82 /// Write all of the supplied data to a stream before returning.
  83 /**
  84  * This function is used to write a certain number of bytes of data to a stream.
  85  * The call will block until one of the following conditions is true:
  86  *
  87  * @li All of the data in the supplied buffers has been written. That is, the
  88  * bytes transferred is equal to the sum of the buffer sizes.
  89  *
  90  * @li An error occurred.
  91  *
  92  * This operation is implemented in terms of zero or more calls to the stream's
  93  * write_some function.
  94  *
  95  * @param s The stream to which the data is to be written. The type must support
  96  * the SyncWriteStream concept.
  97  *
  98  * @param buffers One or more buffers containing the data to be written. The sum
  99  * of the buffer sizes indicates the maximum number of bytes to write to the
 100  * stream.
 101  *
 102  * @param ec Set to indicate what error occurred, if any.
 103  *
 104  * @returns The number of bytes transferred.
 105  *
 106  * @par Example
 107  * To write a single data buffer use the @ref buffer function as follows:
 108  * @code boost::asio::write(s, boost::asio::buffer(data, size), ec); @endcode
 109  * See the @ref buffer documentation for information on writing multiple
 110  * buffers in one go, and how to use it with arrays, boost::array or
 111  * std::vector.
 112  *
 113  * @note This overload is equivalent to calling:
 114  * @code boost::asio::write(
 115  *     s, buffers,
 116  *     boost::asio::transfer_all(), ec); @endcode
 117  */
 118 template <typename SyncWriteStream, typename ConstBufferSequence>
 119 std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
 120     boost::system::error_code& ec,
 121     typename enable_if<
 122       is_const_buffer_sequence<ConstBufferSequence>::value
 123     >::type* = 0);
 124
 125 /// Write a certain amount of data to a stream before returning.
 126 /**
 127  * This function is used to write a certain number of bytes of data to a stream.
 128  * The call will block until one of the following conditions is true:
 129  *
 130  * @li All of the data in the supplied buffers has been written. That is, the
 131  * bytes transferred is equal to the sum of the buffer sizes.
 132  *
 133  * @li The completion_condition function object returns 0.
 134  *
 135  * This operation is implemented in terms of zero or more calls to the stream's
 136  * write_some function.
 137  *
 138  * @param s The stream to which the data is to be written. The type must support
 139  * the SyncWriteStream concept.
 140  *
 141  * @param buffers One or more buffers containing the data to be written. The sum
 142  * of the buffer sizes indicates the maximum number of bytes to write to the
 143  * stream.
 144  *
 145  * @param completion_condition The function object to be called to determine
 146  * whether the write operation is complete. The signature of the function object
 147  * must be:
 148  * @code std::size_t completion_condition(
 149  *   // Result of latest write_some operation.
 150  *   const boost::system::error_code& error,
 151  *
 152  *   // Number of bytes transferred so far.
 153  *   std::size_t bytes_transferred
 154  * ); @endcode
 155  * A return value of 0 indicates that the write operation is complete. A
 156  * non-zero return value indicates the maximum number of bytes to be written on
 157  * the next call to the stream's write_some function.
 158  *
 159  * @returns The number of bytes transferred.
 160  *
 161  * @throws boost::system::system_error Thrown on failure.
 162  *
 163  * @par Example
 164  * To write a single data buffer use the @ref buffer function as follows:
 165  * @code boost::asio::write(s, boost::asio::buffer(data, size),
 166  *     boost::asio::transfer_at_least(32)); @endcode
 167  * See the @ref buffer documentation for information on writing multiple
 168  * buffers in one go, and how to use it with arrays, boost::array or
 169  * std::vector.
 170  */
 171 template <typename SyncWriteStream, typename ConstBufferSequence,
 172     typename CompletionCondition>
 173 std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
 174     CompletionCondition completion_condition,
 175     typename enable_if<
 176       is_const_buffer_sequence<ConstBufferSequence>::value
 177     >::type* = 0);
 178
 179 /// Write a certain amount of data to a stream before returning.
 180 /**
 181  * This function is used to write a certain number of bytes of data to a stream.
 182  * The call will block until one of the following conditions is true:
 183  *
 184  * @li All of the data in the supplied buffers has been written. That is, the
 185  * bytes transferred is equal to the sum of the buffer sizes.
 186  *
 187  * @li The completion_condition function object returns 0.
 188  *
 189  * This operation is implemented in terms of zero or more calls to the stream's
 190  * write_some function.
 191  *
 192  * @param s The stream to which the data is to be written. The type must support
 193  * the SyncWriteStream concept.
 194  *
 195  * @param buffers One or more buffers containing the data to be written. The sum
 196  * of the buffer sizes indicates the maximum number of bytes to write to the
 197  * stream.
 198  *
 199  * @param completion_condition The function object to be called to determine
 200  * whether the write operation is complete. The signature of the function object
 201  * must be:
 202  * @code std::size_t completion_condition(
 203  *   // Result of latest write_some operation.
 204  *   const boost::system::error_code& error,
 205  *
 206  *   // Number of bytes transferred so far.
 207  *   std::size_t bytes_transferred
 208  * ); @endcode
 209  * A return value of 0 indicates that the write operation is complete. A
 210  * non-zero return value indicates the maximum number of bytes to be written on
 211  * the next call to the stream's write_some function.
 212  *
 213  * @param ec Set to indicate what error occurred, if any.
 214  *
 215  * @returns The number of bytes written. If an error occurs, returns the total
 216  * number of bytes successfully transferred prior to the error.
 217  */
 218 template <typename SyncWriteStream, typename ConstBufferSequence,
 219     typename CompletionCondition>
 220 std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
 221     CompletionCondition completion_condition, boost::system::error_code& ec,
 222     typename enable_if<
 223       is_const_buffer_sequence<ConstBufferSequence>::value
 224     >::type* = 0);
 225
 226 /// Write all of the supplied data to a stream before returning.
 227 /**
 228  * This function is used to write a certain number of bytes of data to a stream.
 229  * The call will block until one of the following conditions is true:
 230  *
 231  * @li All of the data in the supplied dynamic buffer sequence has been written.
 232  *
 233  * @li An error occurred.
 234  *
 235  * This operation is implemented in terms of zero or more calls to the stream's
 236  * write_some function.
 237  *
 238  * @param s The stream to which the data is to be written. The type must support
 239  * the SyncWriteStream concept.
 240  *
 241  * @param buffers The dynamic buffer sequence from which data will be written.
 242  * Successfully written data is automatically consumed from the buffers.
 243  *
 244  * @returns The number of bytes transferred.
 245  *
 246  * @throws boost::system::system_error Thrown on failure.
 247  *
 248  * @note This overload is equivalent to calling:
 249  * @code boost::asio::write(
 250  *     s, buffers,
 251  *     boost::asio::transfer_all()); @endcode
 252  */
 253 template <typename SyncWriteStream, typename DynamicBuffer>
 254 std::size_t write(SyncWriteStream& s,
 255     BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
 256     typename enable_if<
 257       is_dynamic_buffer<DynamicBuffer>::value
 258     >::type* = 0);
 259
 260 /// Write all of the supplied data to a stream before returning.
 261 /**
 262  * This function is used to write a certain number of bytes of data to a stream.
 263  * The call will block until one of the following conditions is true:
 264  *
 265  * @li All of the data in the supplied dynamic buffer sequence has been written.
 266  *
 267  * @li An error occurred.
 268  *
 269  * This operation is implemented in terms of zero or more calls to the stream's
 270  * write_some function.
 271  *
 272  * @param s The stream to which the data is to be written. The type must support
 273  * the SyncWriteStream concept.
 274  *
 275  * @param buffers The dynamic buffer sequence from which data will be written.
 276  * Successfully written data is automatically consumed from the buffers.
 277  *
 278  * @param ec Set to indicate what error occurred, if any.
 279  *
 280  * @returns The number of bytes transferred.
 281  *
 282  * @note This overload is equivalent to calling:
 283  * @code boost::asio::write(
 284  *     s, buffers,
 285  *     boost::asio::transfer_all(), ec); @endcode
 286  */
 287 template <typename SyncWriteStream, typename DynamicBuffer>
 288 std::size_t write(SyncWriteStream& s,
 289     BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
 290     boost::system::error_code& ec,
 291     typename enable_if<
 292       is_dynamic_buffer<DynamicBuffer>::value
 293     >::type* = 0);
 294
 295 /// Write a certain amount of data to a stream before returning.
 296 /**
 297  * This function is used to write a certain number of bytes of data to a stream.
 298  * The call will block until one of the following conditions is true:
 299  *
 300  * @li All of the data in the supplied dynamic buffer sequence has been written.
 301  *
 302  * @li The completion_condition function object returns 0.
 303  *
 304  * This operation is implemented in terms of zero or more calls to the stream's
 305  * write_some function.
 306  *
 307  * @param s The stream to which the data is to be written. The type must support
 308  * the SyncWriteStream concept.
 309  *
 310  * @param buffers The dynamic buffer sequence from which data will be written.
 311  * Successfully written data is automatically consumed from the buffers.
 312  *
 313  * @param completion_condition The function object to be called to determine
 314  * whether the write operation is complete. The signature of the function object
 315  * must be:
 316  * @code std::size_t completion_condition(
 317  *   // Result of latest write_some operation.
 318  *   const boost::system::error_code& error,
 319  *
 320  *   // Number of bytes transferred so far.
 321  *   std::size_t bytes_transferred
 322  * ); @endcode
 323  * A return value of 0 indicates that the write operation is complete. A
 324  * non-zero return value indicates the maximum number of bytes to be written on
 325  * the next call to the stream's write_some function.
 326  *
 327  * @returns The number of bytes transferred.
 328  *
 329  * @throws boost::system::system_error Thrown on failure.
 330  */
 331 template <typename SyncWriteStream, typename DynamicBuffer,
 332     typename CompletionCondition>
 333 std::size_t write(SyncWriteStream& s,
 334     BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
 335     CompletionCondition completion_condition,
 336     typename enable_if<
 337       is_dynamic_buffer<DynamicBuffer>::value
 338     >::type* = 0);
 339
 340 /// Write a certain amount of data to a stream before returning.
 341 /**
 342  * This function is used to write a certain number of bytes of data to a stream.
 343  * The call will block until one of the following conditions is true:
 344  *
 345  * @li All of the data in the supplied dynamic buffer sequence has been written.
 346  *
 347  * @li The completion_condition function object returns 0.
 348  *
 349  * This operation is implemented in terms of zero or more calls to the stream's
 350  * write_some function.
 351  *
 352  * @param s The stream to which the data is to be written. The type must support
 353  * the SyncWriteStream concept.
 354  *
 355  * @param buffers The dynamic buffer sequence from which data will be written.
 356  * Successfully written data is automatically consumed from the buffers.
 357  *
 358  * @param completion_condition The function object to be called to determine
 359  * whether the write operation is complete. The signature of the function object
 360  * must be:
 361  * @code std::size_t completion_condition(
 362  *   // Result of latest write_some operation.
 363  *   const boost::system::error_code& error,
 364  *
 365  *   // Number of bytes transferred so far.
 366  *   std::size_t bytes_transferred
 367  * ); @endcode
 368  * A return value of 0 indicates that the write operation is complete. A
 369  * non-zero return value indicates the maximum number of bytes to be written on
 370  * the next call to the stream's write_some function.
 371  *
 372  * @param ec Set to indicate what error occurred, if any.
 373  *
 374  * @returns The number of bytes written. If an error occurs, returns the total
 375  * number of bytes successfully transferred prior to the error.
 376  */
 377 template <typename SyncWriteStream, typename DynamicBuffer,
 378     typename CompletionCondition>
 379 std::size_t write(SyncWriteStream& s,
 380     BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
 381     CompletionCondition completion_condition, boost::system::error_code& ec,
 382     typename enable_if<
 383       is_dynamic_buffer<DynamicBuffer>::value
 384     >::type* = 0);
 385
 386 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 387 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 388
 389 /// Write all of the supplied data to a stream before returning.
 390 /**
 391  * This function is used to write a certain number of bytes of data to a stream.
 392  * The call will block until one of the following conditions is true:
 393  *
 394  * @li All of the data in the supplied basic_streambuf has been written.
 395  *
 396  * @li An error occurred.
 397  *
 398  * This operation is implemented in terms of zero or more calls to the stream's
 399  * write_some function.
 400  *
 401  * @param s The stream to which the data is to be written. The type must support
 402  * the SyncWriteStream concept.
 403  *
 404  * @param b The basic_streambuf object from which data will be written.
 405  *
 406  * @returns The number of bytes transferred.
 407  *
 408  * @throws boost::system::system_error Thrown on failure.
 409  *
 410  * @note This overload is equivalent to calling:
 411  * @code boost::asio::write(
 412  *     s, b,
 413  *     boost::asio::transfer_all()); @endcode
 414  */
 415 template <typename SyncWriteStream, typename Allocator>
 416 std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b);
 417
 418 /// Write all of the supplied data to a stream before returning.
 419 /**
 420  * This function is used to write a certain number of bytes of data to a stream.
 421  * The call will block until one of the following conditions is true:
 422  *
 423  * @li All of the data in the supplied basic_streambuf has been written.
 424  *
 425  * @li An error occurred.
 426  *
 427  * This operation is implemented in terms of zero or more calls to the stream's
 428  * write_some function.
 429  *
 430  * @param s The stream to which the data is to be written. The type must support
 431  * the SyncWriteStream concept.
 432  *
 433  * @param b The basic_streambuf object from which data will be written.
 434  *
 435  * @param ec Set to indicate what error occurred, if any.
 436  *
 437  * @returns The number of bytes transferred.
 438  *
 439  * @note This overload is equivalent to calling:
 440  * @code boost::asio::write(
 441  *     s, b,
 442  *     boost::asio::transfer_all(), ec); @endcode
 443  */
 444 template <typename SyncWriteStream, typename Allocator>
 445 std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
 446     boost::system::error_code& ec);
 447
 448 /// Write a certain amount of data to a stream before returning.
 449 /**
 450  * This function is used to write a certain number of bytes of data to a stream.
 451  * The call will block until one of the following conditions is true:
 452  *
 453  * @li All of the data in the supplied basic_streambuf has been written.
 454  *
 455  * @li The completion_condition function object returns 0.
 456  *
 457  * This operation is implemented in terms of zero or more calls to the stream's
 458  * write_some function.
 459  *
 460  * @param s The stream to which the data is to be written. The type must support
 461  * the SyncWriteStream concept.
 462  *
 463  * @param b The basic_streambuf object from which data will be written.
 464  *
 465  * @param completion_condition The function object to be called to determine
 466  * whether the write operation is complete. The signature of the function object
 467  * must be:
 468  * @code std::size_t completion_condition(
 469  *   // Result of latest write_some operation.
 470  *   const boost::system::error_code& error,
 471  *
 472  *   // Number of bytes transferred so far.
 473  *   std::size_t bytes_transferred
 474  * ); @endcode
 475  * A return value of 0 indicates that the write operation is complete. A
 476  * non-zero return value indicates the maximum number of bytes to be written on
 477  * the next call to the stream's write_some function.
 478  *
 479  * @returns The number of bytes transferred.
 480  *
 481  * @throws boost::system::system_error Thrown on failure.
 482  */
 483 template <typename SyncWriteStream, typename Allocator,
 484     typename CompletionCondition>
 485 std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
 486     CompletionCondition completion_condition);
 487
 488 /// Write a certain amount of data to a stream before returning.
 489 /**
 490  * This function is used to write a certain number of bytes of data to a stream.
 491  * The call will block until one of the following conditions is true:
 492  *
 493  * @li All of the data in the supplied basic_streambuf has been written.
 494  *
 495  * @li The completion_condition function object returns 0.
 496  *
 497  * This operation is implemented in terms of zero or more calls to the stream's
 498  * write_some function.
 499  *
 500  * @param s The stream to which the data is to be written. The type must support
 501  * the SyncWriteStream concept.
 502  *
 503  * @param b The basic_streambuf object from which data will be written.
 504  *
 505  * @param completion_condition The function object to be called to determine
 506  * whether the write operation is complete. The signature of the function object
 507  * must be:
 508  * @code std::size_t completion_condition(
 509  *   // Result of latest write_some operation.
 510  *   const boost::system::error_code& error,
 511  *
 512  *   // Number of bytes transferred so far.
 513  *   std::size_t bytes_transferred
 514  * ); @endcode
 515  * A return value of 0 indicates that the write operation is complete. A
 516  * non-zero return value indicates the maximum number of bytes to be written on
 517  * the next call to the stream's write_some function.
 518  *
 519  * @param ec Set to indicate what error occurred, if any.
 520  *
 521  * @returns The number of bytes written. If an error occurs, returns the total
 522  * number of bytes successfully transferred prior to the error.
 523  */
 524 template <typename SyncWriteStream, typename Allocator,
 525     typename CompletionCondition>
 526 std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
 527     CompletionCondition completion_condition, boost::system::error_code& ec);
 528
 529 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 530 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 531
 532 /*@}*/
 533 /**
 534  * @defgroup async_write boost::asio::async_write
 535  *
 536  * @brief Start an asynchronous operation to write a certain amount of data to a
 537  * stream.
 538  */
 539 /*@{*/
 540
 541 /// Start an asynchronous operation to write all of the supplied data to a
 542 /// stream.
 543 /**
 544  * This function is used to asynchronously write a certain number of bytes of
 545  * data to a stream. The function call always returns immediately. The
 546  * asynchronous operation will continue until one of the following conditions
 547  * is true:
 548  *
 549  * @li All of the data in the supplied buffers has been written. That is, the
 550  * bytes transferred is equal to the sum of the buffer sizes.
 551  *
 552  * @li An error occurred.
 553  *
 554  * This operation is implemented in terms of zero or more calls to the stream's
 555  * async_write_some function, and is known as a <em>composed operation</em>. The
 556  * program must ensure that the stream performs no other write operations (such
 557  * as async_write, the stream's async_write_some function, or any other composed
 558  * operations that perform writes) until this operation completes.
 559  *
 560  * @param s The stream to which the data is to be written. The type must support
 561  * the AsyncWriteStream concept.
 562  *
 563  * @param buffers One or more buffers containing the data to be written.
 564  * Although the buffers object may be copied as necessary, ownership of the
 565  * underlying memory blocks is retained by the caller, which must guarantee
 566  * that they remain valid until the handler is called.
 567  *
 568  * @param handler The handler to be called when the write operation completes.
 569  * Copies will be made of the handler as required. The function signature of
 570  * the handler must be:
 571  * @code void handler(
 572  *   const boost::system::error_code& error, // Result of operation.
 573  *
 574  *   std::size_t bytes_transferred           // Number of bytes written from the
 575  *                                           // buffers. If an error occurred,
 576  *                                           // this will be less than the sum
 577  *                                           // of the buffer sizes.
 578  * ); @endcode
 579  * Regardless of whether the asynchronous operation completes immediately or
 580  * not, the handler will not be invoked from within this function. Invocation of
 581  * the handler will be performed in a manner equivalent to using
 582  * boost::asio::io_context::post().
 583  *
 584  * @par Example
 585  * To write a single data buffer use the @ref buffer function as follows:
 586  * @code
 587  * boost::asio::async_write(s, boost::asio::buffer(data, size), handler);
 588  * @endcode
 589  * See the @ref buffer documentation for information on writing multiple
 590  * buffers in one go, and how to use it with arrays, boost::array or
 591  * std::vector.
 592  */
 593 template <typename AsyncWriteStream, typename ConstBufferSequence,
 594     typename WriteHandler>
 595 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 596     void (boost::system::error_code, std::size_t))
 597 async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
 598     BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
 599     typename enable_if<
 600       is_const_buffer_sequence<ConstBufferSequence>::value
 601     >::type* = 0);
 602
 603 /// Start an asynchronous operation to write a certain amount of data to a
 604 /// stream.
 605 /**
 606  * This function is used to asynchronously write a certain number of bytes of
 607  * data to a stream. The function call always returns immediately. The
 608  * asynchronous operation will continue until one of the following conditions
 609  * is true:
 610  *
 611  * @li All of the data in the supplied buffers has been written. That is, the
 612  * bytes transferred is equal to the sum of the buffer sizes.
 613  *
 614  * @li The completion_condition function object returns 0.
 615  *
 616  * This operation is implemented in terms of zero or more calls to the stream's
 617  * async_write_some function, and is known as a <em>composed operation</em>. The
 618  * program must ensure that the stream performs no other write operations (such
 619  * as async_write, the stream's async_write_some function, or any other composed
 620  * operations that perform writes) until this operation completes.
 621  *
 622  * @param s The stream to which the data is to be written. The type must support
 623  * the AsyncWriteStream concept.
 624  *
 625  * @param buffers One or more buffers containing the data to be written.
 626  * Although the buffers object may be copied as necessary, ownership of the
 627  * underlying memory blocks is retained by the caller, which must guarantee
 628  * that they remain valid until the handler is called.
 629  *
 630  * @param completion_condition The function object to be called to determine
 631  * whether the write operation is complete. The signature of the function object
 632  * must be:
 633  * @code std::size_t completion_condition(
 634  *   // Result of latest async_write_some operation.
 635  *   const boost::system::error_code& error,
 636  *
 637  *   // Number of bytes transferred so far.
 638  *   std::size_t bytes_transferred
 639  * ); @endcode
 640  * A return value of 0 indicates that the write operation is complete. A
 641  * non-zero return value indicates the maximum number of bytes to be written on
 642  * the next call to the stream's async_write_some function.
 643  *
 644  * @param handler The handler to be called when the write operation completes.
 645  * Copies will be made of the handler as required. The function signature of the
 646  * handler must be:
 647  * @code void handler(
 648  *   const boost::system::error_code& error, // Result of operation.
 649  *
 650  *   std::size_t bytes_transferred           // Number of bytes written from the
 651  *                                           // buffers. If an error occurred,
 652  *                                           // this will be less than the sum
 653  *                                           // of the buffer sizes.
 654  * ); @endcode
 655  * Regardless of whether the asynchronous operation completes immediately or
 656  * not, the handler will not be invoked from within this function. Invocation of
 657  * the handler will be performed in a manner equivalent to using
 658  * boost::asio::io_context::post().
 659  *
 660  * @par Example
 661  * To write a single data buffer use the @ref buffer function as follows:
 662  * @code boost::asio::async_write(s,
 663  *     boost::asio::buffer(data, size),
 664  *     boost::asio::transfer_at_least(32),
 665  *     handler); @endcode
 666  * See the @ref buffer documentation for information on writing multiple
 667  * buffers in one go, and how to use it with arrays, boost::array or
 668  * std::vector.
 669  */
 670 template <typename AsyncWriteStream, typename ConstBufferSequence,
 671     typename CompletionCondition, typename WriteHandler>
 672 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 673     void (boost::system::error_code, std::size_t))
 674 async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
 675     CompletionCondition completion_condition,
 676     BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
 677     typename enable_if<
 678       is_const_buffer_sequence<ConstBufferSequence>::value
 679     >::type* = 0);
 680
 681 /// Start an asynchronous operation to write all of the supplied data to a
 682 /// stream.
 683 /**
 684  * This function is used to asynchronously write a certain number of bytes of
 685  * data to a stream. The function call always returns immediately. The
 686  * asynchronous operation will continue until one of the following conditions
 687  * is true:
 688  *
 689  * @li All of the data in the supplied dynamic buffer sequence has been written.
 690  *
 691  * @li An error occurred.
 692  *
 693  * This operation is implemented in terms of zero or more calls to the stream's
 694  * async_write_some function, and is known as a <em>composed operation</em>. The
 695  * program must ensure that the stream performs no other write operations (such
 696  * as async_write, the stream's async_write_some function, or any other composed
 697  * operations that perform writes) until this operation completes.
 698  *
 699  * @param s The stream to which the data is to be written. The type must support
 700  * the AsyncWriteStream concept.
 701  *
 702  * @param buffers The dynamic buffer sequence from which data will be written.
 703  * Although the buffers object may be copied as necessary, ownership of the
 704  * underlying memory blocks is retained by the caller, which must guarantee
 705  * that they remain valid until the handler is called. Successfully written
 706  * data is automatically consumed from the buffers.
 707  *
 708  * @param handler The handler to be called when the write operation completes.
 709  * Copies will be made of the handler as required. The function signature of the
 710  * handler must be:
 711  * @code void handler(
 712  *   const boost::system::error_code& error, // Result of operation.
 713  *
 714  *   std::size_t bytes_transferred           // Number of bytes written from the
 715  *                                           // buffers. If an error occurred,
 716  *                                           // this will be less than the sum
 717  *                                           // of the buffer sizes.
 718  * ); @endcode
 719  * Regardless of whether the asynchronous operation completes immediately or
 720  * not, the handler will not be invoked from within this function. Invocation of
 721  * the handler will be performed in a manner equivalent to using
 722  * boost::asio::io_context::post().
 723  */
 724 template <typename AsyncWriteStream,
 725     typename DynamicBuffer, typename WriteHandler>
 726 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 727     void (boost::system::error_code, std::size_t))
 728 async_write(AsyncWriteStream& s,
 729     BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
 730     BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
 731     typename enable_if<
 732       is_dynamic_buffer<DynamicBuffer>::value
 733     >::type* = 0);
 734
 735 /// Start an asynchronous operation to write a certain amount of data to a
 736 /// stream.
 737 /**
 738  * This function is used to asynchronously write a certain number of bytes of
 739  * data to a stream. The function call always returns immediately. The
 740  * asynchronous operation will continue until one of the following conditions
 741  * is true:
 742  *
 743  * @li All of the data in the supplied dynamic buffer sequence has been written.
 744  *
 745  * @li The completion_condition function object returns 0.
 746  *
 747  * This operation is implemented in terms of zero or more calls to the stream's
 748  * async_write_some function, and is known as a <em>composed operation</em>. The
 749  * program must ensure that the stream performs no other write operations (such
 750  * as async_write, the stream's async_write_some function, or any other composed
 751  * operations that perform writes) until this operation completes.
 752  *
 753  * @param s The stream to which the data is to be written. The type must support
 754  * the AsyncWriteStream concept.
 755  *
 756  * @param buffers The dynamic buffer sequence from which data will be written.
 757  * Although the buffers object may be copied as necessary, ownership of the
 758  * underlying memory blocks is retained by the caller, which must guarantee
 759  * that they remain valid until the handler is called. Successfully written
 760  * data is automatically consumed from the buffers.
 761  *
 762  * @param completion_condition The function object to be called to determine
 763  * whether the write operation is complete. The signature of the function object
 764  * must be:
 765  * @code std::size_t completion_condition(
 766  *   // Result of latest async_write_some operation.
 767  *   const boost::system::error_code& error,
 768  *
 769  *   // Number of bytes transferred so far.
 770  *   std::size_t bytes_transferred
 771  * ); @endcode
 772  * A return value of 0 indicates that the write operation is complete. A
 773  * non-zero return value indicates the maximum number of bytes to be written on
 774  * the next call to the stream's async_write_some function.
 775  *
 776  * @param handler The handler to be called when the write operation completes.
 777  * Copies will be made of the handler as required. The function signature of the
 778  * handler must be:
 779  * @code void handler(
 780  *   const boost::system::error_code& error, // Result of operation.
 781  *
 782  *   std::size_t bytes_transferred           // Number of bytes written from the
 783  *                                           // buffers. If an error occurred,
 784  *                                           // this will be less than the sum
 785  *                                           // of the buffer sizes.
 786  * ); @endcode
 787  * Regardless of whether the asynchronous operation completes immediately or
 788  * not, the handler will not be invoked from within this function. Invocation of
 789  * the handler will be performed in a manner equivalent to using
 790  * boost::asio::io_context::post().
 791  */
 792 template <typename AsyncWriteStream, typename DynamicBuffer,
 793     typename CompletionCondition, typename WriteHandler>
 794 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 795     void (boost::system::error_code, std::size_t))
 796 async_write(AsyncWriteStream& s,
 797     BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers,
 798     CompletionCondition completion_condition,
 799     BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
 800     typename enable_if<
 801       is_dynamic_buffer<DynamicBuffer>::value
 802     >::type* = 0);
 803
 804 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 805 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 806
 807 /// Start an asynchronous operation to write all of the supplied data to a
 808 /// stream.
 809 /**
 810  * This function is used to asynchronously write a certain number of bytes of
 811  * data to a stream. The function call always returns immediately. The
 812  * asynchronous operation will continue until one of the following conditions
 813  * is true:
 814  *
 815  * @li All of the data in the supplied basic_streambuf has been written.
 816  *
 817  * @li An error occurred.
 818  *
 819  * This operation is implemented in terms of zero or more calls to the stream's
 820  * async_write_some function, and is known as a <em>composed operation</em>. The
 821  * program must ensure that the stream performs no other write operations (such
 822  * as async_write, the stream's async_write_some function, or any other composed
 823  * operations that perform writes) until this operation completes.
 824  *
 825  * @param s The stream to which the data is to be written. The type must support
 826  * the AsyncWriteStream concept.
 827  *
 828  * @param b A basic_streambuf object from which data will be written. Ownership
 829  * of the streambuf is retained by the caller, which must guarantee that it
 830  * remains valid until the handler is called.
 831  *
 832  * @param handler The handler to be called when the write operation completes.
 833  * Copies will be made of the handler as required. The function signature of the
 834  * handler must be:
 835  * @code void handler(
 836  *   const boost::system::error_code& error, // Result of operation.
 837  *
 838  *   std::size_t bytes_transferred           // Number of bytes written from the
 839  *                                           // buffers. If an error occurred,
 840  *                                           // this will be less than the sum
 841  *                                           // of the buffer sizes.
 842  * ); @endcode
 843  * Regardless of whether the asynchronous operation completes immediately or
 844  * not, the handler will not be invoked from within this function. Invocation of
 845  * the handler will be performed in a manner equivalent to using
 846  * boost::asio::io_context::post().
 847  */
 848 template <typename AsyncWriteStream, typename Allocator, typename WriteHandler>
 849 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 850     void (boost::system::error_code, std::size_t))
 851 async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
 852     BOOST_ASIO_MOVE_ARG(WriteHandler) handler);
 853
 854 /// Start an asynchronous operation to write a certain amount of data to a
 855 /// stream.
 856 /**
 857  * This function is used to asynchronously write a certain number of bytes of
 858  * data to a stream. The function call always returns immediately. The
 859  * asynchronous operation will continue until one of the following conditions
 860  * is true:
 861  *
 862  * @li All of the data in the supplied basic_streambuf has been written.
 863  *
 864  * @li The completion_condition function object returns 0.
 865  *
 866  * This operation is implemented in terms of zero or more calls to the stream's
 867  * async_write_some function, and is known as a <em>composed operation</em>. The
 868  * program must ensure that the stream performs no other write operations (such
 869  * as async_write, the stream's async_write_some function, or any other composed
 870  * operations that perform writes) until this operation completes.
 871  *
 872  * @param s The stream to which the data is to be written. The type must support
 873  * the AsyncWriteStream concept.
 874  *
 875  * @param b A basic_streambuf object from which data will be written. Ownership
 876  * of the streambuf is retained by the caller, which must guarantee that it
 877  * remains valid until the handler is called.
 878  *
 879  * @param completion_condition The function object to be called to determine
 880  * whether the write operation is complete. The signature of the function object
 881  * must be:
 882  * @code std::size_t completion_condition(
 883  *   // Result of latest async_write_some operation.
 884  *   const boost::system::error_code& error,
 885  *
 886  *   // Number of bytes transferred so far.
 887  *   std::size_t bytes_transferred
 888  * ); @endcode
 889  * A return value of 0 indicates that the write operation is complete. A
 890  * non-zero return value indicates the maximum number of bytes to be written on
 891  * the next call to the stream's async_write_some function.
 892  *
 893  * @param handler The handler to be called when the write operation completes.
 894  * Copies will be made of the handler as required. The function signature of the
 895  * handler must be:
 896  * @code void handler(
 897  *   const boost::system::error_code& error, // Result of operation.
 898  *
 899  *   std::size_t bytes_transferred           // Number of bytes written from the
 900  *                                           // buffers. If an error occurred,
 901  *                                           // this will be less than the sum
 902  *                                           // of the buffer sizes.
 903  * ); @endcode
 904  * Regardless of whether the asynchronous operation completes immediately or
 905  * not, the handler will not be invoked from within this function. Invocation of
 906  * the handler will be performed in a manner equivalent to using
 907  * boost::asio::io_context::post().
 908  */
 909 template <typename AsyncWriteStream, typename Allocator,
 910     typename CompletionCondition, typename WriteHandler>
 911 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 912     void (boost::system::error_code, std::size_t))
 913 async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
 914     CompletionCondition completion_condition,
 915     BOOST_ASIO_MOVE_ARG(WriteHandler) handler);
 916
 917 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 918 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 919
 920 /*@}*/
 921
 922 } // namespace asio
 923 } // namespace boost
 924
 925 #include <boost/asio/detail/pop_options.hpp>
 926
 927 #include <boost/asio/impl/write.hpp>
 928
 929 #endif // BOOST_ASIO_WRITE_HPP