From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Ahmed Charles
Sent: 23 August 2015 02:09
To: boost-announce@lists.boost.org; boost-users@lists.boost.org
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

+44 (0) 1539 561830