Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2014-08-18 07:35:36

On 17 Aug 2014 at 18:32, Robert Ramey wrote:

> With an eye to verifying the existence of library using templates which would
> not benefit from explicit type constraints I went through some of the
> documentation of AFIO.  I posted a log of my notes as I went through it
> here:
> 
> http://rrsd.com/blincubator.com/open-content/#comment-26

A strange location for a comment. Why not on the AFIO review page?

> Of necessity, it sort of rambles around before it gets to the main point. 
> That's because I had to start at the beginning in order to have enough
> context to understand it.

You actually made some very valid points, points which were facepalm 
obvious. Thank you. I tried hitting reply, but there appears to be no 
mechanism for quoting which would make a rebuttal confusing and 
messy. I can rebut here (about half your observations are already 
answered in the docs), or am I wrong about the lack of quoting?

FYI you had some unfortunate timing, last night just after I went to 
bed my DSL modem decided to go into a bootloop, so my CI was offline 
till 9am this morning when I power cycled the modem. Hence all the 
documentation was not online.

Due to continuing DSL modem instability, I am already in the process 
of relocating AFIO documentation to be autopushed onto github after 
each CI run, in fact I only completed the refactoring of the CI 
innards to achieve this three weekends ago and last week was my 
daughter's christening.

> a) I don't think this library demonstrates that type constraints 
wouldn't
> help.  In fact I think the opposite.
> b) This further reinforces my view that DOxygen is not a great system for
> writing C++ documentation.

Its two big advantages are that both Eclipse and Visual Studio will 
show tooltips of the API doc when you hover over it, plus it has 
exceptionally low maintenance. Otherwise I agree, it's not bad for Qt 
C++, but not good for Boost C++. I am unaware of a superior 
alternative in maintenance costs.

> c) AFIO is much more complicated than I think it has to be - but I can't
> prove this because its so hard to understand anything about it.

On the last point I will say this: AFIO is clean, logical and simple 
only when compared to other asynchronous i/o libraries. The Windows 
overlapped i/o API, libuv and of course the POSIX aio API come to 
mind, all of which have their own weird quirks too. You may find the 
reverse engineered docs for Linux's KAIO async i/o API at 
http://www.fsl.cs.sunysb.edu/~vass/linux-aio.txt illustrative as to 
what I mean about API complexity. There are also a list of caveats, 
gotchas and quirks for using Linux KAIO at 
https://code.google.com/p/kernel/wiki/AIOUserGuide which AFIO makes 
disappear for you so you don't need to think about them [1].

In other words, the lack of complexity is entirely relative to its 
peers only. I agree that in absolute terms 98% of people needing to 
do storage don't need async i/o. This is why AFIO will never be 
popular enough to find a review manager.

[1]: AFIO doesn't support the Linux KAIO API yet, we ran out of time 
during GSoC 2013. But the design accomodates the Linux quirks as well 
as it does the Windows quirks, and a lot of non-obvious effort was 
expended very early on to make a design which would hide 
platform-specific implementation detail so well.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ 
http://ie.linkedin.com/in/nialldouglas/