id	summary	reporter	owner	description	type	status	milestone	component	version	severity	resolution	keywords	cc
9023	asio::io_service::wrap() docs need an example	vinnie.falco@…	chris_kohlhoff	"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.
"	Feature Requests	closed	To Be Determined	asio	Boost 1.54.0	Cosmetic	invalid