Re: [boost] Documentation for Boost libraries

From: Michael Marcin (mike.marcin_at_[hidden])
Date: 2008-06-30 15:55:45

Edward Diener wrote:
> It is very nice that ASIO has all of this functionality which you 
> mention but since the overview documentation, aside from the tutorials 
> and examples, is nonexistent it would take a more persistent programmer 
> than I am to figure out how to do anything with the library other than 
> socket programming. Even in the latter regard I find the lack of an 
> overview to be daunting as I do not learn libraries well from 
> tutorials/examples, but do from actual documentation with conceptual 
> explanations.
> 

I agree.

Last week I had to create a prototype for a real-time multiplayer game 
including multiple clients and a server. I've been meaning to look at 
Asio for a while so I used it for this project. I started by reading the 
using Boost.Asio, tutorial and design sections. After I finished this I 
really still had almost no idea how to use the library to accomplish my 
task.

I then looked to the examples and found that that chat program was 
probably the closest thing to what I needed. I found the code for it to 
be somewhat convoluted and includes no comments at all.

I finally found some information I could digest in the reference 
section. For my demo server io_service run worked fine but I didn't want 
to deal with the complexities of multithreaded code for the client in my 
timefram. I eventually found io_server poll which suited my clients 
needs but I don't recall seeing this outside of the reference. I came to 
some incorrect conclusions based on the reference material that didn't 
show up until they were runtime errors.

For instance while doing an async_read I passed in a buffer created from 
the asio::buffer function by passing a std::vector. The reference 
documentation says:

"An individual buffer may be created from a builtin array, std::vector 
or boost::array of POD elements. This helps prevent buffer overruns by 
automatically determining the size of the buffer: "

I took this to mean that if I passed in a std::vector it would resize 
the vector to the size required to complete the read. I found out that I 
was wrong rather abruptly when I got a crash after passing in an empty 
std::vector.

On the whole I probably learned more from the comment blocks above the 
Asio functions than the documentation.

Eventually I did manage to cobble together something that appears to 
function which is all I needed for my current task and it was easier 
than using winsock directly which I haven't done in several years.

I really want to learn how to write better and more efficient networking 
with Asio but the documentation seems to be a reference for people that 
already know networking well. For instance the design section says:

"To allow the development of efficient network applications, Boost.Asio 
includes support for scatter-gather operations"

But not why or how these make network applications more efficient.

Thanks,

Michael Marcin