Support for pointers to polymorphic base classes. More...

#include "cereal/cereal.hpp"
#include "cereal/types/memory.hpp"
#include "cereal/details/util.hpp"
#include "cereal/details/helpers.hpp"
#include "cereal/details/traits.hpp"
#include "cereal/details/polymorphic_impl.hpp"

Macros
#define	CEREAL_STATIC_CONSTEXPR static constexpr

#define	CEREAL_REGISTER_TYPE(...)
	Registers a derived polymorphic type with cereal. More...

#define	CEREAL_REGISTER_TYPE_WITH_NAME(T, Name)

#define	CEREAL_REGISTER_POLYMORPHIC_RELATION(Base, Derived)
	Registers the base-derived relationship for a polymorphic type. More...

#define	CEREAL_REGISTER_DYNAMIC_INIT(LibName)

#define	CEREAL_FORCE_DYNAMIC_INIT(LibName)

#define	UNREGISTERED_POLYMORPHIC_EXCEPTION(LoadSave, Name)
	Error message used for unregistered polymorphic types. More...

Functions
template<class Archive >
typename::cereal::detail::InputBindingMap< Archive >::Serializers	cereal::polymorphic_detail::getInputBinding (Archive &ar, std::uint32_t const nameid)
	Get an input binding from the given archive by deserializing the type meta data.

template<class Archive , class T >
std::enable_if<(traits::is_default_constructible< T >::value\|\|traits::has_load_and_construct< T, Archive >::value)&&!std::is_abstract< T >::value, bool >::type	cereal::polymorphic_detail::serialize_wrapper (Archive &ar, std::shared_ptr< T > &ptr, std::uint32_t const nameid)
	Serialize a shared_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee. More...

template<class Archive , class T , class D >
std::enable_if<(traits::is_default_constructible< T >::value\|\|traits::has_load_and_construct< T, Archive >::value)&&!std::is_abstract< T >::value, bool >::type	cereal::polymorphic_detail::serialize_wrapper (Archive &ar, std::unique_ptr< T, D > &ptr, std::uint32_t const nameid)
	Serialize a unique_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee. More...

template<class Archive , class T >
std::enable_if<(!traits::is_default_constructible< T >::value &&!traits::has_load_and_construct< T, Archive >::value)\|\|std::is_abstract< T >::value, bool >::type	cereal::polymorphic_detail::serialize_wrapper (Archive &, std::shared_ptr< T > &, std::uint32_t const nameid)
	Serialize a shared_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee. More...

template<class Archive , class T , class D >
std::enable_if<(!traits::is_default_constructible< T >::value &&!traits::has_load_and_construct< T, Archive >::value)\|\|std::is_abstract< T >::value, bool >::type	cereal::polymorphic_detail::serialize_wrapper (Archive &, std::unique_ptr< T, D > &, std::uint32_t const nameid)
	Serialize a unique_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee. More...

template<class Archive , class T >
std::enable_if< std::is_polymorphic< T >::value &&std::is_abstract< T >::value, void >::type	cereal::CEREAL_SAVE_FUNCTION_NAME (Archive &ar, std::shared_ptr< T > const &ptr)
	Saving std::shared_ptr for polymorphic types, abstract.

template<class Archive , class T >
std::enable_if< std::is_polymorphic< T >::value &&!std::is_abstract< T >::value, void >::type	cereal::CEREAL_SAVE_FUNCTION_NAME (Archive &ar, std::shared_ptr< T > const &ptr)
	Saving std::shared_ptr for polymorphic types, not abstract.

template<class Archive , class T >
std::enable_if< std::is_polymorphic< T >::value, void >::type	cereal::CEREAL_LOAD_FUNCTION_NAME (Archive &ar, std::shared_ptr< T > &ptr)
	Loading std::shared_ptr for polymorphic types.

template<class Archive , class T >
std::enable_if< std::is_polymorphic< T >::value, void >::type	cereal::CEREAL_SAVE_FUNCTION_NAME (Archive &ar, std::weak_ptr< T > const &ptr)
	Saving std::weak_ptr for polymorphic types.

template<class Archive , class T >
std::enable_if< std::is_polymorphic< T >::value, void >::type	cereal::CEREAL_LOAD_FUNCTION_NAME (Archive &ar, std::weak_ptr< T > &ptr)
	Loading std::weak_ptr for polymorphic types.

template<class Archive , class T , class D >
std::enable_if< std::is_polymorphic< T >::value &&std::is_abstract< T >::value, void >::type	cereal::CEREAL_SAVE_FUNCTION_NAME (Archive &ar, std::unique_ptr< T, D > const &ptr)
	Saving std::unique_ptr for polymorphic types that are abstract.

template<class Archive , class T , class D >
std::enable_if< std::is_polymorphic< T >::value &&!std::is_abstract< T >::value, void >::type	cereal::CEREAL_SAVE_FUNCTION_NAME (Archive &ar, std::unique_ptr< T, D > const &ptr)
	Saving std::unique_ptr for polymorphic types, not abstract.

