[Boost-bugs] [Boost C++ Libraries] #9023: asio::io_service::wrap() docs need an example

Subject: [Boost-bugs] [Boost C++ Libraries] #9023: asio::io_service::wrap() docs need an example
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2013-08-21 07:44:07

#9023: asio::io_service::wrap() docs need an example
------------------------------+----------------------------
 Reporter:  vinnie.falco@…    |      Owner:  chris_kohlhoff
     Type:  Feature Requests  |     Status:  new
Milestone:  To Be Determined  |  Component:  asio
  Version:  Boost 1.54.0      |   Severity:  Cosmetic
 Keywords:                    |
------------------------------+----------------------------
 The documentation for '''io_service::wrap''' reads:

 '''Return Value''' A function object that, when invoked, passes the
 wrapped handler to the '''io_service''' object's dispatch function. Given
 a function object with the signature:

 To say that this is cryptic would be an understatement. An example should
 be provided. One of the most common cases for calling
 '''io_service::wrap''' is when you want to post your own completion
 parameters for a given handler. For example, in your composed operation
 when an error occurs, you simply want to call the handler with the
 '''error_code'''.

 Here's an example from a piece of my own code. Note how the ReadHandler is
 posted to the '''io_service''' with a default-constructed '''error_code'''
 and '''bytes_transferred''' from the result of '''asio::buffer_copy''':

 {{{
     template <typename MutableBufferSequence, typename ReadHandler>
     BEAST_ASIO_INITFN_RESULT_TYPE(ReadHandler, void (error_code,
 std::size_t))
     async_read_some (MutableBufferSequence const& buffers,
         BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
     {
         using namespace boost;
         if (m_buffer.size () > 0)
         {
             std::size_t const bytes_transferred = asio::buffer_copy (
                 buffers, m_buffer.data ());
             return get_io_service ().wrap (
                 BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)) (
                     error_code (), bytes_transferred);
         }

         return m_next_layer.async_read_some (buffers,
             BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
     }
 }}}

 The addition of an example of a call to '''io_service::wrap''' would help
 illuminate this useful case.

-- 
Ticket URL: <https://svn.boost.org/trac/boost/ticket/9023>
Boost C++ Libraries <http://www.boost.org/>
Boost provides free peer-reviewed portable C++ source libraries.