MIRA
Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
ConcreteBinarySerializer< BinaryStream, BinaryFormatVersion, Buffered > Class Template Reference

#include <serialization/BinarySerializer.h>

Inheritance diagram for ConcreteBinarySerializer< BinaryStream, BinaryFormatVersion, Buffered >:
Inheritance graph
[legend]

Public Types

typedef BinaryBufferOstream SimpleStreamType
 
typedef boost::mpl::bool_< false > useHumanReadableIDs
 
typedef Format::requireReflectBarriers requireReflectBarriers
 
typedef Format::ReflectState ReflectState
 
typedef Format::VersionType VersionType
 
typedef Base::AcceptDesiredVersion AcceptDesiredVersion
 
typedef BinarySerializerTag Tag
 
typedef boost::mpl::bool_< true > isReadOnly
 
typedef boost::mpl::bool_< true > isObjectTrackingSupported
 
typedef Base::ClassVersionMap ClassVersionMap
 
enum  PointerType { NULL_POINTER = 0, POINTER_REFERENCE = 1, NORMAL_POINTER = 2, POLYMORPHIC_POINTER = 3 }
 Pointer type that is stored as 1-byte marker before storing the pointer. More...
 
typedef BinaryStream StreamType
 The type of stream the serializer writes to (the actual output stream here) More...
 

Public Member Functions

 ConcreteBinarySerializer (typename BinaryStream::streambuffer_pointer buffer)
 Create a new binary serializer based on the specified stream buffer object. More...
 
 ConcreteBinarySerializer (BinaryStream &stream)
 Create a new binary serializer and assign it to the specified binary output stream. More...
 
template<typename T >
void serialize (const T &value, bool enableTypeCheck=true)
 Provides a special serialize interface for the BinarySerializer. More...
 
template<typename T >
VersionType version (VersionType version, const T *caller=NULL)
 
 MIRA_DEPRECATED ("Please call as version<MyType>(v) or version(v, this)", VersionType version(VersionType version))
 
template<typename T >
VersionType version (VersionType version, AcceptDesiredVersion, const T *caller=NULL)
 
void pointerReference (int referencedObjectID)
 
void pointerWithoutClassType ()
 
void pointerWithClassType (const std::string &type)
 
void pointerNull ()
 
template<typename T >
void invokeOverwrite (T &object)
 
template<typename T >
void invokeOverwrite (serialization::PlainArray< T > &array)
 Specialized for PlainArray to implement an optimized variant for serializing array, if possible (i.e. More...
 
template<typename T >
void write (const T *data, std::size_t count)
 
void registerCodec (BinarySerializerCodecPtr codec)
 Registers the specified codec instance in this binary serializer. More...
 
void unregisterCodec (BinarySerializerCodecPtr codec)
 Removes a previously registered codec. More...
 
template<typename T >
bool hasCodec () const
 Returns true, of there is a codec for the specified type T. More...
 
template<typename T >
bool codec (const T &obj)
 Encodes the specified object containing the data using a matching codec. More...
 
VersionType version (VersionType version, const T *caller=NULL)
 
VersionType version (VersionType version, AcceptDesiredVersion, const T *caller=NULL)
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)", VersionType requireVersion(VersionType version, VersionType minVersion))
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v) or requireVersion(v, this)", void requireVersion(VersionType requiredVersion))
 
void desireClassVersions (const ClassVersionMap &versions)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void serialize (const std::string &name, const T &value, const std::string &comment="")
 Serializes the specified object value under the given name. More...
 
void trackObject (T &member)
 
void pointer (T *&pointer)
 
void pointerNormal (T *&pointer, int typeId)
 
void pointerPolymorphic (T *&pointer, int typeId)
 
void pointerAbstract (T *&pointer, int typeId)
 
void pushObjectTrackingStore ()
 
void popObjectTrackingStore ()
 
