Re: [boost] [serialization docs] Ping?

From: Robert Ramey (ramey_at_[hidden])
Date: 2005-09-22 12:36:24

David Abrahams wrote:

> That's a context in which Allocator is a dependent type.  Let me be
> perfectly clear.  Try compiling this:
>
>       struct foo {};
>       void f()
>       {
>          boost::serialization::text_oarchive<std::ofstream> ar;
>          ar.template register_type<foo>();
>       }
>
>
> On a conforming compiler, it will fail.  Now remove the template
> keyword and try again.

OK, I see this now.  But I don't think the example above represents
common or useful usage.

But it turns out there are several places within
the library where the ar really is a template.  One place is within
the implementation of serialization.   This is would be no big deal
to me as its inside the implementation.

There are examples and tests and I'm sure user programs which
do the following.

struct X {};
struct Y : public X {};

template<class Archive>
void serialize(Archive & ar, X & x, const unsigned int version){
    ar.register_type<Y>();    // will fail on any conforming compiler
    ar.template register_type<Y>();    // will compile on a conforming 
compler - will fail on others
    ar.register_type(static_cast<Y *>(NULL));    // works everywhere.
}

Of course a user could do

void serialize(boost::serialization::text_oarchive<std::ofstream>  & ar, X & 
x, const unsigned int version){
    ar.register_type<Y>();    // compiles fine
    ar.template register_type<Y>();    // fails to compile
    ar.register_type(static_cast<Y *>(NULL));    // works everywhere.
}

But I would argue that he is needlessly giving up generality.

So my advice to user it to always use the third choice above so that
he can just forget about it an move on.

>>> Maybe I've been too hasty, but it seemed to me, from the lack of any
>>> requirement that the archive do something that interacts with the
>>> Serializable concept (and produce sensible semantics) and your
>>> reference to a separate section describing how to implement an
>>> archive, that you had been trying to make the "Archive Concept"
>>> section a "user-only" document, and had put the real requirements
>>> elsewhere.
>>
>> correct. But I didn't think of them as "real requirements", I
>> thought of them as "implementation details" from the perspective of
>> the user.
>
> Are they requirements or aren't they?  It would be conceptually purer
> if a model of the Archive concept wasn't required to be derived from a
> library-provided class template, but I could live with that derivation
> requirement if the other requirements you specified were complete and
> meaningful.

Again here is the crux of the problem.  The information in the section
is not "real requirements".  It is description of how I implemented the
Archive Concept(s) as decribed in the first section.  It is here that
the sematics are really defined.  And of course the exact semantics
vary according to the particular archive.  For example, the xml_archives
include a tag with the variable name - other archives don't.  However
they all implement the Archive Concept(s).

So again here is how I came here.

The main task for the user of the library is to make his types
"Serializable".  Of necessity, this requires a description of the
interface to an "Achive" class which is normally passed as a template.
The in turn requires that the "Archive Concept(s)" be defined so that
the user may know what operations he can invoke on the "Archive"
class passed as an argument. The SOLE function of the "Archive Concept"
documentation is to enumerate those operations.  This is all that is
required for a user to write a "serialize" function which he can know
with certainty will function with any conforming implementation.

Now comes the problem of how to implement an archive which
implements the concept.  Of course it must support the enumerated
operations.  Hopefully it does something useful, but that's an issue
totally separate from the definition of the Archive Concept.

The section titled "Archive Implementation" describes how I managed
to make a set of archives which fullfilled the requirement of the
"Archive Concept"  They are not part of the Archive Concept itself.

There is no requirement that an Archive implementor use any of
the information in this section or any of the archive code included
in the library.

> Matthias did. [failed to make a new archive]  He only succeeded after 
> getting information from you
> that wasn't present in the docs.

But this is not due to the problems of "Archive Concept(s).

Mattias leveraged on my implementation of other archives.
And he did manage to do it with very little help from me.
(I assume it wasn't much as I don't specifically remember getting any
quesitons from him).  FWIW other users have made thier own
archives based on the information in this section - I think there
is one even loaded to the vault.

In any case, I've acknowledged that the section
"Archive Implementation" is not satisfactory as it stands for the
purpose for which it was intended.   I've looked at it in terms
of formal concepts and in light of the iterator library but still
have not been able to formalize in a way that would be
accurate and useful.  This will take some time.

>> I think what I should have done and what we should do now is:
>>
>> a) change the title of the section "Archive Concept" back to
>> "Archive User Interface"
>> or "Archive Interface". and restore the original content which is
>> based of function prototypes.
>> b) change the title of the section titled "Serializable Concept"
>> back to "Serializable types".
>> c) The question of formal documentation for the serialization library
>> can be considered at leisure.
>
> Grrr!
>
> You're very close to having reasonable concept documentation now; I
> don't know why you'd throw that out.

I see now we're much farther apart than I thought we were.

> As I've said, "formal" documentation isn't the issue; the question is
> whether the docs can be practically used by someone who wants to build
> a new archive type.

In order of frequence of usage, I see the documents as being used
to describe how to:

a) make one's types serializable. ("Archive Concepts" and "Serializable 
Concept")

b) use archives which are included. ("Archive Models")

c) make one's own archive implementation leveraging on the code included.
("Archive Concept" and "Archive Implementation")

d) make one's own archive implementation from scratch.  No one has
ever attempted this.  ("Archive Concept")

I realize you don't buy this and expect to see information which is
included in "Archive Implementation" moved to "Archive Concepts".
But in my view that muddles the whole functional organization which
I was so careful to preserve above.  Its been this way since the
beginning.

What's changed is that the descriptions are couched
in terms of "Concept" and "valid expressions" rather than function
prototypes a before.  At this point part of the documentation
uses one approach and other parts use the other and this is
confusing.  That's why I would like to go back to were we
started and just elmininate the terms "Concept" which imply
a method which hasn't been used in a consistent and
correct way throughout the document.

I've also come to believe that the notion of "Semantics" is
quite subjective and needs to be thought through more.

So that is the basis of my suggestion for roling things back
to the begining and just removing the word "Concept" as
its use isn't really correct in that context.

Robert Ramey