ceph/src/boost/boost/asio/read.hpp

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