Re: [Boost-users] [boost] [afio] Formal review of Boost.AFIO

Subject: Re: [Boost-users] [boost] [afio] Formal review of Boost.AFIO
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-08-25 07:37:07

From: Boost-users [mailto:boost-users-bounces_at_[hidden]] On Behalf Of Ahmed Charles
Sent: 23 August 2015 02:09
To: boost-announce_at_[hidden]; boost-users_at_[hidden]
Subject: [Boost-users] [boost] [afio] Formal review of Boost.AFIO

 

The formal review of the Boost.AFIO library starts, August 21st and ends 
on Monday August 31st.  
 
Boost.AFIO provides a portable API implementing synchronous and 
asynchronous race-free filesystem and scatter-gather file i/o. It requires 
a minimum of C++ 11. It has minimum dependencies on a Filesystem TS and a 
Networking TS implementation (e.g. Boost.Filesystem and Boost.ASIO). 
Backends are provided for the Windows NT kernel and POSIX.  
 
The utility of a portable library providing strong concurrent race 
guarantees about filesystem and file i/o can be seen in its tutorial where 
a transactional ACID key-value store is built from first principles.  
 
Boost.AFIO was brought to Boost as part of GSoC 2013 and Niall Douglas has 
continued to develop and improve the library since then, generating two 
internal implementation libraries Boost.APIBind and Boost.Monad which are 
expected to be separately brought for Boost review in 2016.
 
The documentation can be found here: 
https://boostgsoc13.github.io/boost.afio/doc/html/afio.html  
 
The source code can be found here: 
https://github.com/BoostGSoC13/boost.afio/tree/boost-peer-review  
 
Online web compiler playpen can be found here:
http://melpon.org/wandbox/permlink/DR8wCpu5Rl20GMdM?
 
 
Please answer the following questions: 
 
1. Should Boost.AFIO be accepted into Boost? Please state all 
   conditions for acceptance explicity. 
 
Provisionally, yes. 
 
Requirements:
 
.        Major restructuring of documentation. (Not re-writing!)
 
.        Completion of Boost.Was_Called_Monad and APBind.
 
.        Creation of a TODO list.

 

.        Mini-review before going into a release (perhaps of all together?).

 

.        More documentation of examples to explain what they demonstrate.
 
 
2. What is your evaluation of the design? 
 
Not qualified to judge.

3. What is your evaluation of the implementation? 
 
Mature-ish but still evolving. 
 
Incomplete  - but that is no reason for rejecting a library.
Just as "No battle plan survives the first contact with the enemy".  No software does either.
 
IMO what we are deciding is if we want this software to be developed and maintained, not, as some
mistakenly imagine, if it is finished and complete ready to go into the 1.60 release.  It isn't and
won't be until 1.61 at the very earliest, and will still be modified after release because 
 
.        It is using cutting edge tools.
.        It is breaking new ground and will be changes by C++ Standard, Library and compiler
changes.
 
Personally, I don't believe that Incubator is the right way to speed development of this software.
I think we need to alter the Boost review and acceptance process.  I favour accepting this quite
mature software and being prepared for it to change as a result of user experience.  It won't get
users until it is part of a release, as we are running things at present.
 
I have a violent objection to the name monad - anywhere in Boost.  As I have said before.
 
It just seems unsuitable for the task - it's just far too general - you wouldn't have a function
called 'sub-routine'?
 
Better to called it "useful_software_thingy_but_we_don't_have_a_good_name_for_it_yet!" 
 
Names really do matter!
 
4. What is your evaluation of the documentation? 
 
Looks nice.  Excellent index.  Good documentation of functions.  
 
But impossible to see the wood for the trees! L
 
(Ability to add comments makes it even worse at review time!)
 
Get into far too many details far too soon.  Feels like a stream-of-consciousness dump L
 
Overall structure and sections need major re-thinking and re-structuring. 
(Getting someone not 'burdened by knowing too much' might be the best idea?)
We don't need configuration info in the introduction, for example.  I'd use Quickbook code snippets
and a link to the full code, so avoiding clutter like which namespace to use.  The full code should
be user runnable and linked from the text.
 
Move all the 'coming soon trailers' to a separate "Planned enhancements" or "Roadmap" section (and
provide links to that where necessary in the text.
 
I didn't find the callouts on the "Table 1.10. Traditional STL iostreams and AFIO side by side"
at all helpful - why not just add C++ comments?
 
For the time being, I'd prefer that the (very informative) papers on this immensely complex subject
held elsewhere and referenced rather than being part of this documentation (at least while we are
reviewing).  (This is especially as it contains reference to a TripleGIT system which I suspect is
conceptware at best and vapourware at worse).

5. What is your evaluation of the potential usefulness of the library? 
 
Niche at present, but what the library offers will undoubtedly be useful to far more people than
they now realise, and far sooner.  

6. Did you try to use the library? With what compiler? Did you have 
   any problems? 
 
Worked out that I could not use this without VS2015 and I'm still in the dim ages of VS2013.

7. How much effort did you put into your evaluation? 
 
A quick reading.
 
8. Are you knowledgeable about the problem domain? 
 
No, but I expect to have to become so.
 
Paul

 

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]