/[svn]/libgig/trunk/src/Serialization.h
ViewVC logotype

Diff of /libgig/trunk/src/Serialization.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3156 by schoenebeck, Mon May 8 17:18:07 2017 UTC revision 3198 by schoenebeck, Sun May 21 12:46:05 2017 UTC
# Line 35  Line 35 
35  #include <vector>  #include <vector>
36  #include <map>  #include <map>
37  #include <time.h>  #include <time.h>
38    #include <stdarg.h>
39    
40    #ifndef __has_extension
41    # define __has_extension(x) 0
42    #endif
43    
44    #ifndef HAS_BUILTIN_TYPE_TRAITS
45    # if __cplusplus >= 201103L
46    #  define HAS_BUILTIN_TYPE_TRAITS 1
47    # elif ( __has_extension(is_class) && __has_extension(is_enum) )
48    #  define HAS_BUILTIN_TYPE_TRAITS 1
49    # elif ( __GNUC__ > 4 || ( __GNUC__ == 4 && __GNUC_MINOR__ >= 3 ) )
50    #  define HAS_BUILTIN_TYPE_TRAITS 1
51    # elif _MSC_VER >= 1400 /* MS Visual C++ 8.0 (Visual Studio 2005) */
52    #  define HAS_BUILTIN_TYPE_TRAITS 1
53    # elif __INTEL_COMPILER >= 1100
54    #  define HAS_BUILTIN_TYPE_TRAITS 1
55    # else
56    #  define HAS_BUILTIN_TYPE_TRAITS 0
57    # endif
58    #endif
59    
60    #if !HAS_BUILTIN_TYPE_TRAITS
61    # include <tr1/type_traits>
62    # define LIBGIG_IS_CLASS(type) std::tr1::__is_union_or_class<type>::value //NOTE: without compiler support we cannot distinguish union from class
63    #else
64    # define LIBGIG_IS_CLASS(type) __is_class(type)
65    #endif
66    
67  /** @brief Serialization / deserialization framework.  /** @brief Serialization / deserialization framework.
68   *   *
# Line 91  namespace Serialization { Line 119  namespace Serialization {
119    
120      typedef std::string String;      typedef std::string String;
121    
122        /** @brief Raw data stream of serialized C++ objects.
123         *
124         * This data type is used for the data stream as a result of serializing
125         * your C++ objects with Archive::serialize(), and for native raw data
126         * representation of individual serialized C/C++ objects, members and variables.
127         *
128         * @see Archive::rawData(), Object::rawData()
129         */
130      typedef std::vector<uint8_t> RawData;      typedef std::vector<uint8_t> RawData;
131    
132        /** @brief Abstract identifier for serialized C++ objects.
133         *
134         * This data type is used for identifying serialized C++ objects and members
135         * of your C++ objects. It is important to know that such an ID might not
136         * necessarily be unique. For example the ID of one C++ object might often
137         * be identical to the ID of the first member of that particular C++ object.
138         * That's why there is additionally the concept of an UID in this framework.
139         *
140         * @see UID
141         */
142      typedef void* ID;      typedef void* ID;
143    
144        /** @brief Version number data type.
145         *
146         * This data type is used for maintaining version number information of
147         * your C++ class implementations.
148         *
149         * @see Archive::setVersion() and Archive::setMinVersion()
150         */
151      typedef uint32_t Version;      typedef uint32_t Version;
152    
153      enum operation_t {      /** @brief To which time zone a certain timing information relates to.
154          OPERATION_NONE,       *
155          OPERATION_SERIALIZE,       * The constants in this enum type are used to define to which precise time
156          OPERATION_DESERIALIZE       * zone a time stamp relates to.
157      };       */
   
158      enum time_base_t {      enum time_base_t {
159          LOCAL_TIME,          LOCAL_TIME, ///< The time stamp relates to the machine's local time zone. Request a time stamp in local time if you want to present that time stamp to the end user.
160          UTC_TIME          UTC_TIME ///< The time stamp relates to "Greenwhich Mean Time" zone, also known as "Coordinated Universal Time". Request time stamp with UTC if you want to compare that time stamp with other time stamps.
161      };      };
162    
163        /** @brief Check whether data is a C/C++ @c enum type.
164         *
165         * Returns true if the supplied C++ variable or object is of a C/C++ @c enum
166         * type.
167         *
168         * @param data - the variable or object whose data type shall be checked
169         */
170      template<typename T>      template<typename T>
171      bool IsEnum(const T& data) {      bool IsEnum(const T& data) {
172            #if !HAS_BUILTIN_TYPE_TRAITS
173            return std::tr1::is_enum<T>::value;
174            #else
175          return __is_enum(T);          return __is_enum(T);
176            #endif
177      }      }
178    
179        /** @brief Check whether data is a C++ @c union type.
180         *
181         * Returns true if the supplied C++ variable or object is of a C/C++ @c union
182         * type. Note that the result of this function is only reliable if the C++
183         * compiler you are using has support for built-in type traits. If your C++
184         * compiler does not have built-in type traits support, then this function
185         * will simply return @c false on all your calls.
186         *
187         * @param data - the variable or object whose data type shall be checked
188         */
189      template<typename T>      template<typename T>
190      bool IsUnion(const T& data) {      bool IsUnion(const T& data) {
191            #if !HAS_BUILTIN_TYPE_TRAITS
192            return false; // without compiler support we cannot distinguish union from class
193            #else
194          return __is_union(T);          return __is_union(T);
195            #endif
196      }      }
197    
198        /** @brief Check whether data is a C/C++ @c struct or C++ @c class type.
199         *
200         * Returns true if the supplied C++ variable or object is of C/C++ @c struct
201         * or C++ @c class type. Note that if you are using a C++ compiler which
202         * does have built-in type traits support, then this function will also
203         * return @c true on C/C++ @c union types.
204         *
205         * @param data - the variable or object whose data type shall be checked
206         */
207      template<typename T>      template<typename T>
208      bool IsClass(const T& data) {      bool IsClass(const T& data) {
209            #if !HAS_BUILTIN_TYPE_TRAITS
210            return std::tr1::__is_union_or_class<T>::value; // without compiler support we cannot distinguish union from class
211            #else
212          return __is_class(T);          return __is_class(T);
213            #endif
214      }      }
215    
216      /*template<typename T>      /*template<typename T>
# Line 133  namespace Serialization { Line 223  namespace Serialization {
223          return __is_pod(T);          return __is_pod(T);
224      }*/      }*/
225    
226      /** @brief Unique identifier for one specific C++ object, member or fundamental variable.      /** @brief Unique identifier referring to one specific native C++ object, member, fundamental variable, or any other native C++ data.
227         *
228         * Reflects a unique identifier for one specific serialized C++ data, i.e.
229         * C++ class instance, C/C++ struct instance, member, primitive pointer,
230         * fundamental variables, or any other native C/C++ data originally being
231         * serialized.
232       *       *
233       * Reflects a unique identifier for one specific serialized C++ class       * A unique identifier is composed of an id (an identifier which is not
234       * instance, struct instance, member, primitive pointer, or fundamental       * necessarily unique) and a size. Since the underlying ID is derived from
235       * variables.       * the original C++ object's memory location, such an ID is not sufficient
236         * to distinguish a particular C++ object from the first member of that C++
237         * object, since both typically share the same memory address. So
238         * additionally the memory size of the respective object or member is
239         * bundled with UID objects to make them unique and distinguishable.
240       */       */
241      class UID {      class UID {
242      public:      public:
243          ID id;          ID id; ///< Abstract non-unique ID of the object or member in question.
244          size_t size;          size_t size; ///< Memory size of the object or member in question.
245    
246          bool isValid() const;          bool isValid() const;
247          operator bool() const { return isValid(); }          operator bool() const { return isValid(); } ///< Same as calling isValid().
248          //bool operator()() const { return isValid(); }          //bool operator()() const { return isValid(); }
249          bool operator==(const UID& other) const { return id == other.id && size == other.size; }          bool operator==(const UID& other) const { return id == other.id && size == other.size; }
250          bool operator!=(const UID& other) const { return id != other.id || size != other.size; }          bool operator!=(const UID& other) const { return id != other.id || size != other.size; }
251          bool operator<(const UID& other) const { return id < other.id || (id == other.id && size < other.size); }          bool operator<(const UID& other) const { return id < other.id || (id == other.id && size < other.size); }
252          bool operator>(const UID& other) const { return id > other.id || (id == other.id && size > other.size); }          bool operator>(const UID& other) const { return id > other.id || (id == other.id && size > other.size); }
253    
254            /** @brief Create an unique indentifier for a native C++ object/member/variable.
255             *
256             * Creates and returns an unique identifier for the passed native C++
257             * object, object member or variable. For the same C++ object/member/variable
258             * this function will always return the same UID. For all other ones,
259             * this function is guaranteed to return a different UID.
260             */
261          template<typename T>          template<typename T>
262          static UID from(const T& obj) {          static UID from(const T& obj) {
263              return Resolver<T>::resolve(obj);              return Resolver<T>::resolve(obj);
# Line 162  namespace Serialization { Line 268  namespace Serialization {
268          template<typename T>          template<typename T>
269          struct Resolver {          struct Resolver {
270              static UID resolve(const T& obj) {              static UID resolve(const T& obj) {
271                  return (UID) { (ID) &obj, sizeof(obj) };                  const UID uid = { (ID) &obj, sizeof(obj) };
272                    return uid;
273              }              }
274          };          };
275    
# Line 170  namespace Serialization { Line 277  namespace Serialization {
277          template<typename T>          template<typename T>
278          struct Resolver<T*> {          struct Resolver<T*> {
279              static UID resolve(const T* const & obj) {              static UID resolve(const T* const & obj) {
280                  return (UID) { (ID) obj, sizeof(*obj) };                  const UID uid = { (ID) obj, sizeof(*obj) };
281                    return uid;
282              }              }
283          };          };
284      };      };
285    
286      /**      /**
287       * Reflects an invalid UID and behaves similar to NULL as invalid value for       * Reflects an invalid UID and behaves similar to NULL as invalid value for
288       * pointer types.       * pointer types. All UID objects are first initialized with this value,
289         * and it essentially an all zero object.
290       */       */
291      extern const UID NO_UID;      extern const UID NO_UID;
292    
293        /** @brief Chain of UIDs.
294         *
295         * This data type is used for native C++ pointers. The first member of the
296         * UID chain is the unique identifier of the C++ pointer itself, then the
297         * following UIDs are the respective objects or variables the pointer is
298         * pointing to. The size (the amount of elements) of the UIDChain depends
299         * solely on the degree of the pointer type. For example the following C/C++
300         * pointer:
301         * @code
302         * int* pNumber;
303         * @endcode
304         * is an integer pointer of first degree. Such a pointer would have a
305         * UIDChain with 2 members: the first element would be the UID of the
306         * pointer itself, the second element of the chain would be the integer data
307         * that pointer is pointing to. In the following example:
308         * @code
309         * bool*** pppSomeFlag;
310         * @endcode
311         * That boolean pointer would be of third degree, and thus its UIDChain
312         * would have a size of 4 (elements).
313         *
314         * Accordingly a non pointer type like:
315         * @code
316         * float f;
317         * @endcode
318         * would yield in a UIDChain of size 1.
319         *
320         * Since however this serialization framework currently only supports
321         * pointers of first degree yet, all UIDChains are currently either of
322         * size 1 or 2, which might change in future though.
323         */
324      typedef std::vector<UID> UIDChain;      typedef std::vector<UID> UIDChain;
325    
326      // prototyping of private internal friend functions      // prototyping of private internal friend functions
# Line 190  namespace Serialization { Line 330  namespace Serialization {
330      static Object _popObjectBlob(const char*& p, const char* end);      static Object _popObjectBlob(const char*& p, const char* end);
331      static void _popPrimitiveValue(const char*& p, const char* end, Object& obj);      static void _popPrimitiveValue(const char*& p, const char* end, Object& obj);
332      static String _primitiveObjectValueToString(const Object& obj);      static String _primitiveObjectValueToString(const Object& obj);
333        //  |
334        template<typename T>
335        static T _primitiveObjectValueToNumber(const Object& obj);
336    
337      /** @brief Abstract reflection of a native C++ data type.      /** @brief Abstract reflection of a native C++ data type.
338       *       *
339       * Provides detailed information about a C++ data type, whether it is a       * Provides detailed information about a serialized C++ data type, whether
340       * fundamental C/C++ data type (like int, float, char, etc.) or custom       * it is a fundamental C/C++ data type (like @c int, @c float, @c char,
341       * defined data type like a C++ class, struct, enum, as well as other       * etc.) or custom defined data types like a C++ @c class, C/C++ @c struct,
342       * features of the data type like its native memory size and more.       * @c enum, as well as other features of the respective data type like its
343         * native memory size and more.
344         *
345         * All informations provided by this class are retrieved from the
346         * respective individual C++ objects, their members and other data when
347         * they are serialized, and all those information are stored with the
348         * serialized archive and its resulting data stream. Due to the availability
349         * of these extensive data type information within serialized archives, this
350         * framework is capable to use them in order to adapt its deserialization
351         * process upon subsequent changes to your individual C++ classes.
352       */       */
353      class DataType {      class DataType {
354      public:      public:
355          DataType();          DataType();
356          size_t size() const { return m_size; }          size_t size() const { return m_size; } ///< Returns native memory size of the respective C++ object or variable.
357          bool isValid() const;          bool isValid() const;
358          bool isPointer() const;          bool isPointer() const;
359          bool isClass() const;          bool isClass() const;
# Line 211  namespace Serialization { Line 363  namespace Serialization {
363          bool isBool() const;          bool isBool() const;
364          bool isEnum() const;          bool isEnum() const;
365          bool isSigned() const;          bool isSigned() const;
366          operator bool() const { return isValid(); }          operator bool() const { return isValid(); } ///< Same as calling isValid().
367          //bool operator()() const { return isValid(); }          //bool operator()() const { return isValid(); }
368          bool operator==(const DataType& other) const;          bool operator==(const DataType& other) const;
369          bool operator!=(const DataType& other) const;          bool operator!=(const DataType& other) const;
370          bool operator<(const DataType& other) const;          bool operator<(const DataType& other) const;
371          bool operator>(const DataType& other) const;          bool operator>(const DataType& other) const;
372          String asLongDescr() const;          String asLongDescr() const;
373          String baseTypeName() const { return m_baseTypeName; }          String baseTypeName() const;
374          String customTypeName() const { return m_customTypeName; }          String customTypeName(bool demangle = false) const;
375    
376            /** @brief Construct a DataType object for the given native C++ data.
377             *
378             * Use this function to create corresponding DataType objects for
379             * native C/C++ objects, members and variables.
380             *
381             * @param data - native C/C++ object/member/variable a DataType object
382             *               shall be created for
383             * @returns corresponding DataType object for the supplied native C/C++
384             *          object/member/variable
385             */
386          template<typename T>          template<typename T>
387          static DataType dataTypeOf(const T& data) {          static DataType dataTypeOf(const T& data) {
388              return Resolver<T>::resolve(data);              return Resolver<T>::resolve(data);
# Line 303  namespace Serialization { Line 465  namespace Serialization {
465       * serialized C++ object, like its C++ data type, offset of this member       * serialized C++ object, like its C++ data type, offset of this member
466       * within its containing data structure/class, its C++ member variable name       * within its containing data structure/class, its C++ member variable name
467       * and more.       * and more.
468         *
469         * Consider you defined the following user defined C/C++ @c struct type in
470         * your application:
471         * @code
472         * struct Foo {
473         *     int  a;
474         *     bool b;
475         *     double someValue;
476         * };
477         * @endcode
478         * Then @c a, @c b and @c someValue are "members" of @c struct @c Foo for
479         * instance. So that @c struct would have 3 members in the latter example.
480         *
481         * @see Object::members()
482       */       */
483      class Member {      class Member {
484      public:      public:
485          Member();          Member();
486          UID uid() const { return m_uid; }          UID uid() const;
487          String name() const { return m_name; }          String name() const;
488          size_t offset() const { return m_offset; }          size_t offset() const;
489          const DataType& type() const { return m_type; }          const DataType& type() const;
490          bool isValid() const;          bool isValid() const;
491          operator bool() const { return isValid(); }          operator bool() const { return isValid(); } ///< Same as calling isValid().
492          //bool operator()() const { return isValid(); }          //bool operator()() const { return isValid(); }
493          bool operator==(const Member& other) const;          bool operator==(const Member& other) const;
494          bool operator!=(const Member& other) const;          bool operator!=(const Member& other) const;
# Line 332  namespace Serialization { Line 508  namespace Serialization {
508          friend Member _popMemberBlob(const char*& p, const char* end);          friend Member _popMemberBlob(const char*& p, const char* end);
509      };      };
510    
511      /** @brief Abstract reflection of a native C++ class/struct instance.      /** @brief Abstract reflection of some native serialized C/C++ data.
512         *
513         * When your native C++ objects are serialized, all native data is
514         * translated and reflected by such an Object reflection. So each instance
515         * of your serialized native C++ class objects become available as an
516         * Object, but also each member variable of your C++ objects is translated
517         * into an Object, and any other native C/C++ data. So essentially every
518         * native data is turned into its own Object and accessible by this API.
519         *
520         * For each one of those Object reflections, this class provides detailed
521         * information about their native origin. For example if an Object
522         * represents a native C++ class instante, then it provides access to its
523         * C++ class/struct name, to its C++ member variables, its native memory
524         * size and much more.
525       *       *
526       * Provides detailed information about a specific serialized C++ object,       * Even though this framework allows you to adjust abstract Object instances
527       * like its C++ member variables, its C++ class/struct name, its native       * to a certain extent, most of the methods of this Object class are
528       * memory size and more.       * read-only though and the actual modifyable methods are made available
529         * not as part of this Object class, but as part of the Archive class
530         * instead. This design decision was made for performance and safety
531         * reasons.
532         *
533         * @see Archive::setIntValue() as an example for modifying Object instances.
534       */       */
535      class Object {      class Object {
536      public:      public:
537          Object();          Object();
538          Object(UIDChain uidChain, DataType type);          Object(UIDChain uidChain, DataType type);
539    
540          UID uid(int index = 0) const {          UID uid(int index = 0) const;
541              return (index < m_uid.size()) ? m_uid[index] : NO_UID;          const UIDChain& uidChain() const;
542          }          const DataType& type() const;
543            const RawData& rawData() const;
544          const UIDChain& uidChain() const { return m_uid; }          Version version() const;
545          const DataType& type() const { return m_type; }          Version minVersion() const;
         const RawData& rawData() const { return m_data; }  
   
         Version version() const { return m_version; }  
   
         void setVersion(Version v) {  
             m_version = v;  
         }  
   
         Version minVersion() const { return m_minVersion; }  
   
         void setMinVersion(Version v) {  
             m_minVersion = v;  
         }  
   
546          bool isVersionCompatibleTo(const Object& other) const;          bool isVersionCompatibleTo(const Object& other) const;
547            std::vector<Member>& members();
548          std::vector<Member>& members() { return m_members; }          const std::vector<Member>& members() const;
         const std::vector<Member>& members() const { return m_members; }  
549          Member memberNamed(String name) const;          Member memberNamed(String name) const;
550          Member memberByUID(const UID& uid) const;          Member memberByUID(const UID& uid) const;
551          std::vector<Member> membersOfType(const DataType& type) const;          std::vector<Member> membersOfType(const DataType& type) const;
552          int sequenceIndexOf(const Member& member) const;          int sequenceIndexOf(const Member& member) const;
553          bool isValid() const;          bool isValid() const;
554          operator bool() const { return isValid(); }          operator bool() const { return isValid(); } ///< Same as calling isValid().
555          //bool operator()() const { return isValid(); }          //bool operator()() const { return isValid(); }
556          bool operator==(const Object& other) const;          bool operator==(const Object& other) const;
557          bool operator!=(const Object& other) const;          bool operator!=(const Object& other) const;
# Line 381  namespace Serialization { Line 560  namespace Serialization {
560    
561      protected:      protected:
562          void remove(const Member& member);          void remove(const Member& member);
563            void setVersion(Version v);
564            void setMinVersion(Version v);
565    
566      private:      private:
567          DataType m_type;          DataType m_type;
# Line 394  namespace Serialization { Line 575  namespace Serialization {
575          friend Object _popObjectBlob(const char*& p, const char* end);          friend Object _popObjectBlob(const char*& p, const char* end);
576          friend void _popPrimitiveValue(const char*& p, const char* end, Object& obj);          friend void _popPrimitiveValue(const char*& p, const char* end, Object& obj);
577          friend String _primitiveObjectValueToString(const Object& obj);          friend String _primitiveObjectValueToString(const Object& obj);
578    
579            template<typename T>
580            friend T _primitiveObjectValueToNumber(const Object& obj);
581    
582          friend class Archive;          friend class Archive;
583      };      };
584    
# Line 509  namespace Serialization { Line 694  namespace Serialization {
694       * Note that there is only one method that you need to implement. So the       * Note that there is only one method that you need to implement. So the
695       * respective serialize() method implementation of your classes/structs are       * respective serialize() method implementation of your classes/structs are
696       * both called for serialization, as well as for deserialization!       * both called for serialization, as well as for deserialization!
697         *
698         * In case you need to enforce backward incompatiblity for one of your C++
699         * classes, you can do so by setting a version and minimum version for your
700         * class (see @c setVersion() and @c setMinVersion() for details).
701       */       */
702      class Archive {      class Archive {
703      public:      public:
# Line 517  namespace Serialization { Line 706  namespace Serialization {
706          Archive(const uint8_t* data, size_t size);          Archive(const uint8_t* data, size_t size);
707          virtual ~Archive();          virtual ~Archive();
708    
709            /** @brief Initiate serialization.
710             *
711             * Initiates serialization of all native C++ objects, which means
712             * capturing and storing the current data of all your C++ objects as
713             * content of this Archive.
714             *
715             * This framework has a concept of a "root" object which you must pass
716             * to this method. The root object is the starting point for
717             * serialization of your C++ objects. The framework will then
718             * recursively serialize all members of that C++ object an continue to
719             * serialize all other C++ objects that it might contain or point to.
720             *
721             * After this method returned, you might traverse all serialized objects
722             * by walking them starting from the rootObject(). You might then modify
723             * that abstract reflection of your C++ objects and finally you might
724             * call rawData() to get an encoded raw data stream which you might use
725             * for sending it "over wire" to somewhere where it is going to be
726             * deserialized later on.
727             *
728             * Note that whenever you call this method, the previous content of this
729             * Archive will first be cleared.
730             *
731             * @param obj - native C++ root object where serialization shall start
732             * @see Archive::operator<<()
733             */
734          template<typename T>          template<typename T>
735          void serialize(const T* obj) {          void serialize(const T* obj) {
736              m_operation = OPERATION_SERIALIZE;              m_operation = OPERATION_SERIALIZE;
# Line 528  namespace Serialization { Line 742  namespace Serialization {
742              m_operation = OPERATION_NONE;              m_operation = OPERATION_NONE;
743          }          }
744    
745            /** @brief Initiate deserialization.
746             *
747             * Initiates deserialization of all native C++ objects, which means all
748             * your C++ objects will be restored with the values contained in this
749             * Archive. So that also means calling deserialize() only makes sense if
750             * this a non-empty Archive, which i.e. is the case if you either called
751             * serialize() with this Archive object before or if you passed a
752             * previously serialized raw data stream to the constructor of this
753             * Archive object.
754             *
755             * This framework has a concept of a "root" object which you must pass
756             * to this method. The root object is the starting point for
757             * deserialization of your C++ objects. The framework will then
758             * recursively deserialize all members of that C++ object an continue to
759             * deserialize all other C++ objects that it might contain or point to,
760             * according to the values stored in this Archive.
761             *
762             * @param obj - native C++ root object where deserialization shall start
763             * @see Archive::operator>>()
764             *
765             * @throws Exception if the data stored in this Archive cannot be
766             *         restored to the C++ objects passed to this method, i.e.
767             *         because of version or type incompatibilities.
768             */
769          template<typename T>          template<typename T>
770          void deserialize(T* obj) {          void deserialize(T* obj) {
771              Archive a;              Archive a;
# Line 538  namespace Serialization { Line 776  namespace Serialization {
776              m_operation = OPERATION_NONE;              m_operation = OPERATION_NONE;
777          }          }
778    
779            /** @brief Initiate serialization of your C++ objects.
780             *
781             * Same as calling @c serialize(), this is just meant if you prefer
782             * to use operator based code instead, which you might find to be more
783             * intuitive.
784             *
785             * Example:
786             * @code
787             * Archive a;
788             * a << myRootObject;
789             * @endcode
790             *
791             * @see Archive::serialize() for more details.
792             */
793          template<typename T>          template<typename T>
794          void operator<<(const T& obj) {          void operator<<(const T& obj) {
795              serialize(&obj);              serialize(&obj);
796          }          }
797    
798            /** @brief Initiate deserialization of your C++ objects.
799             *
800             * Same as calling @c deserialize(), this is just meant if you prefer
801             * to use operator based code instead, which you might find to be more
802             * intuitive.
803             *
804             * Example:
805             * @code
806             * Archive a(rawDataStream);
807             * a >> myRootObject;
808             * @endcode
809             *
810             * @throws Exception if the data stored in this Archive cannot be
811             *         restored to the C++ objects passed to this method, i.e.
812             *         because of version or type incompatibilities.
813             *
814             * @see Archive::deserialize() for more details.
815             */
816          template<typename T>          template<typename T>
817          void operator>>(T& obj) {          void operator>>(T& obj) {
818              deserialize(&obj);              deserialize(&obj);
# Line 551  namespace Serialization { Line 821  namespace Serialization {
821          const RawData& rawData();          const RawData& rawData();
822          virtual String rawDataFormat() const;          virtual String rawDataFormat() const;
823    
824            /** @brief Serialize a native C/C++ member variable.
825             *
826             * This method is usually called by the serialize() method
827             * implementation of your C/C++ structs and classes, for each of the
828             * member variables that shall be serialized and deserialized
829             * automatically with this framework. It is recommend that you are not
830             * using this method name directly, but rather define a short hand C
831             * macro in your .cpp file like:
832             * @code
833             * #define SRLZ(member) \
834             *   archive->serializeMember(*this, member, #member);
835             *
836             * void Foo::serialize(Serialization::Archive* archive) {
837             *     SRLZ(a);
838             *     SRLZ(b);
839             *     SRLZ(c);
840             * }
841             * @endcode
842             * As you can see, using such a macro makes your code more readable and
843             * less error prone.
844             *
845             * It is completely up to you to decide which ones of your member
846             * variables shall automatically be serialized and deserialized with
847             * this framework. Only those member variables which are registered by
848             * calling this method will be serialized and deserialized. It does not
849             * really matter in which order you register your individiual member
850             * variables by calling this method, but the sequence is actually stored
851             * as meta information with the resulting archive and the resulting raw
852             * data stream. That meta information might then be used by this
853             * framework to automatically correct and adapt deserializing that
854             * archive later on for a future (or older) and potentially heavily
855             * modified version of your software. So it is recommended, even though
856             * also not required, that you may retain the sequence of your
857             * serializeMember() calls for your individual C++ classes' members over
858             * all your software versions, to retain backward compatibility of older
859             * archives as much as possible.
860             *
861             * @param nativeObject - native C++ object to be registered for
862             *                       serialization / deserialization
863             * @param nativeMember - native C++ member variable of @a nativeObject
864             *                       to be registered for serialization /
865             *                       deserialization
866             * @param memberName - name of @a nativeMember to be stored with this
867             *                     archive
868             */
869          template<typename T_classType, typename T_memberType>          template<typename T_classType, typename T_memberType>
870          void serializeMember(const T_classType& nativeObject, const T_memberType& nativeMember, const char* memberName) {          void serializeMember(const T_classType& nativeObject, const T_memberType& nativeMember, const char* memberName) {
871              const size_t offset =              const size_t offset =
872              ((const uint8_t*)(const void*)&nativeMember) -                  ((const uint8_t*)(const void*)&nativeMember) -
873              ((const uint8_t*)(const void*)&nativeObject);                  ((const uint8_t*)(const void*)&nativeObject);
874              const UIDChain uids = UIDChainResolver<T_memberType>(nativeMember);              const UIDChain uids = UIDChainResolver<T_memberType>(nativeMember);
875              const DataType type = DataType::dataTypeOf(nativeMember);              const DataType type = DataType::dataTypeOf(nativeMember);
876              const Member member(memberName, uids[0], offset, type);              const Member member(memberName, uids[0], offset, type);
# Line 579  namespace Serialization { Line 894  namespace Serialization {
894              }              }
895          }          }
896    
897            /** @brief Set current version number for your C++ class.
898             *
899             * By calling this method you can define a version number for your
900             * current C++ class (that is a version for its current data structure
901             * layout and method implementations) that is going to be stored along
902             * with the serialized archive. Only call this method if you really want
903             * to constrain compatibility of your C++ class.
904             *
905             * Along with calling @c setMinVersion() this provides a way for you
906             * to constrain backward compatibility regarding serialization and
907             * deserialization of your C++ class which the Archive class will obey
908             * to. If required, then typically you might do so in your
909             * @c serialize() method implementation like:
910             * @code
911             * #define SRLZ(member) \
912             *   archive->serializeMember(*this, member, #member);
913             *
914             * void Foo::serialize(Serialization::Archive* archive) {
915             *     // when serializing: the current version of this class that is
916             *     // going to be stored with the serialized archive
917             *     archive->setVersion(*this, 6);
918             *     // when deserializing: the minimum version this C++ class is
919             *     // compatible with
920             *     archive->setMinVersion(*this, 3);
921             *     // actual data mebers to serialize / deserialize
922             *     SRLZ(a);
923             *     SRLZ(b);
924             *     SRLZ(c);
925             * }
926             * @endcode
927             * In this example above, the C++ class "Foo" would be serialized along
928             * with the version number @c 6 and minimum version @c 3 as additional
929             * meta information in the resulting archive (and its raw data stream
930             * respectively).
931             *
932             * When deserializing archives with the example C++ class code above,
933             * the Archive object would check whether your originally serialized
934             * C++ "Foo" object had at least version number @c 3, if not the
935             * deserialization process would automatically be stopped with a
936             * @c Serialization::Exception, claiming that the classes are version
937             * incompatible.
938             *
939             * But also consider the other way around: you might have serialized
940             * your latest version of your C++ class, and might deserialize that
941             * archive with an older version of your C++ class. In that case it will
942             * likewise be checked whether the version of that old C++ class is at
943             * least as high as the minimum version set with the already seralized
944             * bleeding edge C++ class.
945             *
946             * Since this Serialization / deserialization framework is designed to
947             * be robust on changes to your C++ classes and aims trying to
948             * deserialize all your C++ objects correctly even if your C++ classes
949             * have seen substantial software changes in the meantime; you might
950             * sometimes see it as necessary to constrain backward compatibility
951             * this way. Because obviously there are certain things this framework
952             * can cope with, like for example that you renamed a data member while
953             * keeping the layout consistent, or that you have added new members to
954             * your C++ class or simply changed the order of your members in your
955             * C++ class. But what this framework cannot detect is for example if
956             * you changed the semantics of the values stored with your members, or
957             * even substantially changed the algorithms in your class methods such
958             * that they would not handle the data of your C++ members in the same
959             * and correct way anymore.
960             *
961             * @param nativeObject - your C++ object you want to set a version for
962             * @param v - the version number to set for your C++ class (by default,
963             *            that is if you do not explicitly call this method, then
964             *            your C++ object will be stored with version number @c 0 ).
965             */
966            template<typename T_classType>
967            void setVersion(const T_classType& nativeObject, Version v) {
968                const UID uid = UID::from(nativeObject);
969                Object& obj = m_allObjects[uid];
970                if (!obj) {
971                    const UIDChain uids = UIDChainResolver<T_classType>(nativeObject);
972                    const DataType type = DataType::dataTypeOf(nativeObject);
973                    obj = Object(uids, type);
974                }
975                setVersion(obj, v);
976            }
977    
978            /** @brief Set a minimum version number for your C++ class.
979             *
980             * Call this method to define a minimum version that your current C++
981             * class implementation would be compatible with when it comes to
982             * deserialization of an archive containing an object of your C++ class.
983             * Like the version information, the minimum version will also be stored
984             * for objects of your C++ class with the resulting archive (and its
985             * resulting raw data stream respectively).
986             *
987             * When you start to constrain version compatibility of your C++ class
988             * you usually start by using 1 as version and 1 as minimum version.
989             * So it is eligible to set the same number to both version and minimum
990             * version. However you must @b not set a minimum version higher than
991             * version. Doing so would not raise an exception, but the resulting
992             * behavior would be undefined.
993             *
994             * It is not relevant whether you first set version and then minimum
995             * version or vice versa. It is also not relevant when exactly you set
996             * those two numbers, even though usually you would set both in your
997             * serialize() method implementation.
998             *
999             * @see @c setVersion() for more details about this overall topic.
1000             *
1001             * @param nativeObject - your C++ object you want to set a version for
1002             * @param v - the minimum version you want to define for your C++ class
1003             *            (by default, that is if you do not explicitly call this
1004             *            method, then a minium version of @c 0 is assumed for your
1005             *            C++ class instead).
1006             */
1007            template<typename T_classType>
1008            void setMinVersion(const T_classType& nativeObject, Version v) {
1009                const UID uid = UID::from(nativeObject);
1010                Object& obj = m_allObjects[uid];
1011                if (!obj) {
1012                    const UIDChain uids = UIDChainResolver<T_classType>(nativeObject);
1013                    const DataType type = DataType::dataTypeOf(nativeObject);
1014                    obj = Object(uids, type);
1015                }
1016                setMinVersion(obj, v);
1017            }
1018    
1019          virtual void decode(const RawData& data);          virtual void decode(const RawData& data);
1020          virtual void decode(const uint8_t* data, size_t size);          virtual void decode(const uint8_t* data, size_t size);
1021          void clear();          void clear();
# Line 593  namespace Serialization { Line 1030  namespace Serialization {
1030          void setBoolValue(Object& object, bool value);          void setBoolValue(Object& object, bool value);
1031          void setEnumValue(Object& object, uint64_t value);          void setEnumValue(Object& object, uint64_t value);
1032          String valueAsString(const Object& object);          String valueAsString(const Object& object);
1033            int64_t valueAsInt(const Object& object);
1034            double valueAsReal(const Object& object);
1035            bool valueAsBool(const Object& object);
1036            void setVersion(Object& object, Version v);
1037            void setMinVersion(Object& object, Version v);
1038          String name() const;          String name() const;
1039          void setName(String name);          void setName(String name);
1040          String comment() const;          String comment() const;
# Line 622  namespace Serialization { Line 1064  namespace Serialization {
1064          class UIDChainResolver<T*> {          class UIDChainResolver<T*> {
1065          public:          public:
1066              UIDChainResolver(const T*& data) {              UIDChainResolver(const T*& data) {
1067                  m_uid.push_back((UID) { &data, sizeof(data) });                  const UID uids[2] = {
1068                  m_uid.push_back((UID) { data, sizeof(*data) });                      { &data, sizeof(data) },
1069                        { data, sizeof(*data) }
1070                    };
1071                    m_uid.push_back(uids[0]);
1072                    m_uid.push_back(uids[1]);
1073              }              }
1074    
1075              operator UIDChain() const { return m_uid; }              operator UIDChain() const { return m_uid; }
# Line 663  namespace Serialization { Line 1109  namespace Serialization {
1109    
1110          // Automatically handles recursion for class/struct types, while ignoring all primitive types.          // Automatically handles recursion for class/struct types, while ignoring all primitive types.
1111          template<typename T>          template<typename T>
1112          struct SerializationRecursion : SerializationRecursionImpl<T, __is_class(T)> {          struct SerializationRecursion : SerializationRecursionImpl<T, LIBGIG_IS_CLASS(T)> {
1113          };          };
1114    
1115          class ObjectPool : public std::map<UID,Object> {          class ObjectPool : public std::map<UID,Object> {
# Line 701  namespace Serialization { Line 1147  namespace Serialization {
1147              Archive& m_src;              Archive& m_src;
1148          };          };
1149    
1150            enum operation_t {
1151                OPERATION_NONE,
1152                OPERATION_SERIALIZE,
1153                OPERATION_DESERIALIZE
1154            };
1155    
1156          virtual void encode();          virtual void encode();
1157    
1158          ObjectPool m_allObjects;          ObjectPool m_allObjects;
# Line 722  namespace Serialization { Line 1174  namespace Serialization {
1174          public:          public:
1175              String Message;              String Message;
1176    
1177              Exception(String Message) { Exception::Message = Message; }              Exception(String format, ...);
1178                Exception(String format, va_list arg);
1179              void PrintMessage();              void PrintMessage();
1180              virtual ~Exception() {}              virtual ~Exception() {}
1181    
1182            protected:
1183                Exception();
1184                static String assemble(String format, va_list arg);
1185      };      };
1186    
1187  } // namespace Serialization  } // namespace Serialization
Legend:
Removed from v.3156  
changed lines
  Added in v.3198
  ViewVC Help
Powered by ViewVC