Best documentation for Boost:asio?

Question

The documentation available on the boost website is... limited.

From what I've been able to read, the general consensus is that it is simply difficult to find good documentation on the boost::asio library.

Is this really the case? If so, why?

Notes:

• I have already found the (non-boost) Asio website - and the documentation looks to be identical to that on the boost website.
• I know that Boost::asio is new! I'm looking for solutions not excuses.

Edit:

• There is a proposal to add a networking library to standard library for TR2 written by the author of Boost:asio (Christopher Kohlhoff). While it isn't documentation for boost:asio, it does use it as a base for the TR2 proposal. Since the author put more effort into this document, I have found it to be somewhat helpful, if not as a reference, then at least as an overview.

Answer 1

Some nice documentation on boost including a chapter on asio can be found in a (free) boost book at http://en.highscore.de/cpp/boost/index.html. The chapter on asio provides a general overview and then goes as far as how to develop your own custom asio extensions. Really fantastic effort by Boris Schäling!

Answer 2

First, I've been using Boost.Asio for quite a while already -- and I share your concern. To address your question:

• There really is very scarce documentation about Boost.Asio aside from the introduction and tutorial. I am not the author, but this is mostly because there are just too many things to document for something as low-level as an Asynchronous IO Library.
• The examples give more away than the tutorials do. If you don't mind spending a little time looking at the different examples, I would think they should suffice to get you started. If you want to run away with it, then the reference documentation should help you a lot.
• Ask around in the Boost Users and Boost Developers mailing list if you're really stuck or looking for specific guidance. I'm pretty sure a lot of people will be willing to address your concerns on the mailing lists.

There are efforts (not part of Boost.Asio) to expose a lot of the functionality and possible alternative use cases. This at best is scattered around the web in blogs and other forms of non-packaged documentation.

One thing that is unclear and which will really need close coordination with the author and developers of the Boost.Asio library would be as far as extending and customizing it for a specific platform or adding specific new functionality. This should be improved though but the good thing is it's looking like Asio will be a reference implementation for a standard library technical report (for an asynchronous IO library in the STL) in the future.

• mmocny: Thanks for confirming suspicions. Unfortunately, I tried learning from the examples, with decent but limited success. Unfortunately, I cannot justify using a library which has a small set of examples as a set of instructions. I may heed your advice to ask on the ML, but eagerly await better support!
• mmocny: I just put two-and-two together. One of the top google hits (and most informative articles) I found while googling boost asio was on your blog :)
• Dean Michael: Yeah, but I didn't want to say it out in the open yet. ;) Chis Kholhoff (the author) also has a blog in which he talks a lot about Asio and how it can be used in not so common circumstances.
• unixman83: @mmocny I would agree, however the quality of the implementation of ASIO is better than most other free event libraries, especially under Windows.

Answer 3

I wrote two small articles that could be used as introductions to boost.asio. They are available from my site

• deft_code: I found Alex Ott's website independently while researching whether or not to use asio or ace for our current project. His site answered many of my questions.
• maxywb: RIP this guy's site. This is why you post answers here instead of linking to dead websites until the end of time.

Answer 4

NOTE: I have contacted gamedev.net to let them know about the formatting issues. Unfortunately at the time of writing this comment, this resource is more difficult to recommend because of some changes with their website which hide/delete the #include statements + a missing .zip file resource.

A relatively new and very good beginner tutorial for Boost.Asio (which also introduces how to use it effectively with bind, shared_ptr, and threads) can be found here:

http://www.gamedev.net/blog/950/entry-2249317-a-guide-to-getting-started-with-boostasio?pg=1

Note: If you're using c++0x features many of the simple uses of bind for creating a functor can be replaced with lambdas, and shared_ptr/bind are also available in the latest version of visual studio (or gcc which also includes threads.)

When I was searching for documentation or a tutorial this question kept popping up at the top of search results, so it is important to keep it updated as new tutorials come around.

• Ralf: Great link! Definitely a good guide to getting started with asio
• Rotsiser Mho: Thanks for posting this link. Unfortunately, I felt that just as it was starting to get good, the author drops the ball, dumping you straight into the library he/she created, and completely lost me. He/she went from explaining in detail how bind works to leaving the reader to guess what Hive is in their library.
• M2tM: They have the hive defenition + interface directly in the tutorial. I think it's useful and makes sense because they introduce it on page 10 of 11.
• Jake Gaston: This article mentions a zip file with examples, but I don't see one. Also, the #includes are cut out of the example code?
• M2tM: Ah, unfortunately it seems the article has eroded in the sands of time with an update to gamedev.net's rendering code which seems to not handle angle brackets well at all and I can't vouch for the validity of this answer at this point in time. While it may still be an okay reference, its formatting has clearly not been properly migrated. @JakeGaston

Answer 5

I came along to 3 videos that I've found helpful once you get past the official boost asio overview:

• Thinking asynchronously - designing applications with asio
• Are you ready for ipv6
• Why c-0x is the awesomest language for network programming

And

• Thinking asynchronously slides
• Are you ready for ipv6 slides
• Why c-0x is the awesomest language for network programming slides

Answer 6

The asio documentation, the one available in boost, is minimalist but very precise, each word is significant. That said,I have learned asio (and continue to learn) mainly from SO.

In my opinion, the answer to 'Confused when boost::asio::io_service run method blocks/unblocks' is the very first step, read an read again until you really understand it, second answer is also helpful.

Then I have RSS subscribed to newest SO boost-asio tag question and to these two answerers:

Tanner Sansburry, the author of the answer above, his answers are always very precise, comprehensive, with references, even beautiful schemas. RSS feed
Sehe (sorry Sehe, only 2nd). RSS feed

With all that material, you will soon be an asio expert !

• m4rlord: Confirmed, these writers are rockstars.

Answer 7

I was quite curious about that, too but this page gave me some head start. It's in French, but you could use google translate which is pretty readable (I had to follow down this path myself).

http://gwenael-dunand.developpez.com/tutoriels/cpp/boost/asio/

Answer 8

A little late to the party but there's a book out called "Boost Asio Network Programming" (Packt publishing).

I bought a copy of this, read it over the weekend and then wrote a full on server in C++ without much problem.

Disclaimer: I have nothing to do with the book

• sehe: Ow. I've picked up I think 3 books about Asio from Packt, and have not found them trustworthy. To the extent that I can recognize when people have been reading the wrong books from the code smells they copied into their SO questions, see e.g. stackoverflow.com/a/48084444/85371 or stackoverflow.com/a/47698904/85371

Answer 9

I stumbled on the following pdf: http://boost.cowic.de/rc/pdf/asio_doc.pdf

• Oleh Prypin: But wait... it's just the same thing, only in pdf. Who upvoted this!?