template<class Archive , class T , class D >
std::enable_if< std::is_polymorphic< T >::value, void >::type	cereal::CEREAL_LOAD_FUNCTION_NAME (Archive &ar, std::unique_ptr< T, D > &ptr)
	Loading std::unique_ptr, case when user provides load_and_construct for polymorphic types.

Detailed Description

Support for pointers to polymorphic base classes.

Macro Definition Documentation

◆ CEREAL_FORCE_DYNAMIC_INIT

#define CEREAL_FORCE_DYNAMIC_INIT ( LibName )

Value:

  namespace cereal {                                       \
  namespace detail {                                       \
    void CEREAL_DLL_EXPORT dynamic_init_dummy_##LibName(); \
  } /* end detail */                                       \
  } /* end cereal */                                       \
  namespace {                                              \
    struct dynamic_init_##LibName {                        \
      dynamic_init_##LibName() {                           \
        ::cereal::detail::dynamic_init_dummy_##LibName();  \
      }                                                    \
    } dynamic_init_instance_##LibName;                     \
  } /* end anonymous namespace */

Forces dynamic initialization of polymorphic support in a previously registered source file

See also: CEREAL_REGISTER_DYNAMIC_INIT

See CEREAL_REGISTER_DYNAMIC_INIT for detailed explanation of how this macro should be used. The name used should match that for CEREAL_REGISTER_DYNAMIC_INIT.

◆ CEREAL_REGISTER_DYNAMIC_INIT

#define CEREAL_REGISTER_DYNAMIC_INIT ( LibName )

Value:

  namespace cereal {                                         \
  namespace detail {                                         \
    void CEREAL_DLL_EXPORT dynamic_init_dummy_##LibName() {} \
  } } /* end namespaces */

Adds a way to force initialization of a translation unit containing calls to CEREAL_REGISTER_TYPE

In C++, dynamic initialization of non-local variables of a translation unit may be deferred until "the first odr-use of any function or variable defined in the same translation unit as the variable to be initialized."

Informally, odr-use means that your program takes the address of or binds a reference directly to an object, which must have a definition.

Since polymorphic type support in cereal relies on the dynamic initialization of certain global objects happening before serialization is performed, it is important to ensure that something from files that call CEREAL_REGISTER_TYPE is odr-used before serialization occurs, otherwise the registration will never take place. This may often be the case when serialization is built as a shared library external from your main program.

This macro, with any name of your choosing, should be placed into the source file that contains calls to CEREAL_REGISTER_TYPE.

Its counterpart, CEREAL_FORCE_DYNAMIC_INIT, should be placed in its associated header file such that it is included in the translation units (source files) in which you want the registration to appear.

◆ CEREAL_REGISTER_POLYMORPHIC_RELATION

#define CEREAL_REGISTER_POLYMORPHIC_RELATION	(	Base,
		Derived
	)

Value:

  namespace cereal {                                                            \
  namespace detail {                                                            \
  template <>                                                                   \
  struct PolymorphicRelation<Base, Derived>                                     \
  { static void bind() { RegisterPolymorphicCaster<Base, Derived>::bind(); } }; \
  } } /* end namespaces */

Registers the base-derived relationship for a polymorphic type.

When polymorphic serialization occurs, cereal needs to know how to properly cast between derived and base types for the polymorphic type. Normally this happens automatically whenever cereal::base_class or cereal::virtual_base_class are used to serialize a base class. In cases where neither of these is ever called but a base class still exists, this explicit registration is required.

The Derived class should be the most derived type that will be serialized, and the Base type any possible base that has not been covered under a base class serialization that will be used to store a Derived pointer.

Placement of this is the same as for CEREAL_REGISTER_TYPE.

◆ CEREAL_REGISTER_TYPE

#define CEREAL_REGISTER_TYPE ( ... )

Value:

  namespace cereal {                                                     \
  namespace detail {                                                     \
  template <>                                                            \
  struct binding_name<__VA_ARGS__>                                       \
  {                                                                      \
    CEREAL_STATIC_CONSTEXPR char const * name() { return #__VA_ARGS__; } \
  };                                                                     \
  } } /* end namespaces */                                               \
  CEREAL_BIND_TO_ARCHIVES(__VA_ARGS__)

Registers a derived polymorphic type with cereal.

Polymorphic types must be registered before smart pointers to them can be serialized. Note that base classes do not need to be registered.

Registering a type lets cereal know how to properly serialize it when a smart pointer to a base object is used in conjunction with a derived class.

This assumes that all relevant archives have also previously been registered. Registration for archives is usually done in the header file in which they are defined. This means that type registration needs to happen after specific archives to be used are included.

It is recommended that type registration be done in the header file in which the type is declared.

Registration can also be placed in a source file, but this may require the use of the CEREAL_REGISTER_DYNAMIC_INIT macro (see below).

Registration may be called repeatedly for the same type in different translation units to add support for additional archives if they are not initially available (included and registered).

When building serialization support as a DLL on Windows, registration must happen in the header file. On Linux and Mac things should still work properly if placed in a source file, but see the above comments on registering in source files.

Polymorphic support in cereal requires RTTI to be enabled

◆ CEREAL_REGISTER_TYPE_WITH_NAME

#define CEREAL_REGISTER_TYPE_WITH_NAME	(	T,
		Name
	)

