Better documentation on when <cereal/types/polymorphic.hpp> is required

[johnwbyrd]

I spent a few hours beating my head against a particular problem until the solution became clear, and I'd like to save the next guy the same time. In particular, I was trying to serialize something like the following structure:

std::map< int, std::shared_ptr< MySubclass > > myMap;

and I kept getting the following error:

cereal could not find any output serialization functions for the provided type and archive combination.

A serialization function existed and was working for MySubclass, so I couldn't see what all the fuss was about.

The actual source of the error, however, was that I had apparently failed to include cereal/types/polymorphic.hpp, and so myMap could not work out a specialization for MySubclass.

It would be helpful to both amend the documentation and the warning message to indicate that polymorphic.hpp needs to be included any time you serialize a derived class stored within a shared_ptr, regardless of whether or not there are multiple dependent serialized classes.

[randvoorhies]

Sounds reasonable to me. Any suggestions on how to best phrase it?

[johnwbyrd]

How about on http://uscilab.github.io/cereal/pointers.html :

"If your smart pointers are serializing a subclassed object, such as a derived class, you must include the cereal/include/polymorphic.hpp header, regardless of whether or not you are using cereal's support for dynamic instancing of polymorphic types."

And for fixing the warning message in the header:

"If you are using a smart pointer to a derived class, make sure to include cereal/include/polymorphic.hpp . "

Feel free to rewrite this for intelligibility...

[erichkeane]

I'm curious if this is such a common thing to have happen, if we shouldn't just have the shared-ptr serialization code just include polymorphic by default?

[randvoorhies]

I'm fine with that. I don't think there's too much of a compile-time penalty for just including the file. We would need to update all of the documentation to reflect the change. What do you think, @AzothAmmo ?

[johnwbyrd]

I vote to automatically include cereal/types/polymorphic.hpp whenever cereal/types/memory.hpp is included. shared_ptr only would ever be practically used to serialize complicated structs and classes, not basic data types. In the worst case, compilation time is slowed trivially, and in the best case things just magically work out of the box for the average programmer. Anyone else trying to serialize containers of shared_ptrs to derived classes will run into this issue, I suspect. But I certainly don't know this system very well..

[AzothAmmo]

I have no real objection to this.

[randvoorhies]

Great, let's do it. I've put it on the v1.2.0 milestone, as making this change will require some tedious documentation edits. In this case, polymorphic.hpp should probably be moved out of types, and into details (maybe just merged with polymorphic_impl.hpp).

[johnwbyrd]

Thanks!

[AzothAmmo]

I think the best way to go about this is to just include polymorphic in memory and leave the file structure as-is, so we don't introduce a breaking change (plus I like the current organization).

[johnwbyrd]

Since picking and choosing headers is technically a compilation
optimization, I feel that you should have a "quick start" header file that
includes everything by default, and use that in all your quick start
guides. And if that is too slow for people, they can read the docs to only
include the headers they need. It's always better to produce correct
results slowly than to provide confusing compilation errors quickly.
On Tue, Dec 22, 2015 at 11:58 PM Shane Grant notifications@github.com
wrote:

I think the best way to go about this is to just include polymorphic in
memory and leave the file structure as-is, so we don't introduce a breaking
change (plus I like the current organization).

—
Reply to this email directly or view it on GitHub
#193 (comment).