Re: [boost] [asio] Formal Review

From: Christopher Kohlhoff (chris_at_[hidden])
Date: 2005-12-12 21:16:24

Hi Caleb,

--- Caleb Epstein <caleb.epstein_at_[hidden]> wrote:
<snip>
> One place where asio stops short, however, is in the area of
> more high-level user-friendly abstractions.

If asio does get accepted, and after wider in-the-field
experience is gained, i'd like to look at developing a library
of higher level abstractions, e.g. common protocols like http,
functions for creating endpoints from URLs etc. I see one of the
roles of asio as to provide a basis for further abstraction.

> There is one example application (in
> example/iostreams/daytime_client, unfortunately not linked to
> in the Review Materials HTML documentation) that illustrates
> how a high-level Iostreams-based interface can be built using
> asio and Boost.Iostreams.  The "socket_stream" class
> implemented here is pure gold for users who want to write
> simple client applications and don't want to know about the
> demuxer, host resolver, or asynchronous operations.  It might
> be worthwhile to include this class or something like as part
> of the asio library and not just as an example.

I didn't really think it was of high enough quality as-is :)
particularly with respect to its interface, but if people think
otherwise...

> I've run into some const correctness problems for operations
> that should likely be const (e.g.
> basic_*_socket::get_local_endpoint, and
> ::get_remote_endpoint).  For example it would be nice to be
> able to write this:

Oops. I fixed it for stream_socket and datagram_socket, but not
for socket_acceptor. Sorry!

> std::ostream& operator<< (std::ostream& os, const
> asio::ipv4::tcp::endpoint& endpoint) { return os <<
> endpoint.address().to_string() << ':' << endpoint.port(); }

BTW, operator<< is now defined for endpoints too, and it outputs
in the format you use above.

> The Reference documentation for the library is quite good
> overall, but it might make sense to elide some of the
> low-level detail in places.  I don't think most users will
> care that stream_socket is simply a typedef of
> basic_stream_socket<> (though this could be mentioned on the
> basic_stream_socket<> documentation).  The extra clicks
> required to get at the documentation you actually need (that
> of basic_stream_socket) can be frustrating.

Some time soon I'm going to look at using doxygen's XML output
to generate the output in a friendlier format, and when I do
this I'll automatically clone the documentation from
basic_stream_socket<> to stream_socket, etc. I do like how
doxygen keeps the documentation close to the code, but I find
its generated HTML a little quirky.

<snip>
> It appears that the valid values for
> "asio::socket_base::message_flags" are undocumented.  This
> makes the basic_stream::async_* functions rather hard to use
> :)

They are, but not linked to from anywhere it seems. You can find
them on the socket_base page. I should add links to them from
the functions that let you use them.

<snip>

Cheers,
Chris