Best Documentation for Boost:Asio

Best documentation for Boost:asio?

First, I've been using Boost.Asio for quite a while already -- and I share your concern. To address your question:

• There really is very scarce documentation about Boost.Asio aside from the introduction and tutorial. I am not the author, but this is mostly because there are just too many things to document for something as low-level as an Asynchronous IO Library.
• The examples give more away than the tutorials do. If you don't mind spending a little time looking at the different examples, I would think they should suffice to get you started. If you want to run away with it, then the reference documentation should help you a lot.
• Ask around in the Boost Users and Boost Developers mailing list if you're really stuck or looking for specific guidance. I'm pretty sure a lot of people will be willing to address your concerns on the mailing lists.

There are efforts (not part of Boost.Asio) to expose a lot of the functionality and possible alternative use cases. This at best is scattered around the web in blogs and other forms of non-packaged documentation.

One thing that is unclear and which will really need close coordination with the author and developers of the Boost.Asio library would be as far as extending and customizing it for a specific platform or adding specific new functionality. This should be improved though but the good thing is it's looking like Asio will be a reference implementation for a standard library technical report (for an asynchronous IO library in the STL) in the future.

Boost asio architecture document

Here are some slides from a presentation by Michael Caisse at BoostCon 2010: Getting Started with ASIO

Here is the video of Michael giving that presentation, although the slides are easy to follow without watching the video: Michael Caisse: An Asio Based Flash XML Server

For more general information on the design, read up on the Proactor pattern

How to use Boost.Asio c++?

How you use it depends on what you want to do, ;-).

The documentation is found here:

http://www.boost.org/doc/libs/1_46_1/doc/html/boost_asio.html

You will find lots of examples that should suite your needs.

For building, you should note that the library dependancies depend upon whether you are running on windows or linux. See here

http://www.boost.org/doc/libs/1_46_1/doc/html/boost_asio/using.html

In particular:

With MSVC or Borland C++ you may want
to add -DBOOST_DATE_TIME_NO_LIB and
-DBOOST_REGEX_NO_LIB to your project settings to disable autolinking of the
Boost.Date_Time and Boost.Regex
libraries respectively. Alternatively,
you may choose to build these
libraries and link to them

If you don't want the dependancies to the other boost libraries then you can use the non-boost (i think otherwise identical asio) library from here: http://think-async.com/

For sources of other documentation see this question on SO: Best documentation for Boost:asio?

As an example, to open a serial port you might write something like this:

/** Manage serial connections.*/
class serial_manager
{

  boost::asio::io_service m_io_service;
  std::string m_name;
  const unsigned int m_baud_rate;
  const enum flow_control::type m_flow_control;
  const enum parity::type m_parity;
  const enum stop_bits::type m_stop_bits;
  const unsigned int m_char_size;
  boost::asio::serial_port  m_SerialPort;
  boost::system::error_code m_error;
public:

  /** A constructor.
   *  @param name The dvice name, for example "COM1" (windows, or "/dev/ttyS0" (linux).
   *  @param baud_rate The baud rate. 
   *  @param flow_control The flow control. Acceptable values are flow_control::none, flow_control::software, flow_control::hardware.
   *  @param parity The parity of the connection. Acceptable values are parity::none, parity::even, parity::odd.
   *  @param stop_bits The number of stop bits. Acceptable values are stop_bits::one, stop_bits::one_point_five, stop::bits::two
   *  @param char_size The number of characters in connection.
   */
  serial_manager(const std::string& name, 
         const unsigned int& baud_rate  = 19200,
         const enum flow_control::type&   flow_control  = flow_control::none,
         const enum parity::type&         parity        = parity::none,
         const enum stop_bits::type&      stop_bits     = stop_bits::one,
         const unsigned int& char_size  = 8
         ) 
;
  void open();
};

void
serial_manager::open() {
  if (!m_SerialPort.is_open()) 
    {
      m_SerialPort.open(m_name, m_error);

     if (m_error == boost::system::errc::no_such_file_or_directory ) 
     {  //for example you tried to open "COM1" on a linux machine.
        //... handle the error somehow
     }

      m_SerialPort.set_option(boost::asio::serial_port::baud_rate(m_baud_rate));
      m_SerialPort.set_option(boost::asio::serial_port::flow_control(m_flow_control));
      m_SerialPort.set_option(boost::asio::serial_port::parity(m_parity));
      m_SerialPort.set_option(boost::asio::serial_port::stop_bits(m_stop_bits));
      m_SerialPort.set_option(boost::asio::serial_port::character_size(m_char_size));


    }
 }

Boost.Asio without Boost.System

AFAIR you can configure Boost System to be header-only

Source: http://www.boost.org/doc/libs/1_66_0/libs/system/doc/reference.html

Other than that, you might simply use Non-Boost Asio

Alternative of boost::asio::executor_work_guard for older boost version (1.57)

In older versions you'd use a io_service::work object:

boost::asio::io_service io;
boost::asio::work work(io);

Note that to get reset() like functionality you'd wrap that in boost::optional<> or std::unique_ptr<>

This is actually still in the documentation for the 1.57.0 version in the same place(s) where you'd find executor_work_guard in newer versions, e.g. https://www.boost.org/doc/libs/1_57_0/doc/html/boost_asio/reference/io_service.html#boost_asio.reference.io_service.stopping_the_io_service_from_running_out_of_work

Understanding boost::asio::post with single callable - who executes?

Eventually, boost::asio::post will use get_associated_executor to look up a specialization of associated_executor. The default implementation will provide a static instance of system_executor, where the object will be invoked.

Is it safe to call APIs of ASIO objects concurrently?

Look at the thread safety guarantees, which are documented with each class, but also in general https://www.boost.org/doc/libs/1_71_0/doc/html/boost_asio/overview/core/threads.html

This confirms that:

Q. Can I assume that a socket protects it's internal state, even if I invoke it from a background thread that does not invoke io_service.run()?

No you can not assume that, because it doesn't "protect it's internal state" in the sense you likely mean: it does not synchronize access to it.

Also, access from multiple threads running io_service handlers does no mean it's safe. You may need strands (either implicit or explicit) to ensure that.

Boost Asio message_flags

I searched for a while and finally tried to look in Boost's source code. I found this in socket_base.hpp:

  /// Bitmask type for flags that can be passed to send and receive operations.
  typedef int message_flags;

  #if defined(GENERATING_DOCUMENTATION)
  /// Peek at incoming data without removing it from the input queue.
  static const int message_peek = implementation_defined;

  /// Process out-of-band data.
  static const int message_out_of_band = implementation_defined;

  /// Specify that the data should not be subject to routing.
  static const int message_do_not_route = implementation_defined;

  /// Specifies that the data marks the end of a record.
  static const int message_end_of_record = implementation_defined;
  #else
  BOOST_ASIO_STATIC_CONSTANT(int,
      message_peek = BOOST_ASIO_OS_DEF(MSG_PEEK));
  BOOST_ASIO_STATIC_CONSTANT(int,
      message_out_of_band = BOOST_ASIO_OS_DEF(MSG_OOB));
  BOOST_ASIO_STATIC_CONSTANT(int,
      message_do_not_route = BOOST_ASIO_OS_DEF(MSG_DONTROUTE));
  BOOST_ASIO_STATIC_CONSTANT(int,
      message_end_of_record = BOOST_ASIO_OS_DEF(MSG_EOR));
  #endif

Based on this, it looks like message_peek, message_out_of_band, and message_do_not_route are the possible values. I'm going to give these a try and see if I can get them to work.

---

Related Topics