Value:

  namespace cereal {                                                \
  namespace detail {                                                \
  template <>                                                       \
  struct binding_name<T>                                            \
  { CEREAL_STATIC_CONSTEXPR char const * name() { return Name; } }; \
  } } /* end namespaces */                                          \
  CEREAL_BIND_TO_ARCHIVES(T)

Registers a polymorphic type with cereal, giving it a user defined name

In some cases the default name used with CEREAL_REGISTER_TYPE (the name of the type) may not be suitable. This macro allows any name to be associated with the type. The name should be unique

◆ UNREGISTERED_POLYMORPHIC_EXCEPTION

#define UNREGISTERED_POLYMORPHIC_EXCEPTION	(	LoadSave,
		Name
	)

Value:

      throw cereal::Exception("Trying to " #LoadSave " an unregistered polymorphic type (" + Name + ").\n"                                          \
                              "Make sure your type is registered with CEREAL_REGISTER_TYPE and that the archive "                                   \
                              "you are using was included (and registered with CEREAL_REGISTER_ARCHIVE) prior to calling CEREAL_REGISTER_TYPE.\n"   \
                              "If your type is already registered and you still see this error, you may need to use CEREAL_REGISTER_DYNAMIC_INIT.");

Error message used for unregistered polymorphic types.

Function Documentation

◆ serialize_wrapper() [1/4]

template<class Archive , class T >

std::enable_if<(!traits::is_default_constructible< T >::value &&!traits::has_load_and_construct< T, Archive >::value)\|\|std::is_abstract< T >::value, bool >::type cereal::polymorphic_detail::serialize_wrapper	(	Archive &	,
		std::shared_ptr< T > &	,
		std::uint32_t const	nameid
	)

inline

Serialize a shared_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee.

This case is for when we can't actually construct the shared pointer. Normally this would be caught as the pointer itself is serialized, but since this is a polymorphic pointer, if we tried to serialize the pointer we'd end up back here recursively. So we have to catch the error here as well, if this was a polymorphic type serialized by its proper pointer type

◆ serialize_wrapper() [2/4]

template<class Archive , class T , class D >

std::enable_if<(!traits::is_default_constructible< T >::value &&!traits::has_load_and_construct< T, Archive >::value)\|\|std::is_abstract< T >::value, bool >::type cereal::polymorphic_detail::serialize_wrapper	(	Archive &	,
		std::unique_ptr< T, D > &	,
		std::uint32_t const	nameid
	)

inline

Serialize a unique_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee.

This case is for when we can't actually construct the unique pointer. Normally this would be caught as the pointer itself is serialized, but since this is a polymorphic pointer, if we tried to serialize the pointer we'd end up back here recursively. So we have to catch the error here as well, if this was a polymorphic type serialized by its proper pointer type

◆ serialize_wrapper() [3/4]

template<class Archive , class T >

std::enable_if<(traits::is_default_constructible< T >::value\|\|traits::has_load_and_construct< T, Archive >::value)&&!std::is_abstract< T >::value, bool >::type cereal::polymorphic_detail::serialize_wrapper	(	Archive &	ar,
		std::shared_ptr< T > &	ptr,
		std::uint32_t const	nameid
	)

inline

Serialize a shared_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee.

This check lets us try and skip doing polymorphic machinery if we can get away with using the derived class serialize function

Note that on MSVC 2013 preview, is_default_constructible<T> returns true for abstract classes with default constructors, but on clang/gcc this will return false. So we also need to check for that here.

◆ serialize_wrapper() [4/4]

template<class Archive , class T , class D >

std::enable_if<(traits::is_default_constructible< T >::value\|\|traits::has_load_and_construct< T, Archive >::value)&&!std::is_abstract< T >::value, bool >::type cereal::polymorphic_detail::serialize_wrapper	(	Archive &	ar,
		std::unique_ptr< T, D > &	ptr,
		std::uint32_t const	nameid
	)

inline

Serialize a unique_ptr if the 2nd msb in the nameid is set, and if we can actually construct the pointee.

This check lets us try and skip doing polymorphic machinery if we can get away with using the derived class serialize function

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CEREAL_FORCE_DYNAMIC_INIT

◆ CEREAL_REGISTER_DYNAMIC_INIT

◆ CEREAL_REGISTER_POLYMORPHIC_RELATION

◆ CEREAL_REGISTER_TYPE

◆ CEREAL_REGISTER_TYPE_WITH_NAME

◆ UNREGISTERED_POLYMORPHIC_EXCEPTION

Function Documentation

◆ serialize_wrapper() [1/4]

◆ serialize_wrapper() [2/4]

◆ serialize_wrapper() [3/4]

◆ serialize_wrapper() [4/4]