[boost] [asio] Formal Review

From: Caleb Epstein (caleb.epstein_at_[hidden])
Date: 2005-12-12 16:44:18

* Design

I think the design of asio is quite good.  It manages to present a modern
C++ interface to the arcane and error-prone Berkeley Sockets API (among
other things).  It takes what I believe is the right approach of mainly
providing the low-level interfaces required for a high performance
networking library (TCP, UDP sockets with asynchronous operations and I/O
multiplexing) and building higher-level functions on top of these
primitives.

One place where asio stops short, however, is in the area of more high-level
user-friendly abstractions.  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.

* Implementation

Excellent.  The convention use of Boost.Bind for producing Handlers (e.g.
Callbacks) is quite flexible and easy to use.  The templated asio::buffer
function is an excellent solution for wrapping different containers-of-bytes
for sending or receiving network payloads.  The code in the library itself
is easy to read and follow, as are most of the examples.

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:

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

std::ostream& operator<< (std::ostream& os, /* problem here -> */ const
asio::socket_acceptor& sock) {
    sock.get_local_endpoint (endpoint, asio::ignore_error());
    return os << endpoint;
}

But the "const" qualification must be dropped on the second function due to
const-correctness issues with ::get_local_endpoint.

The lack of IPv6 support does not bother me, and I do not think it should
stand in the way of acceptance into Boost, but it is clearly an area for
future work.

* Documentation

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.

The Tutorial offers a good introduction to the basics of the library, but I
think it could use some additional meat which could likely come from
documenting some of the Example programs.

As it stands, I think the Doxygen-generated documentation in the Examples
section offers very little.  More detailed exposition about the form and
function of the Examples would be a lot more valuable than the generated
reference material that exists now.  Additionally, a number of the examples
included in the Review Materials appear to be missing from the Examples
section of the docs, specifically the chat, echo, iostreams, multicast, ssl
and timeouts examples all seem to be ignored.  I think the iostreams one in
particular would put to rest the questions from people who want a simple,
easy-to-use high-level interface.

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 :)

I think the addition of some benchmark programs might be meaningful and
helpful.

* Usefulness

A networking library is arguably one of the most glaring pieces of
functionality missing from C++ and one of the most oft-requested.  I think
it is not much of a stretch to say that asio could be one of the most
popular libraries in Boost if it were to be accepted.

* Use

I have compiled the test and example programs on a RedHat Linux system with
gcc 3.3.4 and another Debian system with gcc 4.0.3.  All tests and examples
compiled and executed successfully.

One small oddity with the Jamfiles seems to be that the top-level directory
created in "bin" for this library is boost-asio-proposal-0.3 when I'd expect
-0.3.6.

In attempts to exercise the multi-threaded capabilities of the library, I
ran into a "deadly embrace" problem when I modified the included timer5
example program to run for a longer time with shorter (10 ms) timeouts.
I've contacted Chris about this and he's looking into the issue.

* Effort

I have been toying with asio on and off for a couple of months now.  I have
probably spent on the order of 12-15 hours reading the documentation and
writing small test programs that exercise its features and have had good
results interacting with Christopher with comments, suggestions and small
bug-fixes.

* Me

I consider myself quite knowledgeable in the problem domain.  I have been
writing network-centric applications in C and C++ for many years and have
experience using other libraries (e.g. OS-native APIs, ACE, proprietary
solutions) that solve some or all of these same problems.

* Summary

I vote that asio be accepted into Boost.  I think it is a fantastic piece of
work.

--
Caleb Epstein
caleb dot epstein at gmail dot com