ceph/src/boost/boost/beast/http/read.hpp

   1 //
   2 // Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
   3 //
   4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 //
   7 // Official repository: https://github.com/boostorg/beast
   8 //
   9
  10 #ifndef BOOST_BEAST_HTTP_READ_HPP
  11 #define BOOST_BEAST_HTTP_READ_HPP
  12
  13 #include <boost/beast/core/detail/config.hpp>
  14 #include <boost/beast/core/error.hpp>
  15 #include <boost/beast/http/basic_parser.hpp>
  16 #include <boost/beast/http/message.hpp>
  17 #include <boost/asio/async_result.hpp>
  18
  19 namespace boost {
  20 namespace beast {
  21 namespace http {
  22
  23 /** Read part of a message from a stream using a parser.
  24
  25     This function is used to read part of a message from a stream into a
  26     subclass of @ref basic_parser.
  27     The call will block until one of the following conditions is true:
  28
  29     @li A call to @ref basic_parser::put with a non-empty buffer sequence
  30     is successful.
  31
  32     @li An error occurs.
  33
  34     This operation is implemented in terms of one or
  35     more calls to the stream's `read_some` function.
  36     The implementation may read additional octets that lie past the
  37     end of the message being read. This additional data is stored
  38     in the dynamic buffer, which must be retained for subsequent reads.
  39
  40     If the stream returns the error `boost::asio::error::eof` indicating the
  41     end of file during a read, the error returned from this function will be:
  42
  43     @li @ref error::end_of_stream if no octets were parsed, or
  44
  45     @li @ref error::partial_message if any octets were parsed but the
  46     message was incomplete, otherwise:
  47
  48     @li A successful result. A subsequent attempt to read will
  49     return @ref error::end_of_stream
  50
  51     @param stream The stream from which the data is to be read.
  52     The type must support the @b SyncReadStream concept.
  53
  54     @param buffer A @b DynamicBuffer holding additional bytes
  55     read by the implementation from the stream. This is both
  56     an input and an output parameter; on entry, any data in the
  57     dynamic buffer's input sequence will be given to the parser
  58     first.
  59
  60     @param parser The parser to use.
  61
  62     @return The number of bytes transferred to the parser.
  63
  64     @throws system_error Thrown on failure.
  65 */
  66 template<
  67     class SyncReadStream,
  68     class DynamicBuffer,
  69     bool isRequest, class Derived>
  70 std::size_t
  71 read_some(
  72     SyncReadStream& stream,
  73     DynamicBuffer& buffer,
  74     basic_parser<isRequest, Derived>& parser);
  75
  76 /** Read part of a message from a stream using a parser.
  77
  78     This function is used to read part of a message from a stream into a
  79     subclass of @ref basic_parser.
  80     The call will block until one of the following conditions is true:
  81
  82     @li A call to @ref basic_parser::put with a non-empty buffer sequence
  83     is successful.
  84
  85     @li An error occurs.
  86
  87     This operation is implemented in terms of one or
  88     more calls to the stream's `read_some` function.
  89     The implementation may read additional octets that lie past the
  90     end of the message being read. This additional data is stored
  91     in the dynamic buffer, which must be retained for subsequent reads.
  92
  93     If the stream returns the error `boost::asio::error::eof` indicating the
  94     end of file during a read, the error returned from this function will be:
  95
  96     @li @ref error::end_of_stream if no octets were parsed, or
  97
  98     @li @ref error::partial_message if any octets were parsed but the
  99     message was incomplete, otherwise:
 100
 101     @li A successful result. A subsequent attempt to read will
 102     return @ref error::end_of_stream
 103
 104     The function returns the number of bytes processed from the dynamic
 105     buffer. The caller should remove these bytes by calling `consume` on
 106     the dynamic buffer, regardless of any error.
 107
 108     @param stream The stream from which the data is to be read.
 109     The type must support the @b SyncReadStream concept.
 110
 111     @param buffer A @b DynamicBuffer holding additional bytes
 112     read by the implementation from the stream. This is both
 113     an input and an output parameter; on entry, any data in the
 114     dynamic buffer's input sequence will be given to the parser
 115     first.
 116
 117     @param parser The parser to use.
 118
 119     @param ec Set to the error, if any occurred.
 120
 121     @return The number of bytes transferred to the parser.
 122 */
 123 template<
 124     class SyncReadStream,
 125     class DynamicBuffer,
 126     bool isRequest, class Derived>
 127 std::size_t
 128 read_some(
 129     SyncReadStream& stream,
 130     DynamicBuffer& buffer,
 131     basic_parser<isRequest, Derived>& parser,
 132     error_code& ec);
 133
 134 /** Read part of a message asynchronously from a stream using a parser.
 135
 136     This function is used to asynchronously read part of a message from
 137     a stream into a subclass of @ref basic_parser.
 138     The function call always returns immediately. The asynchronous operation
 139     will continue until one of the following conditions is true:
 140
 141     @li A call to @ref basic_parser::put with a non-empty buffer sequence
 142     is successful.
 143
 144     @li An error occurs.
 145
 146     This operation is implemented in terms of zero or more calls to
 147     the next layer's `async_read_some` function, and is known as a
 148     <em>composed operation</em>. The program must ensure that the
 149     stream performs no other reads until this operation completes.
 150     The implementation may read additional octets that lie past the
 151     end of the object being parsed. This additional data is stored
 152     in the stream buffer, which may be used in subsequent calls.
 153
 154     If the stream returns the error `boost::asio::error::eof` indicating the
 155     end of file during a read, the error returned from this function will be:
 156
 157     @li @ref error::end_of_stream if no octets were parsed, or
 158
 159     @li @ref error::partial_message if any octets were parsed but the
 160     message was incomplete, otherwise:
 161
 162     @li A successful result. A subsequent attempt to read will
 163     return @ref error::end_of_stream
 164
 165     @param stream The stream from which the data is to be read.
 166     The type must support the @b AsyncReadStream concept.
 167
 168     @param buffer A @b DynamicBuffer holding additional bytes
 169     read by the implementation from the stream. This is both
 170     an input and an output parameter; on entry, any data in the
 171     dynamic buffer's input sequence will be given to the parser
 172     first.
 173
 174     @param parser The parser to use.
 175     The object must remain valid at least until the
 176     handler is called; ownership is not transferred.
 177
 178     @param handler The handler to be called when the request
 179     completes. Copies will be made of the handler as required.
 180     The equivalent function signature of the handler must be:
 181     @code void handler(
 182         error_code const& error,        // result of operation
 183         std::size_t bytes_transferred   // the number of bytes transferred to the parser
 184     ); @endcode
 185     Regardless of whether the asynchronous operation completes
 186     immediately or not, the handler will not be invoked from within
 187     this function. Invocation of the handler will be performed in a
 188     manner equivalent to using `boost::asio::io_context::post`.
 189
 190     The completion handler will receive as a parameter the number
 191     of octets processed from the dynamic buffer. The octets should
 192     be removed by calling `consume` on the dynamic buffer after
 193     the read completes, regardless of any error.
 194 */
 195 template<
 196     class AsyncReadStream,
 197     class DynamicBuffer,
 198     bool isRequest, class Derived,
 199     class ReadHandler>
 200 BOOST_ASIO_INITFN_RESULT_TYPE(
 201     ReadHandler, void(error_code, std::size_t))
 202 async_read_some(
 203     AsyncReadStream& stream,
 204     DynamicBuffer& buffer,
 205     basic_parser<isRequest, Derived>& parser,
 206     ReadHandler&& handler);
 207
 208 //------------------------------------------------------------------------------
 209
 210 /** Read a header from a stream using a parser.
 211
 212     This function is used to read a header from a stream into a subclass
 213     of @ref basic_parser.
 214     The call will block until one of the following conditions is true:
 215
 216     @li @ref basic_parser::is_header_done returns `true`
 217
 218     @li An error occurs.
 219
 220     This operation is implemented in terms of one or
 221     more calls to the stream's `read_some` function.
 222     The implementation may read additional octets that lie past the
 223     end of the message being read. This additional data is stored
 224     in the dynamic buffer, which must be retained for subsequent reads.
 225
 226     If the stream returns the error `boost::asio::error::eof` indicating the
 227     end of file during a read, the error returned from this function will be:
 228
 229     @li @ref error::end_of_stream if no octets were parsed, or
 230
 231     @li @ref error::partial_message if any octets were parsed but the
 232     message was incomplete, otherwise:
 233
 234     @li A successful result. A subsequent attempt to read will
 235     return @ref error::end_of_stream
 236
 237     @param stream The stream from which the data is to be read.
 238     The type must support the @b SyncReadStream concept.
 239
 240     @param buffer A @b DynamicBuffer holding additional bytes
 241     read by the implementation from the stream. This is both
 242     an input and an output parameter; on entry, any data in the
 243     dynamic buffer's input sequence will be given to the parser
 244     first.
 245
 246     @param parser The parser to use.
 247
 248     @return The number of bytes transferred to the parser.
 249
 250     @throws system_error Thrown on failure.
 251
 252     @note The implementation will call @ref basic_parser::eager
 253     with the value `false` on the parser passed in.
 254 */
 255 template<
 256     class SyncReadStream,
 257     class DynamicBuffer,
 258     bool isRequest, class Derived>
 259 std::size_t
 260 read_header(
 261     SyncReadStream& stream,
 262     DynamicBuffer& buffer,
 263     basic_parser<isRequest, Derived>& parser);
 264
 265 /** Read a header from a stream using a parser.
 266
 267     This function is used to read a header from a stream into a subclass
 268     of @ref basic_parser.
 269     The call will block until one of the following conditions is true:
 270
 271     @li @ref basic_parser::is_header_done returns `true`
 272
 273     @li An error occurs.
 274
 275     This operation is implemented in terms of one or
 276     more calls to the stream's `read_some` function.
 277     The implementation may read additional octets that lie past the
 278     end of the message being read. This additional data is stored
 279     in the dynamic buffer, which must be retained for subsequent reads.
 280
 281     If the stream returns the error `boost::asio::error::eof` indicating the
 282     end of file during a read, the error returned from this function will be:
 283
 284     @li @ref error::end_of_stream if no octets were parsed, or
 285
 286     @li @ref error::partial_message if any octets were parsed but the
 287     message was incomplete, otherwise:
 288
 289     @li A successful result. A subsequent attempt to read will
 290     return @ref error::end_of_stream
 291
 292     @param stream The stream from which the data is to be read.
 293     The type must support the @b SyncReadStream concept.
 294
 295     @param buffer A @b DynamicBuffer holding additional bytes
 296     read by the implementation from the stream. This is both
 297     an input and an output parameter; on entry, any data in the
 298     dynamic buffer's input sequence will be given to the parser
 299     first.
 300
 301     @param parser The parser to use.
 302
 303     @param ec Set to the error, if any occurred.
 304
 305     @return The number of bytes transferred to the parser.
 306
 307     @note The implementation will call @ref basic_parser::eager
 308     with the value `false` on the parser passed in.
 309 */
 310 template<
 311     class SyncReadStream,
 312     class DynamicBuffer,
 313     bool isRequest, class Derived>
 314 std::size_t
 315 read_header(
 316     SyncReadStream& stream,
 317     DynamicBuffer& buffer,
 318     basic_parser<isRequest, Derived>& parser,
 319     error_code& ec);
 320
 321 /** Read a header from a stream asynchronously using a parser.
 322
 323     This function is used to asynchronously read a header from a stream
 324     into a subclass of @ref basic_parser.
 325     The function call always returns immediately. The asynchronous operation
 326     will continue until one of the following conditions is true:
 327
 328     @li @ref basic_parser::is_header_done returns `true`
 329
 330     @li An error occurs.
 331
 332     This operation is implemented in terms of one or more calls to
 333     the stream's `async_read_some` function, and is known as a
 334     <em>composed operation</em>. The program must ensure that the
 335     stream performs no other reads until this operation completes.
 336     The implementation may read additional octets that lie past the
 337     end of the message being read. This additional data is stored
 338     in the dynamic buffer, which must be retained for subsequent reads.
 339
 340     If the stream returns the error `boost::asio::error::eof` indicating the
 341     end of file during a read, the error returned from this function will be:
 342
 343     @li @ref error::end_of_stream if no octets were parsed, or
 344
 345     @li @ref error::partial_message if any octets were parsed but the
 346     message was incomplete, otherwise:
 347
 348     @li A successful result. A subsequent attempt to read will
 349     return @ref error::end_of_stream
 350
 351     @param stream The stream from which the data is to be read.
 352     The type must support the @b AsyncReadStream concept.
 353
 354     @param buffer A @b DynamicBuffer holding additional bytes
 355     read by the implementation from the stream. This is both
 356     an input and an output parameter; on entry, any data in the
 357     dynamic buffer's input sequence will be given to the parser
 358     first.
 359
 360     @param parser The parser to use.
 361     The object must remain valid at least until the
 362     handler is called; ownership is not transferred.
 363
 364     @param handler The handler to be called when the request
 365     completes. Copies will be made of the handler as required.
 366     The equivalent function signature of the handler must be:
 367     @code void handler(
 368         error_code const& error,        // result of operation,
 369         std::size_t bytes_transferred   // the number of bytes transferred to the parser
 370     ); @endcode
 371     Regardless of whether the asynchronous operation completes
 372     immediately or not, the handler will not be invoked from within
 373     this function. Invocation of the handler will be performed in a
 374     manner equivalent to using `boost::asio::io_context::post`.
 375
 376     @note The implementation will call @ref basic_parser::eager
 377     with the value `false` on the parser passed in.
 378 */
 379 template<
 380     class AsyncReadStream,
 381     class DynamicBuffer,
 382     bool isRequest, class Derived,
 383     class ReadHandler>
 384 BOOST_ASIO_INITFN_RESULT_TYPE(
 385     ReadHandler, void(error_code, std::size_t))
 386 async_read_header(
 387     AsyncReadStream& stream,
 388     DynamicBuffer& buffer,
 389     basic_parser<isRequest, Derived>& parser,
 390     ReadHandler&& handler);
 391
 392 //------------------------------------------------------------------------------
 393
 394 /** Read a complete message from a stream using a parser.
 395
 396     This function is used to read a complete message from a stream into a
 397     subclass of @ref basic_parser.
 398     The call will block until one of the following conditions is true:
 399
 400     @li @ref basic_parser::is_done returns `true`
 401
 402     @li An error occurs.
 403
 404     This operation is implemented in terms of one or
 405     more calls to the stream's `read_some` function.
 406     The implementation may read additional octets that lie past the
 407     end of the message being read. This additional data is stored
 408     in the dynamic buffer, which must be retained for subsequent reads.
 409
 410     If the stream returns the error `boost::asio::error::eof` indicating the
 411     end of file during a read, the error returned from this function will be:
 412
 413     @li @ref error::end_of_stream if no octets were parsed, or
 414
 415     @li @ref error::partial_message if any octets were parsed but the
 416     message was incomplete, otherwise:
 417
 418     @li A successful result. A subsequent attempt to read will
 419     return @ref error::end_of_stream
 420
 421     @param stream The stream from which the data is to be read.
 422     The type must support the @b SyncReadStream concept.
 423
 424     @param buffer A @b DynamicBuffer holding additional bytes
 425     read by the implementation from the stream. This is both
 426     an input and an output parameter; on entry, any data in the
 427     dynamic buffer's input sequence will be given to the parser
 428     first.
 429
 430     @param parser The parser to use.
 431
 432     @return The number of bytes transferred to the parser.
 433
 434     @throws system_error Thrown on failure.
 435
 436     @note The implementation will call @ref basic_parser::eager
 437     with the value `true` on the parser passed in.
 438 */
 439 template<
 440     class SyncReadStream,
 441     class DynamicBuffer,
 442     bool isRequest, class Derived>
 443 std::size_t
 444 read(
 445     SyncReadStream& stream,
 446     DynamicBuffer& buffer,
 447     basic_parser<isRequest, Derived>& parser);
 448
 449 /** Read a complete message from a stream using a parser.
 450
 451     This function is used to read a complete message from a stream into a
 452     subclass of @ref basic_parser.
 453     The call will block until one of the following conditions is true:
 454
 455     @li @ref basic_parser::is_done returns `true`
 456
 457     @li An error occurs.
 458
 459     This operation is implemented in terms of one or
 460     more calls to the stream's `read_some` function.
 461     The implementation may read additional octets that lie past the
 462     end of the message being read. This additional data is stored
 463     in the dynamic buffer, which must be retained for subsequent reads.
 464
 465     If the stream returns the error `boost::asio::error::eof` indicating the
 466     end of file during a read, the error returned from this function will be:
 467
 468     @li @ref error::end_of_stream if no octets were parsed, or
 469
 470     @li @ref error::partial_message if any octets were parsed but the
 471     message was incomplete, otherwise:
 472
 473     @li A successful result. A subsequent attempt to read will
 474     return @ref error::end_of_stream
 475
 476     @param stream The stream from which the data is to be read.
 477     The type must support the @b SyncReadStream concept.
 478
 479     @param buffer A @b DynamicBuffer holding additional bytes
 480     read by the implementation from the stream. This is both
 481     an input and an output parameter; on entry, any data in the
 482     dynamic buffer's input sequence will be given to the parser
 483     first.
 484
 485     @param parser The parser to use.
 486
 487     @param ec Set to the error, if any occurred.
 488
 489     @return The number of bytes transferred to the parser.
 490
 491     @note The implementation will call @ref basic_parser::eager
 492     with the value `true` on the parser passed in.
 493 */
 494 template<
 495     class SyncReadStream,
 496     class DynamicBuffer,
 497     bool isRequest, class Derived>
 498 std::size_t
 499 read(
 500     SyncReadStream& stream,
 501     DynamicBuffer& buffer,
 502     basic_parser<isRequest, Derived>& parser,
 503     error_code& ec);
 504
 505 /** Read a complete message from a stream asynchronously using a parser.
 506
 507     This function is used to asynchronously read a complete message from a
 508     stream into a subclass of @ref basic_parser.
 509     The function call always returns immediately. The asynchronous operation
 510     will continue until one of the following conditions is true:
 511
 512     @li @ref basic_parser::is_done returns `true`
 513
 514     @li An error occurs.
 515
 516     This operation is implemented in terms of one or more calls to
 517     the stream's `async_read_some` function, and is known as a
 518     <em>composed operation</em>. The program must ensure that the
 519     stream performs no other reads until this operation completes.
 520     The implementation may read additional octets that lie past the
 521     end of the message being read. This additional data is stored
 522     in the dynamic buffer, which must be retained for subsequent reads.
 523
 524     If the stream returns the error `boost::asio::error::eof` indicating the
 525     end of file during a read, the error returned from this function will be:
 526
 527     @li @ref error::end_of_stream if no octets were parsed, or
 528
 529     @li @ref error::partial_message if any octets were parsed but the
 530     message was incomplete, otherwise:
 531
 532     @li A successful result. A subsequent attempt to read will
 533     return @ref error::end_of_stream
 534
 535     @param stream The stream from which the data is to be read.
 536     The type must support the @b AsyncReadStream concept.
 537
 538     @param buffer A @b DynamicBuffer holding additional bytes
 539     read by the implementation from the stream. This is both
 540     an input and an output parameter; on entry, any data in the
 541     dynamic buffer's input sequence will be given to the parser
 542     first.
 543
 544     @param parser The parser to use.
 545     The object must remain valid at least until the
 546     handler is called; ownership is not transferred.
 547
 548     @param handler The handler to be called when the request
 549     completes. Copies will be made of the handler as required.
 550     The equivalent function signature of the handler must be:
 551     @code void handler(
 552         error_code const& error,        // result of operation,
 553         std::size_t bytes_transferred   // the number of bytes transferred to the parser
 554     ); @endcode
 555     Regardless of whether the asynchronous operation completes
 556     immediately or not, the handler will not be invoked from within
 557     this function. Invocation of the handler will be performed in a
 558     manner equivalent to using `boost::asio::io_context::post`.
 559
 560     @note The implementation will call @ref basic_parser::eager
 561     with the value `true` on the parser passed in.
 562 */
 563 template<
 564     class AsyncReadStream,
 565     class DynamicBuffer,
 566     bool isRequest, class Derived,
 567     class ReadHandler>
 568 BOOST_ASIO_INITFN_RESULT_TYPE(
 569     ReadHandler, void(error_code, std::size_t))
 570 async_read(
 571     AsyncReadStream& stream,
 572     DynamicBuffer& buffer,
 573     basic_parser<isRequest, Derived>& parser,
 574     ReadHandler&& handler);
 575
 576 //------------------------------------------------------------------------------
 577
 578 /** Read a complete message from a stream.
 579
 580     This function is used to read a complete message from a stream using HTTP/1.
 581     The call will block until one of the following conditions is true:
 582
 583     @li The entire message is read.
 584
 585     @li An error occurs.
 586
 587     This operation is implemented in terms of one or
 588     more calls to the stream's `read_some` function.
 589     The implementation may read additional octets that lie past the
 590     end of the message being read. This additional data is stored
 591     in the dynamic buffer, which must be retained for subsequent reads.
 592
 593     If the stream returns the error `boost::asio::error::eof` indicating the
 594     end of file during a read, the error returned from this function will be:
 595
 596     @li @ref error::end_of_stream if no octets were parsed, or
 597
 598     @li @ref error::partial_message if any octets were parsed but the
 599     message was incomplete, otherwise:
 600
 601     @li A successful result. A subsequent attempt to read will
 602     return @ref error::end_of_stream
 603
 604     @param stream The stream from which the data is to be read.
 605     The type must support the @b SyncReadStream concept.
 606
 607     @param buffer A @b DynamicBuffer holding additional bytes
 608     read by the implementation from the stream. This is both
 609     an input and an output parameter; on entry, any data in the
 610     dynamic buffer's input sequence will be given to the parser
 611     first.
 612
 613     @param msg An object in which to store the message contents.
 614     This object should not have previous contents, otherwise
 615     the behavior is undefined.
 616     The type must be @b MoveAssignable and @b MoveConstructible.
 617
 618     @return The number of bytes transferred to the parser.
 619
 620     @throws system_error Thrown on failure.
 621 */
 622 template<
 623     class SyncReadStream,
 624     class DynamicBuffer,
 625     bool isRequest, class Body, class Allocator>
 626 std::size_t
 627 read(
 628     SyncReadStream& stream,
 629     DynamicBuffer& buffer,
 630     message<isRequest, Body, basic_fields<Allocator>>& msg);
 631
 632 /** Read a complete message from a stream.
 633
 634     This function is used to read a complete message from a stream using HTTP/1.
 635     The call will block until one of the following conditions is true:
 636
 637     @li The entire message is read.
 638
 639     @li An error occurs.
 640
 641     This operation is implemented in terms of one or
 642     more calls to the stream's `read_some` function.
 643     The implementation may read additional octets that lie past the
 644     end of the message being read. This additional data is stored
 645     in the dynamic buffer, which must be retained for subsequent reads.
 646
 647     If the stream returns the error `boost::asio::error::eof` indicating the
 648     end of file during a read, the error returned from this function will be:
 649
 650     @li @ref error::end_of_stream if no octets were parsed, or
 651
 652     @li @ref error::partial_message if any octets were parsed but the
 653     message was incomplete, otherwise:
 654
 655     @li A successful result. A subsequent attempt to read will
 656     return @ref error::end_of_stream
 657
 658     @param stream The stream from which the data is to be read.
 659     The type must support the @b SyncReadStream concept.
 660
 661     @param buffer A @b DynamicBuffer holding additional bytes
 662     read by the implementation from the stream. This is both
 663     an input and an output parameter; on entry, any data in the
 664     dynamic buffer's input sequence will be given to the parser
 665     first.
 666
 667     @param msg An object in which to store the message contents.
 668     This object should not have previous contents, otherwise
 669     the behavior is undefined.
 670     The type must be @b MoveAssignable and @b MoveConstructible.
 671
 672     @param ec Set to the error, if any occurred.
 673
 674     @return The number of bytes transferred to the parser.
 675 */
 676 template<
 677     class SyncReadStream,
 678     class DynamicBuffer,
 679     bool isRequest, class Body, class Allocator>
 680 std::size_t
 681 read(
 682     SyncReadStream& stream,
 683     DynamicBuffer& buffer,
 684     message<isRequest, Body, basic_fields<Allocator>>& msg,
 685     error_code& ec);
 686
 687 /** Read a complete message from a stream asynchronously.
 688
 689     This function is used to asynchronously read a complete message from a
 690     stream using HTTP/1.
 691     The function call always returns immediately. The asynchronous operation
 692     will continue until one of the following conditions is true:
 693
 694     @li The entire message is read.
 695
 696     @li An error occurs.
 697
 698     This operation is implemented in terms of one or more calls to
 699     the stream's `async_read_some` function, and is known as a
 700     <em>composed operation</em>. The program must ensure that the
 701     stream performs no other reads until this operation completes.
 702     The implementation may read additional octets that lie past the
 703     end of the message being read. This additional data is stored
 704     in the dynamic buffer, which must be retained for subsequent reads.
 705
 706     If the stream returns the error `boost::asio::error::eof` indicating the
 707     end of file during a read, the error returned from this function will be:
 708
 709     @li @ref error::end_of_stream if no octets were parsed, or
 710
 711     @li @ref error::partial_message if any octets were parsed but the
 712     message was incomplete, otherwise:
 713
 714     @li A successful result. A subsequent attempt to read will
 715     return @ref error::end_of_stream
 716
 717     @param stream The stream from which the data is to be read.
 718     The type must support the @b AsyncReadStream concept.
 719
 720     @param buffer A @b DynamicBuffer holding additional bytes
 721     read by the implementation from the stream. This is both
 722     an input and an output parameter; on entry, any data in the
 723     dynamic buffer's input sequence will be given to the parser
 724     first.
 725
 726     @param msg An object in which to store the message contents.
 727     This object should not have previous contents, otherwise
 728     the behavior is undefined.
 729     The type must be @b MoveAssignable and @b MoveConstructible.
 730
 731     The object must remain valid at least until the
 732     handler is called; ownership is not transferred.
 733
 734     @param handler The handler to be called when the operation
 735     completes. Copies will be made of the handler as required.
 736     The equivalent function signature of the handler must be:
 737     @code void handler(
 738         error_code const& error,        // result of operation,
 739         std::size_t bytes_transferred   // the number of bytes transferred to the parser
 740     ); @endcode
 741     Regardless of whether the asynchronous operation completes
 742     immediately or not, the handler will not be invoked from within
 743     this function. Invocation of the handler will be performed in a
 744     manner equivalent to using `boost::asio::io_context::post`.
 745 */
 746 template<
 747     class AsyncReadStream,
 748     class DynamicBuffer,
 749     bool isRequest, class Body, class Allocator,
 750     class ReadHandler>
 751 BOOST_ASIO_INITFN_RESULT_TYPE(
 752     ReadHandler, void(error_code, std::size_t))
 753 async_read(
 754     AsyncReadStream& stream,
 755     DynamicBuffer& buffer,
 756     message<isRequest, Body, basic_fields<Allocator>>& msg,
 757     ReadHandler&& handler);
 758
 759 } // http
 760 } // beast
 761 } // boost
 762
 763 #include <boost/beast/http/impl/read.ipp>
 764
 765 #endif