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

Subject: Re: [boost] [afio] Formal review of Boost.AFIO
From: Vladimir Prus (vladimir.prus_at_[hidden])
Date: 2015-08-31 05:28:24

On 31-Aug-15 2:46 AM, Glen Fernandes wrote:
> On Sun, Aug 30, 2015, Gruenke,Matt wrote:
>> This obviously isn't a proper review, and shouldn't be counted as such.
>> Rather, I pose a question to other reviewers: for how many of you does
>> this actually solve a problem you've faced or anticipate?  For me, the
>> answer is "no".  Otherwise, I'd invest further time in a proper review.
>
> This is exactly what I feel. The answer is "no" for me too. This is
> also the reason why I haven't submitted a formal review.

It's quite reasonable question, yes. While there are people on the list
who are deeply aware of recent developments in C++ concurrency, and can
discuss how futures are to be implemented, I was wondering whether I
can use the library to solve my specific issues, and was blocked right
away at the introduction. It might be a great library, but so far the
quality of documentation is a serious impediment to considering it.

Say, introduction suggests I might use AFIO if:

     Your spinning magnetic rust hard drive goes bananas when some routine in
     your code tries to do something to storage, and latency per op starts
     heading into the seconds range.

I have no idea what that means. Another quoted reason is:

     Your code has to interact with a regularly changing filesystem and
     not get weird race errors

That sounds interesting, but still rather vague. It would be helpful if
the introduction be completely rewritten to list concrete situations for
which the library has ready-made, or easy-to-build, solutions.

For example, here are use cases I have at the moment

- Detect when files are added in a directory, compute their SHA1 checksum,
   and notify my other code. Needs to use opportunistic locking on Windows
   to make sure the computed checksum actually matches the final state of
   the file.

- Write content X to a file F, but only if the file content did not change
   since a change to that file was reported to me.

I can't tell whether these use-cases are supported. The tutorial is not
really helpful, it builds something rarely needed (yes, sqlite works),
and the amount of the code shown makes one wonder whether the abstractions
are too low-level.

There's another example at:

    https://boostgsoc13.github.io/boost.afio/doc/html/afio/quickstart/mini_programs/atomic_logging.html

and that starts with "I should emphasise once again that the advisory locking code is riddled with bugs",
and has a code example with not a lot of comments, several "if (1)" and "#if 0" statements, and

        // **** WARNING UNSUPPORTED UNDOCUMENTED API DO NOT USE IN YOUR CODE ****

remarks. Again, the fundamental design and engine might be sound, but it's impossible to
say whether the library solve any practical problems.

I think reworking introduction around concisely solving more specific use cases should be the
top priority for future evolution.

- Volodya