void member (const char *name, T &member, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const std::string &id, T &member, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const T &member, Setter< T > setter, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, T &member, const char *comment, const T &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, T &member, const char *comment, const U &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const T &member, Setter< T > setter, const char *comment, const T &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const T &member, Setter< T > setter, const char *comment, const U &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const T &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const U &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const std::string &id, T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const T &member, Setter< T > setter, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, T &member, const char *comment, const T &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, T &member, const char *comment, const U &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const T &member, Setter< T > setter, const char *comment, const T &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const T &member, Setter< T > setter, const char *comment, const U &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const T &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const U &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void delegate (T &member, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Delegates the serialization directly to the specified member, without creating a separate compound for the current object. More...
 
void delegate (const T &member, Setter< T > setter, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Delegates the serialization directly to the specified member, without creating a separate compound for the current object. More...
 
void delegate (Getter< T > getter, Setter< T > setter, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Delegates the serialization directly to the specified member, without creating a separate compound for the current object. More...
 
const ReflectMemberMetagetCurrentMemberMeta () const
 Returns the meta-information of the current member that is reflected. More...
 
const std::string & getCurrentMemberFullID () const
 Returns the full human readable object id / name of the current member being reflected. More...
 
void invokeMember (T &member, const ReflectMemberMeta &meta)
 Is called to invoke this Reflector on the member with the specified meta information. More...
 
void invokeMemberOverwrite (T &member, const ReflectMemberMeta &meta)
 The actual invokeMember implementation that is called from invokeMember(). More...
 
void invokePointerObject (T &member)
 Is called to reflect objects of pointers. More...
 
void invokeMemberWithoutDefault (T &member, const ReflectMemberMeta &meta)
 Delegates to invokeMember() and rethrows any occurring XMemberNotFound exception as XIO exception. More...
 
void invokeMemberWithDefault (T &member, const ReflectMemberMeta &meta, const U &defaultValue)
 Delegates to invokeMember() and handles any occurring XMemberNotFound exception by setting the member to the given default value. More...
 
void invokeMemberWithDefault (T &member, const ReflectMemberMeta &meta, const serialization::IgnoreMissing &defaultValue)
 Delegates to invokeMember() and handles any occurring XMemberNotFound exception by ignoring the exception and hence the missing member, as indicated by IgnoreMissing as default value. More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void requireVersion (VersionType requiredVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, AcceptDesiredVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void requireVersion (VersionType requiredVersion, AcceptDesiredVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void reflectBase (Base &base)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void postReflect (const ReflectState &)
 See preReflect for documentation. More...
 
void reassign (typename BinaryStream::streambuffer_pointer buffer)
 Reassigns the specified stream buffer to this (serializer). More...
 
Visiting methods
template<typename T >
void atomic (T &member)
 
Format::ReflectState preReflect (const char *context="")
 
void postReflect (const typename Format::ReflectState &prev)
 
Optional Class Versioning.

These visiting methods may be supported by different reflectors like the RecursiveMemberReflector and the RPCMethodReflector, etc.

Note
Specifying versions for serialized classes is optional.
requireVersion() and version() currently are supported by serialization reflectors only.
VersionType version (VersionType version, const T *caller=NULL)
 Specifies the current class version and returns the version found in the data stream. More...
 
VersionType version (VersionType version, AcceptDesiredVersion, const T *caller=NULL)
 Extension of version() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself. More...
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)", VersionType requireVersion(VersionType version, VersionType minVersion))
 Deprecated 'anonymous' (no type) requireVersion(). More...
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v) or requireVersion(v, this)", VersionType requireVersion(VersionType version))
 Deprecated 'anonymous' (no type) requireVersion(). More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, const T *caller=NULL)
 Same as above, but allows to specify a minimum supported version, and throws XIO if the minimum version requirement is not met. More...
 
void requireVersion (VersionType version, const T *caller=NULL)
 Specifies the current class version, which is also the minimum (and therefore only) version accepted (therefore, no need to return a version number). More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, AcceptDesiredVersion, const T *caller=NULL)
 Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself. More...
 
void requireVersion (VersionType version, AcceptDesiredVersion, const T *caller=NULL)
 Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than it one it specifies itself. More...
 
Visiting methods that are called by the RecursiveMemberReflector

while reflecting the members

void enumeration (T &member)
 Is called by the if the member is an enumeration. More...
 
void object (T &member)
 Is called for each complex object. More...
 
void collection (T &member)
 Is called for each complex object or array, where the IsCollection<T> trait is true_type. More...
 
Methods for reflecting members

These visiting methods are supported by the RecursiveMemberReflector.

void roproperty (const char *name, const T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 A property that just reflects a runtime state of the object and can be displayed but not altered. More...
 
void roproperty (const char *name, const std::string &id, const T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Same as above, with an extra parameter for specifying the id explicitly if it differs from name. More...
 
void roproperty (const char *name, Getter< T > getter, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Same as above, with a special getter method for reading the member. More...
 
void itemName (const std::string &name)
 If the currently reflected object is an item within a collection, this allows to specify an explicit name for that item. More...
 
Methods for reflecting RPC (remote procedure call) methods
void interface (const char *name)
 Indicates that the class implements the specified RPC interface. More...
 
void method (const char *name, Method method, const char *comment, const char *paramName, const char *paramDescription, P paramSampleValue,...)
 Specifies that the class that is reflected provides a service through the specified static member function or free function. More...
 
void method (const char *name, Method method, Class *object, const char *comment, const char *paramName, const char *paramDescription, P paramSampleValue,...)
 Specifies that the class that is reflected provides a service through the specified non-static member function. More...
 
void method (const char *name, Method method, const char *comment, const char *paramName, const char *paramDescription, P paramSampleValue,...)
 Specifies that the class that is reflected provides a service through the specified function wrapper. More...
 

Static Public Member Functions

static int forcedSerializeVersion ()
 Returns either the version number from value of environment variable 'MIRA_FORCE_SERIALIZE_VERSION', or -1 (= do not force a version). More...
 
static void registerClass ()
 Registers a new polymorphic class at the PolymorphPointerReflector. More...
 
static void unregisterClass ()
 Unregisters the class. More...
 
static bool isReflectedAsPointer ()
 For internal use only: Returns true, if the type T is ever reflected as pointer within the current translation unit (C file). More...
 
static bool usesHumanReadableIDs ()
 Returns true, if the concrete derived Reflector supports human readable IDs. More...
 

Protected Types

typedef std::set< AObject > ObjectSet
 
typedef std::map< int, std::string > ObjectIDToNameMap
 
typedef std::pair< ObjectSet, ObjectIDToNameMapTrackingState
 

Protected Member Functions

VersionType queryDesiredClassVersion (VersionType version, const std::string &type, bool acceptDesiredVersion=false)
 
VersionType queryDesiredClassVersion (VersionType version, bool acceptDesiredVersion=false)
 
bool isTrackingEnabled () const
 Returns true, if object tracking is enabled for the type T. More...
 
const std::string & getHumanReadableFullID (int objectID) const
 Returns the full human readable object id / name for the given internal objectID. More...
 
void invokeTrackObject (T &member)
 tracks the given object (if pointer tracking is enabled for type T) More...
 
ConcreteBinarySerializer< BinaryStream, BinaryFormatVersion, Buffered > * This ()
 "Curiously recurring template pattern" (CRTP). More...
 
void invoke (T &object)
 Invokes this reflector on the specified object. More...
 
void flushBuffer ()
 Flush stream buffer (write to underlying stream), nothing to do for unbuffered access. More...
 
BinaryStream & stream ()
 Get access to the read/write stream (direct reference to underlying stream). More...
 

Static Protected Member Functions

static int checkForcedVersion (const std::string &variable)
 

Protected Attributes

ClassVersionMap mDesiredClassVersions
 
ObjectSet mObjects
 
ObjectIDToNameMap mObjectIDToName
 
std::stack< TrackingStatemTrackingStack
 

Static Protected Attributes

static constexpr auto MIRA_REFLECTOR_TOPLEVEL_NAME
 Use this when a reflector needs to choose a name for serializing an object. More...
 

Member Typedef Documentation

◆ SimpleStreamType

◆ useHumanReadableIDs

typedef boost::mpl::bool_<false> useHumanReadableIDs

◆ requireReflectBarriers

typedef Format::requireReflectBarriers requireReflectBarriers

◆ ReflectState

typedef Format::ReflectState ReflectState

◆ VersionType

typedef Format::VersionType VersionType

◆ AcceptDesiredVersion

typedef Base::AcceptDesiredVersion AcceptDesiredVersion

◆ Tag

typedef BinarySerializerTag Tag
inherited

◆ isReadOnly

typedef boost::mpl::bool_<true> isReadOnly
inherited

◆ isObjectTrackingSupported

typedef boost::mpl::bool_<true> isObjectTrackingSupported
inherited

◆ ClassVersionMap

typedef Base::ClassVersionMap ClassVersionMap
inherited

◆ ObjectSet

typedef std::set<AObject> ObjectSet
protectedinherited

◆ ObjectIDToNameMap

typedef std::map<int, std::string> ObjectIDToNameMap
protectedinherited

◆ TrackingState

typedef std::pair<ObjectSet, ObjectIDToNameMap> TrackingState
protectedinherited

◆ StreamType

typedef BinaryStream StreamType
inherited

The type of stream the serializer writes to (the actual output stream here)

Member Enumeration Documentation

◆ PointerType

enum PointerType
inherited

Pointer type that is stored as 1-byte marker before storing the pointer.

Note
For internal use within BinarySerializer and BinaryDeserializer only.
Enumerator
NULL_POINTER 
POINTER_REFERENCE 
NORMAL_POINTER 
POLYMORPHIC_POINTER 

Constructor & Destructor Documentation

◆ ConcreteBinarySerializer() [1/2]

ConcreteBinarySerializer ( typename BinaryStream::streambuffer_pointer  buffer)
inline

Create a new binary serializer based on the specified stream buffer object.

The stream buffer object must be specified as pointer. If you use this class with BinaryStlOstream, then the stream buffer object must be of the type std::basic_streambuf<_CharT, _Traits> (see corresponding documentation of STL streams). If you use this class with BinaryBufferOstream, the stream buffer object must be of the type std::vector<char>.

Note
: The stream buffer object must exist as long as the serializer is used.

◆ ConcreteBinarySerializer() [2/2]

ConcreteBinarySerializer ( BinaryStream &  stream)
inline

Create a new binary serializer and assign it to the specified binary output stream.

Note
: The stream object must exist as long as the serializer is used.

Member Function Documentation

◆ serialize() [1/2]

void serialize ( const T &  value,
bool  enableTypeCheck = true 
)
inline

Provides a special serialize interface for the BinarySerializer.

It allows to skip the name, since the name is not used by the binary serializer. Instead an optional second parameter is provided that allows to enable an automatic type check. If the type check is enabled the serializer will write the full typename into the stream before serializing the content. When deserializing the data, this type information is used to ensure that the data types match (type safety). If the type check is enabled here, it also must be enabled in the corresponding deserialize() call of the BinaryDeserializer and vice versa.

◆ version() [1/6]

VersionType version ( VersionType  version,
const T *  caller = NULL 
)
inline

◆ MIRA_DEPRECATED() [1/5]

MIRA_DEPRECATED ( "Please call as version<MyType>(v) or version(v, this)"  ,
VersionType   versionVersionType version 
)
inline

◆ version() [2/6]

VersionType version ( VersionType  version,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inline

◆ atomic()

void atomic ( T &  member)
inline

◆ preReflect()

Format::ReflectState preReflect ( const char *  context = "")
inline

◆ postReflect() [1/2]

void postReflect ( const typename Format::ReflectState &  prev)
inline

◆ pointerReference()

void pointerReference ( int  referencedObjectID)
inline

◆ pointerWithoutClassType()

void pointerWithoutClassType ( )
inline

◆ pointerWithClassType()

void pointerWithClassType ( const std::string &  type)
inline

◆ pointerNull()

void pointerNull ( )
inline

◆ invokeOverwrite() [1/2]

void invokeOverwrite ( T &  object)
inline

◆ invokeOverwrite() [2/2]

void invokeOverwrite ( serialization::PlainArray< T > &  array)
inline

Specialized for PlainArray to implement an optimized variant for serializing array, if possible (i.e.

if object tracking is disabled and each value in the array can be serialized bitwise).

◆ write()

void write ( const T *  data,
std::size_t  count 
)
inline

◆ registerCodec()

void registerCodec ( BinarySerializerCodecPtr  codec)
inline

Registers the specified codec instance in this binary serializer.

Afterwards, the codec can be used by objects that are serialized and that support the codec. Note, that only one codec can be registered for each datatype, otherwise a XLogical exception will be thrown.

◆ unregisterCodec()

void unregisterCodec ( BinarySerializerCodecPtr  codec)
inline

Removes a previously registered codec.

◆ hasCodec()

bool hasCodec ( ) const
inline

Returns true, of there is a codec for the specified type T.

In this case, the encode method can be used to encode the data using the codec.

◆ codec()

bool codec ( const T &  obj)
inline

Encodes the specified object containing the data using a matching codec.

The encoded data will be written directly into the binary output. If no codec was found, false is returned, and the caller must serialize the data manually without codec (in this case "NULL" is written as codec fourcc into the binary stream).

◆ version() [3/6]

VersionType version ( VersionType  version,
const T *  caller = NULL 
)
inlineinherited

◆ version() [4/6]

VersionType version ( VersionType  version,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

◆ version() [5/6]

VersionType version ( VersionType  version,
const T *  caller = NULL 
)
inlineinherited

Specifies the current class version and returns the version found in the data stream.

During serialization (read-only reflector), the specified version usually is stored as class version in the data stream. However, the serialized version can be overridden by setting a specific version for a certain class identifier, using desireClassVersions(). In that case, version() may return a different value than specified, and the class' reflect() method must implement reflection according to that version number. During deserialization (write-only reflector), the reflector reads the version found in the data stream and returns it. Providing the type of the caller enables defining separate version numbers for all base classes of an inherited type. Each class in the inheritance hierarchy can store and retrieve a version number independently of all its bases or sub-classes (assuming reflect() calls the reflect() method of the base class using reflectBase()). The type of the caller is also required to look up whether a specific version is desired (see desireClassVersions()). The sole purpose of the 'caller' parameter is to enable automatic deduction of the template parameter T. It can be omitted when T is given explicitly.

Usage:

template<typename Reflector>
void reflect(Reflector& r)
{
VersionType v = r.version(3, this); // specifies current version 3
// in serialization case, normally returns v=3, unless
// configured differently using desireClassVersions()
// in deserialization case, returns the version read from serialized data
// (or throws XIO if that is higher than 3, i.e. incompatible)
r.member("X", x, "");
if (version >= 2)
r.member("X2", x2, "");
if (version == 3)
...
}
Note
Specifying versions for serialized classes is optional.
requireVersion() and version() currently are supported by serialization reflectors only

◆ version() [6/6]

VersionType version ( VersionType  version,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

Extension of version() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself.

◆ MIRA_DEPRECATED() [2/5]

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)"  ,
VersionType  requireVersionVersionType version, VersionType minVersion 
)
inlineinherited

◆ MIRA_DEPRECATED() [3/5]

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v) or requireVersion(v, this)"  ,
void  requireVersionVersionType requiredVersion 
)
inlineinherited

◆ MIRA_DEPRECATED() [4/5]

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)"  ,
VersionType  requireVersionVersionType version, VersionType minVersion 
)
inlineinherited

Deprecated 'anonymous' (no type) requireVersion().

◆ MIRA_DEPRECATED() [5/5]

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v) or requireVersion(v, this)"  ,
VersionType  requireVersionVersionType version 
)
inlineinherited

