ceph/src/boost/boost/asio/basic_serial_port.hpp

   1 //
   2 // basic_serial_port.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 // Copyright (c) 2008 Rep Invariant Systems, Inc. (info@repinvariant.com)
   7 //
   8 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   9 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  10 //
  11
  12 #ifndef BOOST_ASIO_BASIC_SERIAL_PORT_HPP
  13 #define BOOST_ASIO_BASIC_SERIAL_PORT_HPP
  14
  15 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  16 # pragma once
  17 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  18
  19 #include <boost/asio/detail/config.hpp>
  20
  21 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  22
  23 #if defined(BOOST_ASIO_HAS_SERIAL_PORT) \
  24   || defined(GENERATING_DOCUMENTATION)
  25
  26 #include <string>
  27 #include <boost/asio/basic_io_object.hpp>
  28 #include <boost/asio/detail/handler_type_requirements.hpp>
  29 #include <boost/asio/detail/throw_error.hpp>
  30 #include <boost/asio/error.hpp>
  31 #include <boost/asio/serial_port_base.hpp>
  32 #include <boost/asio/serial_port_service.hpp>
  33
  34 #include <boost/asio/detail/push_options.hpp>
  35
  36 namespace boost {
  37 namespace asio {
  38
  39 /// Provides serial port functionality.
  40 /**
  41  * The basic_serial_port class template provides functionality that is common
  42  * to all serial ports.
  43  *
  44  * @par Thread Safety
  45  * @e Distinct @e objects: Safe.@n
  46  * @e Shared @e objects: Unsafe.
  47  */
  48 template <typename SerialPortService = serial_port_service>
  49 class basic_serial_port
  50   : public basic_io_object<SerialPortService>,
  51     public serial_port_base
  52 {
  53 public:
  54   /// The native representation of a serial port.
  55   typedef typename SerialPortService::native_handle_type native_handle_type;
  56
  57   /// A basic_serial_port is always the lowest layer.
  58   typedef basic_serial_port<SerialPortService> lowest_layer_type;
  59
  60   /// Construct a basic_serial_port without opening it.
  61   /**
  62    * This constructor creates a serial port without opening it.
  63    *
  64    * @param io_context The io_context object that the serial port will use to
  65    * dispatch handlers for any asynchronous operations performed on the port.
  66    */
  67   explicit basic_serial_port(boost::asio::io_context& io_context)
  68     : basic_io_object<SerialPortService>(io_context)
  69   {
  70   }
  71
  72   /// Construct and open a basic_serial_port.
  73   /**
  74    * This constructor creates and opens a serial port for the specified device
  75    * name.
  76    *
  77    * @param io_context The io_context object that the serial port will use to
  78    * dispatch handlers for any asynchronous operations performed on the port.
  79    *
  80    * @param device The platform-specific device name for this serial
  81    * port.
  82    */
  83   explicit basic_serial_port(boost::asio::io_context& io_context,
  84       const char* device)
  85     : basic_io_object<SerialPortService>(io_context)
  86   {
  87     boost::system::error_code ec;
  88     this->get_service().open(this->get_implementation(), device, ec);
  89     boost::asio::detail::throw_error(ec, "open");
  90   }
  91
  92   /// Construct and open a basic_serial_port.
  93   /**
  94    * This constructor creates and opens a serial port for the specified device
  95    * name.
  96    *
  97    * @param io_context The io_context object that the serial port will use to
  98    * dispatch handlers for any asynchronous operations performed on the port.
  99    *
 100    * @param device The platform-specific device name for this serial
 101    * port.
 102    */
 103   explicit basic_serial_port(boost::asio::io_context& io_context,
 104       const std::string& device)
 105     : basic_io_object<SerialPortService>(io_context)
 106   {
 107     boost::system::error_code ec;
 108     this->get_service().open(this->get_implementation(), device, ec);
 109     boost::asio::detail::throw_error(ec, "open");
 110   }
 111
 112   /// Construct a basic_serial_port on an existing native serial port.
 113   /**
 114    * This constructor creates a serial port object to hold an existing native
 115    * serial port.
 116    *
 117    * @param io_context The io_context object that the serial port will use to
 118    * dispatch handlers for any asynchronous operations performed on the port.
 119    *
 120    * @param native_serial_port A native serial port.
 121    *
 122    * @throws boost::system::system_error Thrown on failure.
 123    */
 124   basic_serial_port(boost::asio::io_context& io_context,
 125       const native_handle_type& native_serial_port)
 126     : basic_io_object<SerialPortService>(io_context)
 127   {
 128     boost::system::error_code ec;
 129     this->get_service().assign(this->get_implementation(),
 130         native_serial_port, ec);
 131     boost::asio::detail::throw_error(ec, "assign");
 132   }
 133
 134 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 135   /// Move-construct a basic_serial_port from another.
 136   /**
 137    * This constructor moves a serial port from one object to another.
 138    *
 139    * @param other The other basic_serial_port object from which the move will
 140    * occur.
 141    *
 142    * @note Following the move, the moved-from object is in the same state as if
 143    * constructed using the @c basic_serial_port(io_context&) constructor.
 144    */
 145   basic_serial_port(basic_serial_port&& other)
 146     : basic_io_object<SerialPortService>(
 147         BOOST_ASIO_MOVE_CAST(basic_serial_port)(other))
 148   {
 149   }
 150
 151   /// Move-assign a basic_serial_port from another.
 152   /**
 153    * This assignment operator moves a serial port from one object to another.
 154    *
 155    * @param other The other basic_serial_port object from which the move will
 156    * occur.
 157    *
 158    * @note Following the move, the moved-from object is in the same state as if
 159    * constructed using the @c basic_serial_port(io_context&) constructor.
 160    */
 161   basic_serial_port& operator=(basic_serial_port&& other)
 162   {
 163     basic_io_object<SerialPortService>::operator=(
 164         BOOST_ASIO_MOVE_CAST(basic_serial_port)(other));
 165     return *this;
 166   }
 167 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 168
 169   /// Get a reference to the lowest layer.
 170   /**
 171    * This function returns a reference to the lowest layer in a stack of
 172    * layers. Since a basic_serial_port cannot contain any further layers, it
 173    * simply returns a reference to itself.
 174    *
 175    * @return A reference to the lowest layer in the stack of layers. Ownership
 176    * is not transferred to the caller.
 177    */
 178   lowest_layer_type& lowest_layer()
 179   {
 180     return *this;
 181   }
 182
 183   /// Get a const reference to the lowest layer.
 184   /**
 185    * This function returns a const reference to the lowest layer in a stack of
 186    * layers. Since a basic_serial_port cannot contain any further layers, it
 187    * simply returns a reference to itself.
 188    *
 189    * @return A const reference to the lowest layer in the stack of layers.
 190    * Ownership is not transferred to the caller.
 191    */
 192   const lowest_layer_type& lowest_layer() const
 193   {
 194     return *this;
 195   }
 196
 197   /// Open the serial port using the specified device name.
 198   /**
 199    * This function opens the serial port for the specified device name.
 200    *
 201    * @param device The platform-specific device name.
 202    *
 203    * @throws boost::system::system_error Thrown on failure.
 204    */
 205   void open(const std::string& device)
 206   {
 207     boost::system::error_code ec;
 208     this->get_service().open(this->get_implementation(), device, ec);
 209     boost::asio::detail::throw_error(ec, "open");
 210   }
 211
 212   /// Open the serial port using the specified device name.
 213   /**
 214    * This function opens the serial port using the given platform-specific
 215    * device name.
 216    *
 217    * @param device The platform-specific device name.
 218    *
 219    * @param ec Set the indicate what error occurred, if any.
 220    */
 221   BOOST_ASIO_SYNC_OP_VOID open(const std::string& device,
 222       boost::system::error_code& ec)
 223   {
 224     this->get_service().open(this->get_implementation(), device, ec);
 225     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 226   }
 227
 228   /// Assign an existing native serial port to the serial port.
 229   /*
 230    * This function opens the serial port to hold an existing native serial port.
 231    *
 232    * @param native_serial_port A native serial port.
 233    *
 234    * @throws boost::system::system_error Thrown on failure.
 235    */
 236   void assign(const native_handle_type& native_serial_port)
 237   {
 238     boost::system::error_code ec;
 239     this->get_service().assign(this->get_implementation(),
 240         native_serial_port, ec);
 241     boost::asio::detail::throw_error(ec, "assign");
 242   }
 243
 244   /// Assign an existing native serial port to the serial port.
 245   /*
 246    * This function opens the serial port to hold an existing native serial port.
 247    *
 248    * @param native_serial_port A native serial port.
 249    *
 250    * @param ec Set to indicate what error occurred, if any.
 251    */
 252   BOOST_ASIO_SYNC_OP_VOID assign(const native_handle_type& native_serial_port,
 253       boost::system::error_code& ec)
 254   {
 255     this->get_service().assign(this->get_implementation(),
 256         native_serial_port, ec);
 257     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 258   }
 259
 260   /// Determine whether the serial port is open.
 261   bool is_open() const
 262   {
 263     return this->get_service().is_open(this->get_implementation());
 264   }
 265
 266   /// Close the serial port.
 267   /**
 268    * This function is used to close the serial port. Any asynchronous read or
 269    * write operations will be cancelled immediately, and will complete with the
 270    * boost::asio::error::operation_aborted error.
 271    *
 272    * @throws boost::system::system_error Thrown on failure.
 273    */
 274   void close()
 275   {
 276     boost::system::error_code ec;
 277     this->get_service().close(this->get_implementation(), ec);
 278     boost::asio::detail::throw_error(ec, "close");
 279   }
 280
 281   /// Close the serial port.
 282   /**
 283    * This function is used to close the serial port. Any asynchronous read or
 284    * write operations will be cancelled immediately, and will complete with the
 285    * boost::asio::error::operation_aborted error.
 286    *
 287    * @param ec Set to indicate what error occurred, if any.
 288    */
 289   BOOST_ASIO_SYNC_OP_VOID close(boost::system::error_code& ec)
 290   {
 291     this->get_service().close(this->get_implementation(), ec);
 292     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 293   }
 294
 295   /// Get the native serial port representation.
 296   /**
 297    * This function may be used to obtain the underlying representation of the
 298    * serial port. This is intended to allow access to native serial port
 299    * functionality that is not otherwise provided.
 300    */
 301   native_handle_type native_handle()
 302   {
 303     return this->get_service().native_handle(this->get_implementation());
 304   }
 305
 306   /// Cancel all asynchronous operations associated with the serial port.
 307   /**
 308    * This function causes all outstanding asynchronous read or write operations
 309    * to finish immediately, and the handlers for cancelled operations will be
 310    * passed the boost::asio::error::operation_aborted error.
 311    *
 312    * @throws boost::system::system_error Thrown on failure.
 313    */
 314   void cancel()
 315   {
 316     boost::system::error_code ec;
 317     this->get_service().cancel(this->get_implementation(), ec);
 318     boost::asio::detail::throw_error(ec, "cancel");
 319   }
 320
 321   /// Cancel all asynchronous operations associated with the serial port.
 322   /**
 323    * This function causes all outstanding asynchronous read or write operations
 324    * to finish immediately, and the handlers for cancelled operations will be
 325    * passed the boost::asio::error::operation_aborted error.
 326    *
 327    * @param ec Set to indicate what error occurred, if any.
 328    */
 329   BOOST_ASIO_SYNC_OP_VOID cancel(boost::system::error_code& ec)
 330   {
 331     this->get_service().cancel(this->get_implementation(), ec);
 332     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 333   }
 334
 335   /// Send a break sequence to the serial port.
 336   /**
 337    * This function causes a break sequence of platform-specific duration to be
 338    * sent out the serial port.
 339    *
 340    * @throws boost::system::system_error Thrown on failure.
 341    */
 342   void send_break()
 343   {
 344     boost::system::error_code ec;
 345     this->get_service().send_break(this->get_implementation(), ec);
 346     boost::asio::detail::throw_error(ec, "send_break");
 347   }
 348
 349   /// Send a break sequence to the serial port.
 350   /**
 351    * This function causes a break sequence of platform-specific duration to be
 352    * sent out the serial port.
 353    *
 354    * @param ec Set to indicate what error occurred, if any.
 355    */
 356   BOOST_ASIO_SYNC_OP_VOID send_break(boost::system::error_code& ec)
 357   {
 358     this->get_service().send_break(this->get_implementation(), ec);
 359     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 360   }
 361
 362   /// Set an option on the serial port.
 363   /**
 364    * This function is used to set an option on the serial port.
 365    *
 366    * @param option The option value to be set on the serial port.
 367    *
 368    * @throws boost::system::system_error Thrown on failure.
 369    *
 370    * @sa SettableSerialPortOption @n
 371    * boost::asio::serial_port_base::baud_rate @n
 372    * boost::asio::serial_port_base::flow_control @n
 373    * boost::asio::serial_port_base::parity @n
 374    * boost::asio::serial_port_base::stop_bits @n
 375    * boost::asio::serial_port_base::character_size
 376    */
 377   template <typename SettableSerialPortOption>
 378   void set_option(const SettableSerialPortOption& option)
 379   {
 380     boost::system::error_code ec;
 381     this->get_service().set_option(this->get_implementation(), option, ec);
 382     boost::asio::detail::throw_error(ec, "set_option");
 383   }
 384
 385   /// Set an option on the serial port.
 386   /**
 387    * This function is used to set an option on the serial port.
 388    *
 389    * @param option The option value to be set on the serial port.
 390    *
 391    * @param ec Set to indicate what error occurred, if any.
 392    *
 393    * @sa SettableSerialPortOption @n
 394    * boost::asio::serial_port_base::baud_rate @n
 395    * boost::asio::serial_port_base::flow_control @n
 396    * boost::asio::serial_port_base::parity @n
 397    * boost::asio::serial_port_base::stop_bits @n
 398    * boost::asio::serial_port_base::character_size
 399    */
 400   template <typename SettableSerialPortOption>
 401   BOOST_ASIO_SYNC_OP_VOID set_option(const SettableSerialPortOption& option,
 402       boost::system::error_code& ec)
 403   {
 404     this->get_service().set_option(this->get_implementation(), option, ec);
 405     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 406   }
 407
 408   /// Get an option from the serial port.
 409   /**
 410    * This function is used to get the current value of an option on the serial
 411    * port.
 412    *
 413    * @param option The option value to be obtained from the serial port.
 414    *
 415    * @throws boost::system::system_error Thrown on failure.
 416    *
 417    * @sa GettableSerialPortOption @n
 418    * boost::asio::serial_port_base::baud_rate @n
 419    * boost::asio::serial_port_base::flow_control @n
 420    * boost::asio::serial_port_base::parity @n
 421    * boost::asio::serial_port_base::stop_bits @n
 422    * boost::asio::serial_port_base::character_size
 423    */
 424   template <typename GettableSerialPortOption>
 425   void get_option(GettableSerialPortOption& option)
 426   {
 427     boost::system::error_code ec;
 428     this->get_service().get_option(this->get_implementation(), option, ec);
 429     boost::asio::detail::throw_error(ec, "get_option");
 430   }
 431
 432   /// Get an option from the serial port.
 433   /**
 434    * This function is used to get the current value of an option on the serial
 435    * port.
 436    *
 437    * @param option The option value to be obtained from the serial port.
 438    *
 439    * @param ec Set to indicate what error occurred, if any.
 440    *
 441    * @sa GettableSerialPortOption @n
 442    * boost::asio::serial_port_base::baud_rate @n
 443    * boost::asio::serial_port_base::flow_control @n
 444    * boost::asio::serial_port_base::parity @n
 445    * boost::asio::serial_port_base::stop_bits @n
 446    * boost::asio::serial_port_base::character_size
 447    */
 448   template <typename GettableSerialPortOption>
 449   BOOST_ASIO_SYNC_OP_VOID get_option(GettableSerialPortOption& option,
 450       boost::system::error_code& ec)
 451   {
 452     this->get_service().get_option(this->get_implementation(), option, ec);
 453     BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
 454   }
 455
 456   /// Write some data to the serial port.
 457   /**
 458    * This function is used to write data to the serial port. The function call
 459    * will block until one or more bytes of the data has been written
 460    * successfully, or until an error occurs.
 461    *
 462    * @param buffers One or more data buffers to be written to the serial port.
 463    *
 464    * @returns The number of bytes written.
 465    *
 466    * @throws boost::system::system_error Thrown on failure. An error code of
 467    * boost::asio::error::eof indicates that the connection was closed by the
 468    * peer.
 469    *
 470    * @note The write_some operation may not transmit all of the data to the
 471    * peer. Consider using the @ref write function if you need to ensure that
 472    * all data is written before the blocking operation completes.
 473    *
 474    * @par Example
 475    * To write a single data buffer use the @ref buffer function as follows:
 476    * @code
 477    * serial_port.write_some(boost::asio::buffer(data, size));
 478    * @endcode
 479    * See the @ref buffer documentation for information on writing multiple
 480    * buffers in one go, and how to use it with arrays, boost::array or
 481    * std::vector.
 482    */
 483   template <typename ConstBufferSequence>
 484   std::size_t write_some(const ConstBufferSequence& buffers)
 485   {
 486     boost::system::error_code ec;
 487     std::size_t s = this->get_service().write_some(
 488         this->get_implementation(), buffers, ec);
 489     boost::asio::detail::throw_error(ec, "write_some");
 490     return s;
 491   }
 492
 493   /// Write some data to the serial port.
 494   /**
 495    * This function is used to write data to the serial port. The function call
 496    * will block until one or more bytes of the data has been written
 497    * successfully, or until an error occurs.
 498    *
 499    * @param buffers One or more data buffers to be written to the serial port.
 500    *
 501    * @param ec Set to indicate what error occurred, if any.
 502    *
 503    * @returns The number of bytes written. Returns 0 if an error occurred.
 504    *
 505    * @note The write_some operation may not transmit all of the data to the
 506    * peer. Consider using the @ref write function if you need to ensure that
 507    * all data is written before the blocking operation completes.
 508    */
 509   template <typename ConstBufferSequence>
 510   std::size_t write_some(const ConstBufferSequence& buffers,
 511       boost::system::error_code& ec)
 512   {
 513     return this->get_service().write_some(
 514         this->get_implementation(), buffers, ec);
 515   }
 516
 517   /// Start an asynchronous write.
 518   /**
 519    * This function is used to asynchronously write data to the serial port.
 520    * The function call always returns immediately.
 521    *
 522    * @param buffers One or more data buffers to be written to the serial port.
 523    * Although the buffers object may be copied as necessary, ownership of the
 524    * underlying memory blocks is retained by the caller, which must guarantee
 525    * that they remain valid until the handler is called.
 526    *
 527    * @param handler The handler to be called when the write operation completes.
 528    * Copies will be made of the handler as required. The function signature of
 529    * the handler must be:
 530    * @code void handler(
 531    *   const boost::system::error_code& error, // Result of operation.
 532    *   std::size_t bytes_transferred           // Number of bytes written.
 533    * ); @endcode
 534    * Regardless of whether the asynchronous operation completes immediately or
 535    * not, the handler will not be invoked from within this function. Invocation
 536    * of the handler will be performed in a manner equivalent to using
 537    * boost::asio::io_context::post().
 538    *
 539    * @note The write operation may not transmit all of the data to the peer.
 540    * Consider using the @ref async_write function if you need to ensure that all
 541    * data is written before the asynchronous operation completes.
 542    *
 543    * @par Example
 544    * To write a single data buffer use the @ref buffer function as follows:
 545    * @code
 546    * serial_port.async_write_some(boost::asio::buffer(data, size), handler);
 547    * @endcode
 548    * See the @ref buffer documentation for information on writing multiple
 549    * buffers in one go, and how to use it with arrays, boost::array or
 550    * std::vector.
 551    */
 552   template <typename ConstBufferSequence, typename WriteHandler>
 553   BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 554       void (boost::system::error_code, std::size_t))
 555   async_write_some(const ConstBufferSequence& buffers,
 556       BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
 557   {
 558     // If you get an error on the following line it means that your handler does
 559     // not meet the documented type requirements for a WriteHandler.
 560     BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
 561
 562     return this->get_service().async_write_some(this->get_implementation(),
 563         buffers, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
 564   }
 565
 566   /// Read some data from the serial port.
 567   /**
 568    * This function is used to read data from the serial port. The function
 569    * call will block until one or more bytes of data has been read successfully,
 570    * or until an error occurs.
 571    *
 572    * @param buffers One or more buffers into which the data will be read.
 573    *
 574    * @returns The number of bytes read.
 575    *
 576    * @throws boost::system::system_error Thrown on failure. An error code of
 577    * boost::asio::error::eof indicates that the connection was closed by the
 578    * peer.
 579    *
 580    * @note The read_some operation may not read all of the requested number of
 581    * bytes. Consider using the @ref read function if you need to ensure that
 582    * the requested amount of data is read before the blocking operation
 583    * completes.
 584    *
 585    * @par Example
 586    * To read into a single data buffer use the @ref buffer function as follows:
 587    * @code
 588    * serial_port.read_some(boost::asio::buffer(data, size));
 589    * @endcode
 590    * See the @ref buffer documentation for information on reading into multiple
 591    * buffers in one go, and how to use it with arrays, boost::array or
 592    * std::vector.
 593    */
 594   template <typename MutableBufferSequence>
 595   std::size_t read_some(const MutableBufferSequence& buffers)
 596   {
 597     boost::system::error_code ec;
 598     std::size_t s = this->get_service().read_some(
 599         this->get_implementation(), buffers, ec);
 600     boost::asio::detail::throw_error(ec, "read_some");
 601     return s;
 602   }
 603
 604   /// Read some data from the serial port.
 605   /**
 606    * This function is used to read data from the serial port. The function
 607    * call will block until one or more bytes of data has been read successfully,
 608    * or until an error occurs.
 609    *
 610    * @param buffers One or more buffers into which the data will be read.
 611    *
 612    * @param ec Set to indicate what error occurred, if any.
 613    *
 614    * @returns The number of bytes read. Returns 0 if an error occurred.
 615    *
 616    * @note The read_some operation may not read all of the requested number of
 617    * bytes. Consider using the @ref read function if you need to ensure that
 618    * the requested amount of data is read before the blocking operation
 619    * completes.
 620    */
 621   template <typename MutableBufferSequence>
 622   std::size_t read_some(const MutableBufferSequence& buffers,
 623       boost::system::error_code& ec)
 624   {
 625     return this->get_service().read_some(
 626         this->get_implementation(), buffers, ec);
 627   }
 628
 629   /// Start an asynchronous read.
 630   /**
 631    * This function is used to asynchronously read data from the serial port.
 632    * The function call always returns immediately.
 633    *
 634    * @param buffers One or more buffers into which the data will be read.
 635    * Although the buffers object may be copied as necessary, ownership of the
 636    * underlying memory blocks is retained by the caller, which must guarantee
 637    * that they remain valid until the handler is called.
 638    *
 639    * @param handler The handler to be called when the read operation completes.
 640    * Copies will be made of the handler as required. The function signature of
 641    * the handler must be:
 642    * @code void handler(
 643    *   const boost::system::error_code& error, // Result of operation.
 644    *   std::size_t bytes_transferred           // Number of bytes read.
 645    * ); @endcode
 646    * Regardless of whether the asynchronous operation completes immediately or
 647    * not, the handler will not be invoked from within this function. Invocation
 648    * of the handler will be performed in a manner equivalent to using
 649    * boost::asio::io_context::post().
 650    *
 651    * @note The read operation may not read all of the requested number of bytes.
 652    * Consider using the @ref async_read function if you need to ensure that the
 653    * requested amount of data is read before the asynchronous operation
 654    * completes.
 655    *
 656    * @par Example
 657    * To read into a single data buffer use the @ref buffer function as follows:
 658    * @code
 659    * serial_port.async_read_some(boost::asio::buffer(data, size), handler);
 660    * @endcode
 661    * See the @ref buffer documentation for information on reading into multiple
 662    * buffers in one go, and how to use it with arrays, boost::array or
 663    * std::vector.
 664    */
 665   template <typename MutableBufferSequence, typename ReadHandler>
 666   BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 667       void (boost::system::error_code, std::size_t))
 668   async_read_some(const MutableBufferSequence& buffers,
 669       BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
 670   {
 671     // If you get an error on the following line it means that your handler does
 672     // not meet the documented type requirements for a ReadHandler.
 673     BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
 674
 675     return this->get_service().async_read_some(this->get_implementation(),
 676         buffers, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
 677   }
 678 };
 679
 680 } // namespace asio
 681 } // namespace boost
 682
 683 #include <boost/asio/detail/pop_options.hpp>
 684
 685 #endif // defined(BOOST_ASIO_HAS_SERIAL_PORT)
 686        //   || defined(GENERATING_DOCUMENTATION)
 687
 688 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 689
 690 #endif // BOOST_ASIO_BASIC_SERIAL_PORT_HPP