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

Subject: Re: [boost] [Boost-users] [afio] Formal review of Boost.AFIO
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2015-08-24 05:52:37

On 24.08.2015 12:27, Andrey Semashev wrote:
> On 24.08.2015 04:29, Niall Douglas wrote:
>> On 24 Aug 2015 at 0:46, Vicente J. Botet Escriba wrote:
>>
>>>>> I believe that I need something more about monad<T> than what I have
>>>>> found in the documentation.
>>>> If there is anything missing, please do say in detail.
>>>>
>>> Is this link part of the review? I don't believe, so could you point me
>>> where the monad class is documented in AFIO? If it is not documented,
>>> why it is used so broadly.
>>
>> It is used in the tutorial because as we progress through each stage
>> of increasing complexity, you can see that the data_store class
>> member functions lookup() and write() have either a monad<T> or a
>> shared_future<T> return type depending on whether the API is
>> synchronous (monad<T>) or asynchronous (shared_future<T>).
>>
>> I was trying to keep the interface class for each stage as identical
>> as possible, so monad<T> was a natural fit to make the STL iostreams
>> example look exactly like the AFIO asynchronous example. I suppose
>> what you're saying here is that the tutorial should not be using
>> monad<T> because monad<T> is not documented in AFIO.
>>
>> I can easily rewrite the tutorial code to not use monad<T>, it's no
>> problem.
>>
>>>> If you want to pin a specific ABI which won't break in the future,
>>>> you bind afio like this:
>>>>
>>>> namespace afio = BOOST_AFIO_V2_NAMESPACE;
>>>
>>> Where can I find the description of this macro on the reference
>>> documentation?
>>
>> https://boostgsoc13.github.io/boost.afio/doc/html/afio/quickstart/workshop/naive.html
>>
>>
>>> We have two options:
>>> * we wait to review AFIO once Monad is reviewed in Boost
>>> * You include in AFIO, whatever you consider is need from Monad and only
>>> then we review AFIO.
>>
>> I can remove monad<T> from all the tutorial code. Or I can include
>> documentation of monad<T> in AFIO. Which would you prefer?
>
> Niall, I think you're missing the point. Is monad<T> part of the library
> interface? I.e. is the user allowed to use it to work with the library?
> If the answer is yes then it's a public part of the library and should
> be documented and reviewed. It doesn't matter if it is possible to code
> around it. If the answer is no then why is it there in the first place?

Having looked at the docs, I see:

The monad<> comes from Boost.Monad which is a dependency of Boost.AFIO.

To me this looks like Boost.AFIO uses a not yet accepted library in the 
interface. In this case I would say Boost.Monad should be reviewed first 
and Boost.AFIO review should be postponed until after Boost.Monad is 
reviewed and _accepted_.

Alternatively, Boost.AFIO could be reimplemented to exclude the 
dependency on Boost.Monad; this would include removing its mentioning in 
the docs. But I don't know enough of Boost.AFIO or Boost.Monad to say if 
this would be an improvement of Boost.AFIO.