Deprecated 'anonymous' (no type) requireVersion().

◆ forcedSerializeVersion()

static int forcedSerializeVersion ( )
inlinestaticinherited

Returns either the version number from value of environment variable 'MIRA_FORCE_SERIALIZE_VERSION', or -1 (= do not force a version).

◆ desireClassVersions()

void desireClassVersions ( const ClassVersionMap versions)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

◆ queryDesiredClassVersion() [1/2]

VersionType queryDesiredClassVersion ( VersionType  version,
const std::string &  type,
bool  acceptDesiredVersion = false 
)
inlineprotectedinherited

◆ queryDesiredClassVersion() [2/2]

VersionType queryDesiredClassVersion ( VersionType  version,
bool  acceptDesiredVersion = false 
)
inlineprotectedinherited

◆ serialize() [2/2]

void serialize ( const std::string &  name,
const T &  value,
const std::string &  comment = "" 
)
inlineinherited

Serializes the specified object value under the given name.

If you overwrite this method in a derived class you usually MUST call this method of the base class.

◆ trackObject()

void trackObject ( T &  member)
inlineinherited

◆ pointer()

void pointer ( T *&  pointer)
inlineinherited

◆ pointerNormal()

void pointerNormal ( T *&  pointer,
int  typeId 
)
inlineinherited

