ceph/src/boost/boost/asio/serial_port.hpp

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