Boost logo

Boost :

Subject: Re: [boost] AFIO on the Incubator
From: Robert Ramey (ramey_at_[hidden])
Date: 2015-08-19 11:22:44

On 8/19/15 2:49 AM, Niall Douglas wrote:
> On 17 Aug 2015 at 14:58, Robert Ramey wrote:
>>> FYI I know of about seven people who have ever even tried AFIO in 30
>>> months. It's too niche, though when you see my brand new workshop
>>> tutorial with benchmarks on Friday I think that might radically
>>> change :).
>> Maybe a year ago I went though the documentation of AFIO and wrote a
>> comment based on that experience. I've seen that the package has
>> improved enormously since then. I like to think that my comment made a
>> small difference. (Incidently, I removed my old comment because I didn't
>> think it was relevant any more.)
> Your comment made more than a small difference in fact. It made me
> realise I'd need to implement a much more friendly user facing API.
> You are the Boost.Serialisation guy after all, if you're not lighting
> up with excitement then I'm doing something very wrong.

This is gratifying to me.

> I still don't have iostream serialisation support in AFIO, nor do I
> wish to add it (it's racy). However I have thrown serialisation folk
> a bone by making the new workshop tutorial iostreams based, so I show
> how to adapt AFIO to iostreams in a race free way.

serialization is orthogonal to iostreams so I don't know if that's

I would expect that some sort of support for iostreams would be almost a

>> I think I'm starting to get an idea of
>> what problem the thing is supposed to address.
> I'm hoping by the end of the new tutorial anyone reading will be
> convinced. I hope.
> We'll find out on Friday. I have the final step in the tutorial to
> finish before then, but otherwise it's ready.


I very much want you (and others of course as well) to be successful in
your quest to get your library added to Boost. I believe that the http
experience shows the wrong way to go about it. My personal experience
with the serialization library was a tortured affair involving an
initial rejection illustrates the promise and power of the Boost library
review process. It was personally devastating to me to fail at this
endeavor - but the rejection was correct as the first version of the
library wasn't good enough. It's only due to a particular personality
defect (pathological stubbornness) which resulted in me redoing the
whole thing while incorporating all the feed back from the review. The
rest is history - the library was accepted and eventually came to be
probably one of the most commonly used boost libraries.

Here is my advice - Do not do this. Get it right the first time.

In order to spare others the disappointment, frustration, and huge
amount of extra work, I was motivated to create the Boost library
incubator. I've tried to summarize my experience in such a way as to
help library authors be more successful. It's very hard to know whether
or not it has been successful - the user feedback part has been a
disappointment but its in large part done so we'll see.

Here is my meta advice - Follow my advice at It's
meant to be almost a "form filling" exercise to create a boost quality
library that will be accepted.

In particular,

a) spend more time and attention writing the documentation
b) follow the documentation guidelines
c) write, document and implement concepts
d) write the documentation, code, and tests together

There are two (at least) ways of thinking about creating a software library.

a) It's a sub machine - like a starter motor for a car which can be
included in any other car design.

b) it's a mathematical proof. Given conditions a, b, c it will produce
results x, y and z.

The latter train of thought is more likely to be successful. This also
casts a library as just an implementation of the ideas expressed in the
documentation. As extraneous ideas are cast from the "proof" the
library get's smaller - and paradoxically more useful. Less a bag of
disparate features and more the manifestation of a clearly defined
concept which can more easily composed.


In particular, I do not want to see you (in particular) fail in this
endeavor. To this end I will commit myself to reviewing and/or
commenting on your library as soon as you tell me that you've made the
changes you want to include and think it's ready. Hopefully, you'll
find this useful in preparing for the review. You may or may not
incorporate my observations, but at least you won't be caught with your
pants down when it comes time for the review.

Robert Ramey

Boost list run by bdawes at, gregod at, cpdaniel at, john at