Re: [boost] [serialization] concept requirements

From: David Abrahams (dave_at_[hidden])
Date: 2006-05-21 21:28:10

"Robert Ramey" <ramey_at_[hidden]> writes:

> David Abrahams wrote:
>> Hi Robert,
>>
>> Once again I find myself confounded by the true concept
>> requirements for archives.  Once upon a time, the
>> truth-as-we-knew-it was that the following (copied from the library
>> docs) was part of the input archive requirements.
>>
>>  All input archives should be derived from the following template:
>>
>>  template<class Archive>
>>  detail::common_iarchive;
>
> The above state isn't correct - as you've discovered.  it seems to me
> that it should say something like"
>
> "archives included as part of the library have been derived
> from the following template:
>
> template<class Archive>
> detail::common_iarchive;
>
> In order to factor out common code to fewer modules."

Okay.  Or maybe that implementation detail of the library doesn't need
to be documented at all.

>> But, as I just discovered: polymorphic_iarchive doesn't meet those
>> requirements.
>
> Note that polymorphic_?archive is an abstract base class.  Hence, it
> cannot perform the operations required by the archive concept.  So I
> would say only a derivation from polymorphic_?archive can fulfill
> the archive concept.  All derivations from polymorphic_?archive
> included with the library do in fact also derive from
> common_?archive.
>
> Actually, the application of "Concepts" in the context of an
> abstract base class is a little ambiguous to me.  I would have to
> think about it.

You might express many of the requirements in terms of a class that
must be derivable from the model of the concept.

>> Since you have struggled with how to write the concept requirements
>> for archives, I have a brilliant suggestion: create concept checking
>> classes and archetypes using Boost.ConceptCheck, and use those to
>> formulate and validate your concepts.  Then you can simply copy the
>> concept checking classes into your documentation and add a description
>> of semantic constraints.  You can't go wrong if you do that; the
>> compiler will check your work for you, and make sure your code is
>> consistent with your documentation.
>
> This is an idea that has occurred to me before - actually during our
> memorable discussion regarding documentation of the serialization
> library.
>
> Actually until that time I had only the barest notion of the utility
> and usage of the the "Concepts" concept.  When I looked at it more
> carefully, I saw the utility of building and maintain the concept
> classes during library development.  This would help a lot in
> maintaining a consistent view, avoid dead ends, etc, etc.  And of
> course it would help the documentation.
>
> I resolved to look into it when I had some time.
>
> That opportunity presented itself when I had occasion to use the
> multi-array library.  I tried to use the concepts included to check
> my code deriving from this class which didn't work out for me.  

Which class were you deriving from?

IIUC the MultiArray library doesn't have any classes meant to be
derived from in it, and until very very recently there was no way to
use derivation with the concept checking library either, so what
you're saying doesn't make much sense.

> Then I dug deeper and found that although the concepts were
> included, the code was written in terms of specific classes rather
> than templates which used type arguments checked with the concepts.

That doesn't square with what I'm seeing in the multi_array code.  For
example, in multi_array.hpp:

    
  template <class ExtentList>
  explicit multi_array(ExtentList const& extents,
                       const general_storage_order<NumDims>& so) :
    super_type((T*)initial_base_,extents,so) {
    boost::function_requires<
      detail::multi_array::CollectionConcept<ExtentList> >();
    allocate_space();
  }

> Oh and there were some compiler dependent quirks. All in all it
> seemed that the concept checking classes were added on at the end to
> satisfy some documentation requirement.  They weren't really used as
> far as I could tell.  

How do you think they're supposed to be "used?"

> So, all in all, I was very disappointed.  My general impression was
> - great concept - but not quite ready for "the rest of us"(r).

That's wrong, actually.  "The rest of us" simply haven't tried to
learn to use them.

> I do see much merit in the idea of developing the library, concepts
> and documentation skeleton in parallel.  When I made the serialization
> documentation, I followed the boost pages regarding how to
> make boost documentation and they didn't (don't) mention anything
> about concepts and how to use them.
>
> What is really needed is a tutorial/example on making a very small
> boost library which would show how this is done.  Starting with a
> small idea and showing how each change ripples through the library,
> concepts, skeletal documenation, compile - only tests - for testing
> the concepts, and runtime tests - for programming errors.

Well, that's a great idea, actually.  But seriously, you don't need
that much hand-holding.  Who is likely to go to the trouble to write
that, when
http://www.boost.org/libs/concept_check/using_concept_check.htm is
already *extremely* generous and easy on the reader?

>> [I have recently upgraded the ConceptCheck library to allow some nicer
>> but as-yet-undocumented syntax.  When (if?) you decide to do this,
>> I'll give you the quick skinny]
>
> By the time I get to something like this, I would expect that the
> required information will have migrated into boost documentation.

I see.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com