◆ pointerPolymorphic()

void pointerPolymorphic ( T *&  pointer,
int  typeId 
)
inlineinherited

◆ pointerAbstract()

void pointerAbstract ( T *&  pointer,
int  typeId 
)
inlineinherited

◆ isTrackingEnabled()

bool isTrackingEnabled ( ) const
inlineprotectedinherited

Returns true, if object tracking is enabled for the type T.

◆ pushObjectTrackingStore()

void pushObjectTrackingStore ( )
inlineinherited

◆ popObjectTrackingStore()

void popObjectTrackingStore ( )
inlineinherited

◆ getHumanReadableFullID()

const std::string& getHumanReadableFullID ( int  objectID) const
inlineprotectedinherited

Returns the full human readable object id / name for the given internal objectID.

The human readable id only is available, if the Reflector has set useHumanReadableIDs to true.

◆ member() [1/10]

void member ( const char *  name,
T &  member,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [2/10]

void member ( const char *  name,
const std::string &  id,
T &  member,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [3/10]

void member ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [4/10]

void member ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [5/10]

void member ( const char *  name,
T &  member,
const char *  comment,
const T &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [6/10]

void member ( const char *  name,
T &  member,
const char *  comment,
const U &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [7/10]

void member ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [8/10]

void member ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [9/10]

void member ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ member() [10/10]

void member ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [1/10]

void property ( const char *  name,
T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [2/10]

void property ( const char *  name,
const std::string &  id,
T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [3/10]

void property ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [4/10]

void property ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [5/10]

void property ( const char *  name,
T &  member,
const char *  comment,
const T &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [6/10]

void property ( const char *  name,
T &  member,
const char *  comment,
const U &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [7/10]

void property ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [8/10]

void property ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [9/10]

void property ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ property() [10/10]

void property ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

◆ delegate() [1/3]

void delegate ( T &  member,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Delegates the serialization directly to the specified member, without creating a separate compound for the current object.

This method usually is used together with IsTransparentSerializable. Note: only one call of delegate is allowed within one reflect method.

◆ delegate() [2/3]

void delegate ( const T &  member,
Setter< T >  setter,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Delegates the serialization directly to the specified member, without creating a separate compound for the current object.

This method usually is used together with IsTransparentSerializable. Note: only one call of delegate is allowed within one reflect method.

◆ delegate() [3/3]

void delegate ( Getter< T >  getter,
Setter< T >  setter,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Delegates the serialization directly to the specified member, without creating a separate compound for the current object.

This method usually is used together with IsTransparentSerializable. Note: only one call of delegate is allowed within one reflect method.

◆ enumeration()

void enumeration ( T &  member)
inlineinherited

Is called by the if the member is an enumeration.

(Type A2)

As for all the other visit-methods the parameter is a reference to the actual visited/reflected member.

The default implementation casts the enum to an uint32 and calls atomic().

◆ object()

void object ( T &  member)
inlineinherited

Is called for each complex object.

See documentation of RecursiveMemberReflectorBase class for detailed calling sequences. If you overwrite this method in a derived class you should call the method of the Base class to allow recursive reflection of the complex object's members.

◆ collection()

void collection ( T &  member)
inlineinherited

Is called for each complex object or array, where the IsCollection<T> trait is true_type.

The default implementation calls object().

◆ registerClass()

static void registerClass ( )
inlinestaticinherited

Registers a new polymorphic class at the PolymorphPointerReflector.

Each RecursiveMemberReflector only is able to process pointers to polymorphic classes that are registered using this method.

The MIRA_CLASS_SERIALIZATION macro provides a simple mechanism to register a class in all known MemberReflectors and calls their registerClass() method. If you implement a new MemberReflector you should modify the MIRA_CLASS_SERIALIZATION macro and add your reflector there.

See also
MIRA_CLASS_SERIALIZATION

◆ unregisterClass()

static void unregisterClass ( )
inlinestaticinherited

Unregisters the class.

The MIRA_CLASS_SERIALIZATION macro provides a simple mechanism to register a class in all known MemberReflectors and calls their registerClass() method. If you implement a new MemberReflector you should modify the MIRA_CLASS_SERIALIZATION macro and add your reflector there.

See also
MIRA_CLASS_SERIALIZATION

◆ getCurrentMemberMeta()

const ReflectMemberMeta& getCurrentMemberMeta ( ) const
inlineinherited

Returns the meta-information of the current member that is reflected.

◆ getCurrentMemberFullID()

const std::string& getCurrentMemberFullID ( ) const
inlineinherited

Returns the full human readable object id / name of the current member being reflected.

This method must not be called if the Reflector has set useHumanReadableIDs to false. If it is called anyway we will assert here.

◆ isReflectedAsPointer()

static bool isReflectedAsPointer ( )
inlinestaticinherited

For internal use only: Returns true, if the type T is ever reflected as pointer within the current translation unit (C file).

◆ invokeTrackObject()

void invokeTrackObject ( T &  member)
inlineprotectedinherited

tracks the given object (if pointer tracking is enabled for type T)

◆ invokeMember()

void invokeMember ( T &  member,
const ReflectMemberMeta meta 
)
inlineinherited

Is called to invoke this Reflector on the member with the specified meta information.

This method delegates the call to the most derived invokeMemberOverwrite() method that may be overwritten in subclasses.

Note
Usually, the RecursiveMemberReflector should be invoked using this invokeMember() method instead of the invoke() method of the ReflectorInterface base class. The invoke() method is called internally by the RecursiveMemberReflector.

◆ invokeMemberOverwrite()

void invokeMemberOverwrite ( T &  member,
const ReflectMemberMeta meta 
)
inlineinherited

The actual invokeMember implementation that is called from invokeMember().

This method may be overwritten in derived classes to add additional functionality, however, you should always call this implementation of the base class.

◆ invokePointerObject()

void invokePointerObject ( T &  member)
inlineinherited

Is called to reflect objects of pointers.

They will use the same meta as the pointer

◆ invokeMemberWithoutDefault()

void invokeMemberWithoutDefault ( T &  member,
const ReflectMemberMeta meta 
)
inlineinherited

Delegates to invokeMember() and rethrows any occurring XMemberNotFound exception as XIO exception.

◆ invokeMemberWithDefault() [1/2]

void invokeMemberWithDefault ( T &  member,
const ReflectMemberMeta meta,
const U &  defaultValue 
)
inlineinherited

Delegates to invokeMember() and handles any occurring XMemberNotFound exception by setting the member to the given default value.

◆ invokeMemberWithDefault() [2/2]

void invokeMemberWithDefault ( T &  member,
const ReflectMemberMeta meta,
const serialization::IgnoreMissing defaultValue 
)
inlineinherited

Delegates to invokeMember() and handles any occurring XMemberNotFound exception by ignoring the exception and hence the missing member, as indicated by IgnoreMissing as default value.

The value of the member remains unchanged.

◆ requireVersion() [1/8]

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

◆ requireVersion() [2/8]

void requireVersion ( VersionType  requiredVersion,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

◆ requireVersion() [3/8]

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

◆ requireVersion() [4/8]

void requireVersion ( VersionType  requiredVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

◆ requireVersion() [5/8]

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
const T *  caller = NULL 
)
inlineinherited

Same as above, but allows to specify a minimum supported version, and throws XIO if the minimum version requirement is not met.

Calls version() internally.

Usage:

template<typename Reflector>
void reflect(Reflector& r)
{
VersionType v = r.requireVersion(4, 2, this); // specifies version 4,
// requires version 2 or higher
if(v==3) { // handle reading version 3
...
} else // only versions 2 or 4 remain
...
}
Note
Specifying versions for serialized classes is optional.
requireVersion() and version() currently are supported by serialization reflectors only

◆ requireVersion() [6/8]

void requireVersion ( VersionType  version,
const T *  caller = NULL 
)
inlineinherited

Specifies the current class version, which is also the minimum (and therefore only) version accepted (therefore, no need to return a version number).

See above.

◆ requireVersion() [7/8]

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself.

◆ requireVersion() [8/8]

void requireVersion ( VersionType  version,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than it one it specifies itself.

◆ reflectBase()

void reflectBase ( Base &  base)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

◆ This()

ConcreteBinarySerializer< BinaryStream, BinaryFormatVersion, Buffered > * This ( )
inlineprotectedinherited

"Curiously recurring template pattern" (CRTP).

Safely casts this into Derived. This is safe since when implementing derived class their type is passed as template parameter.

See Wikipedia for more details on CRTP if necessary!

◆ invoke()

void invoke ( T &  object)
inlineprotectedinherited

Invokes this reflector on the specified object.

This is like calling object.reflect(*this). However, this automatically examines if the class T contains a reflect method. In this case it calls the intrusive reflect method, otherwise it uses the non-intrusive reflect method.

◆ roproperty() [1/3]

void roproperty ( const char *  name,
const T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

A property that just reflects a runtime state of the object and can be displayed but not altered.

◆ roproperty() [2/3]

void roproperty ( const char *  name,
const std::string &  id,
const T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Same as above, with an extra parameter for specifying the id explicitly if it differs from name.

◆ roproperty() [3/3]

void roproperty ( const char *  name,
Getter< T >  getter,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Same as above, with a special getter method for reading the member.

See also
Getters and Setters

◆ itemName()

void itemName ( const std::string &  name)
inlineinherited

If the currently reflected object is an item within a collection, this allows to specify an explicit name for that item.

This currently is interpreted by the PropertySerializer only.

◆ interface()

void interface ( const char *  name)
inlineinherited

Indicates that the class implements the specified RPC interface.

If you indicate that your class implements the specified interface by calling this method in your reflect method, there is an implicit contract that your class provides all methods that are defined by that interface.

◆ method() [1/3]

void method ( const char *  name,
Method  method,
const char *  comment,
const char *  paramName,
const char *  paramDescription,
paramSampleValue,
  ... 
)
inherited

Specifies that the class that is reflected provides a service through the specified static member function or free function.

The method will then be available for RPC calls. For each method its name (used to identify the method in RPC calls) and a comment that describes the method must be specified.

Parameters
nameThe name of the method (used for calling it)
methodThe static member function (or free function) that implements the method
commentA comment that describes the method
paramNameOptional additional argument(s) for the names of the method's parameters
paramDescriptionOptional additional argument(s) for the descriptions of the method's parameters.
paramSampleValueOptional additional argument(s) providing a sample value for each parameter. These are not default values, they are only used for documentation purpose, and should mainly serve to illustrate notation.

The optional parameter documentation arguments must be either a sequence of pairs of const char* values or a sequence of triplets, where each third value is a value of the respective method parameter's type. (name and description must both be provided, for all parameters or for none, and if sample values are to be added, they also need to be added for all parameters).

Examples:

r.method("myMethod1", myStaticMethod1, "static method that does something");
r.method("myMethod2", myStaticMethod2, "static method that does something else",
"x", "1st parameter", "y", "2nd parameter");
r.method("myMethod3", myStaticMethod3, "yet another static method"
"a", "parameter 1", ParamType1(...), "b", "parameter b", ParamType2(...));

◆ method() [2/3]

void method ( const char *  name,
Method  method,
Class object,
const char *  comment,
const char *  paramName,
const char *  paramDescription,
paramSampleValue,
  ... 
)
inherited

Specifies that the class that is reflected provides a service through the specified non-static member function.

The method will then be available for RPC calls. For each method its name (used to identify the method in RPC calls) and a comment that describes the method must be specified.

Parameters
nameThe name of the method (used for calling it)
methodThe non-static member function (const or non-const) that implements the method
objectA pointer to the object on which the function is called (usually "this")
commentA comment that describes the method
paramNameOptional additional argument(s) for the names of the method's parameters
paramDescriptionOptional additional argument(s) for the descriptions of the method's parameters.
paramSampleValueOptional additional argument(s) providing a sample value for each parameter.

See above for documentation of optional parameter documentation arguments.

Example:

r.method("myMethod2", &MyClass::myMethod, this, "a non-static method");

◆ method() [3/3]

void method ( const char *  name,
Method  method,
const char *  comment,
const char *  paramName,
const char *  paramDescription,
paramSampleValue,
  ... 
)
inherited

Specifies that the class that is reflected provides a service through the specified function wrapper.

The method will then be available for RPC calls. For each method its name (used to identify the method in RPC calls) and a comment that describes the method must be specified.

Parameters
nameThe name of the method (used for calling it)
methodThe function wrapper object that implements the method, e.g. created using boost::bind
commentA comment that describes the method
paramNameOptional additional argument(s) for the names of the method's parameters
paramDescriptionOptional additional argument(s) for the descriptions of the method's parameters.
paramSampleValueOptional additional argument(s) providing a sample value for each parameter.

See above for documentation of optional parameter documentation arguments.

Example:

r.method("myMethod3", boost::bind(&MyClass::myMethod, this, 1.23, 4, _1), "a function wrapper");

◆ usesHumanReadableIDs()

static bool usesHumanReadableIDs ( )
inlinestaticinherited

Returns true, if the concrete derived Reflector supports human readable IDs.

The return value of this method is known at compile time and hence the compiler is able to optimize the code depending on that value.

◆ postReflect() [2/2]

void postReflect ( const ReflectState &  )
inlineinherited

See preReflect for documentation.

◆ checkForcedVersion()

static int checkForcedVersion ( const std::string &  variable)
inlinestaticprotectedinherited

◆ flushBuffer()

void flushBuffer ( )
inlineprotectedinherited

Flush stream buffer (write to underlying stream), nothing to do for unbuffered access.

◆ reassign()

void reassign ( typename BinaryStream::streambuffer_pointer  buffer)
inlineinherited

Reassigns the specified stream buffer to this (serializer).

The stream buffer usually is specified in the constructor. This method can be used to change the assigned buffer.

◆ stream()

BinaryStream& stream ( )
inlineprotectedinherited

Get access to the read/write stream (direct reference to underlying stream).

Member Data Documentation

◆ mDesiredClassVersions

ClassVersionMap mDesiredClassVersions
protectedinherited

◆ mObjects

ObjectSet mObjects
protectedinherited

◆ mObjectIDToName

ObjectIDToNameMap mObjectIDToName
protectedinherited

◆ mTrackingStack

std::stack<TrackingState> mTrackingStack
protectedinherited

◆ MIRA_REFLECTOR_TOPLEVEL_NAME

constexpr auto MIRA_REFLECTOR_TOPLEVEL_NAME
staticprotectedinherited

Use this when a reflector needs to choose a name for serializing an object.

Internally this is used to recognize it is not a name defined by the reflected object, but by the reflector.


The documentation for this class was generated from the following file: