Boost is cool, and boost code is generally complex. The Asio library is cool, complex, and not really well documented.

Boost.Asio docs from Boost. The best part is really the tons of examples, but examples always suffer from, well, being examples. There is a separate document also written by Christopher Kohlhoff that is also useful to read.

The author of Asio keeps a blog:

StackOverflow thread Best documentation for Boost:asio points a few things out.

There is an online version of The Boost C++ Libraries by Schaling; chapter 7: Asynchronous Input and Output, is a decent read.

Oddly enough, while the Networking Library Proposal for TR2 was disparaged in the StackOverflow thread, it’s actually a pretty good thorough-yet-concise description of Boost.Asio. The down side is that it’s pretty old at this point (it was written in 2006). Maybe Boost.Asio has been really stable and hasn’t been changing a lot – I don’t know.

There is the book Boost.Asio C++ Network Programming by John Torjo, published February 22, 2013, also available as an ebook. However, this book has been somewhat disparaged as fluff or introductory.

Introduction to the Boost C++ Libraries, Volume II – Advanced libraries has several chapters on Boost.Asio.

Interesting article on making Boost as a Framework for MacOS/iOS.


OpenSSL tidbits

An Introduction to OpenSSL Programming (Part I) by Eric Rescorla (the author of the main SSL/TLS book). This is a good companion piece to the book.

Use OpenSSL with Asynchronous Sockets, I/O Completion Ports and Ceritificate Signing has a lot of useful details on mixing and matching SSL and sockets.

Secure programming with the OpenSSL API, Part 1: Overview of the API article from developerWorks.

Cleaning up the build process for OpenSSL on Windows:

The OpenSSL mailing list is at:!forum/

This is a copy of the original SSLv2 spec:

Procedure calls

The procedure call may have been one of the greatest inventions of all time, at least as far as computer programming goes. When was it invented?

Here’s a history of calling support that Mark Smotherman put together: Subroutine and procedure call support.

It looks like the subroutine came first, and only after many years did it evolve into a procedure call (e.g. passing parameters). Alan Turing in 1946 and David Wheeler in 1947 are the first ones to mention ways to invoke subroutines; it became formalized in machine architecture in 1951, parameters were passed (albeit inline in code) in 1955, and by 1963 machine architectures were stack-based, which would finally allow for multiple threads of execution.

So it took something like 17 years for procedure calls to evolve into usable form.

Remote procedure calls sprang into being much more quickly, and have been a drag on our thinking and processing ever since. The main reason is that procedure calling never fails (absent whole-world catastrophe that’s not something you check for), whereas remote procedure calling itself can fail quite easily, and you have to check for that – but you don’t, because you are used to procedure calls being perfectly reliable. It’s math -> physics -> biology.

RPC was proposed in RFC 707:  A High-Level Framework for Network-Based Resource Sharing, in 1976.,

A Critique of the Remote Procedure Call Paradigm

Communication Primitives for Ubiquitous Systems or RPC Considered

Convenience over correctness

Steve Vinoski’s blog has lots of rants against RPC

RPC is a specific approach for developing networked applications where local calls wrap and hide operations that happen to be carried out on another system across the network. The worst and original form is a blocking, synchronous invocation and has the syntax of a statically bound procedural invocation where the procedure acts on an ordered list of formal parameters and returns a result.

Pure RPC is bad. But even impure RPC affects your thinking.

For example, the so-called two-army problem: there is no way to acknowledge the end of a communication, because an ack or an ack to an ack (and to infinity) can be lost.

Great quote from a Lambda The Ultimate thread

RPC schemes aren’t entirely useless. They work pretty well for essentially trivial problems, which make up most of the situations that people who use them get into. But as soon as you go beyond a simple query/response, they are looking at stuffing 20 pounds of potatos into a 10 pound potato-capacity bag, and fixing all the “impedance mismatch” problems in the world only expands the capacity to 12.5 pounds.

Message Passing, Remote Procedure Calls and Distributed Shared Memory as Communication Paradigms for Distributed Systems

Message Passing vs Remote Procedure Call

RPC vs Messaging

The case: RPC vs. Messaging.

Promises and futures are ways that people have tried to fix remote procedure calls.

Promises: Linguistic Support for Efficient Asynchronous Procedure Calls in Distributed Systems

Inside Macintosh – an exemplar of good technical documentation

Caroline Rose created some of the best technical documentation ever with the Inside Macintosh volumes. The Macintosh, like the Lisa, had a radically different programming architecture – it was event-driven rather than structured or procedural. And so, the documentation had to not just describe the Macintosh APIs, but also to put them in context so that people could make the shift. It didn’t try to teach event-driven programming, but it did constantly talk about how various parts of the system should be used.

PDFs of the original three volumes are online here:

It’s worth looking at if you are writing technical documentation of your own. You could go far worse than to try to emulate this style.

And to put the size of the documentation in context – there was 64KB of ROM, and 128KB of RAM, in the first Mac that shipped, and this was covered with about 1200 pages of documentation. For a modern system that encompasses millions of lines of code – either we write code much less tightly than Apple did back in 1984, or we don’t document it nearly well enough.

Oh, and I say Caroline Rose, because my understanding is that she wrote a lot of the first three volumes of Inside Macintosh, and even had an impact on the software by trying to document it (“Her systematic approach to clarity also helped internal Apple developers who, thanks to Caroline remarks, sometimes rewrote their software improving it substantially”). Here are some links: