The MRPT project: CObject.h Source File

00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2010  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 #ifndef  MRPT_COBJECT_H
00029 #define  MRPT_COBJECT_H
00030 
00031 #include <mrpt/utils/utils_defs.h>
00032 #include <mrpt/utils/safe_pointers.h>
00033 
00034 namespace mrpt
00035 {
00036         namespace utils
00037         {
00038                 class BASE_IMPEXP CObject;
00039 
00040                 /** A smart pointer to a CObject object 
00041                   * \note Declared as a class instead of a typedef to avoid multiple defined symbols when linking dynamic libs.
00042                   */
00043                 class BASE_IMPEXP CObjectPtr : public stlplus::smart_ptr_clone<CObject>
00044                 {
00045                         typedef stlplus::smart_ptr_clone<CObject> BASE;
00046                 public:
00047                         inline CObjectPtr() : BASE() {}
00048                         explicit inline CObjectPtr(const CObject& data) :  BASE(data) {}
00049                         explicit inline CObjectPtr(CObject* data) :  BASE(data) { }
00050                         inline CObjectPtr& operator=(const CObject& data) { BASE::operator=(data); return *this; }
00051                         inline CObjectPtr& operator=(const CObjectPtr& r) { BASE::operator=(r); return *this; }
00052                 };
00053 
00054                 /** A structure that holds runtime class type information. Use CLASS_ID(<class_name>) to get a reference to the class_name's TRuntimeClassId descriptor.
00055                   */
00056                 struct BASE_IMPEXP TRuntimeClassId
00057                 {
00058                         const char* className;
00059                         /** Create an object of the related class, or NULL if it is virtual. */
00060                         mrpt::utils::CObject*                   (*ptrCreateObject)();
00061                         /** Gets the base class runtime id. */
00062                         const TRuntimeClassId*          (*getBaseClass)();
00063 
00064                         // Operations
00065                         mrpt::utils::CObject*           createObject() const;
00066                         bool    derivedFrom(const TRuntimeClassId* pBaseClass) const;
00067                         bool    derivedFrom(const char* pBaseClass_name) const;
00068 
00069                 };
00070 
00071                 /** A wrapper class for a "TRuntimeClassId *", well-defined with respect to copy operators and constructors.
00072                   */
00073                 typedef safe_ptr<TRuntimeClassId> TRuntimeClassIdPtr;
00074 
00075                 /** Register a class into the MRPT internal list of "CSerializable" descendents.
00076                   *  Used internally in the macros DEFINE_SERIALIZABLE, etc...
00077                   * \sa getAllRegisteredClasses, CStartUpClassesRegister
00078                   */
00079                 void BASE_IMPEXP registerClass(const mrpt::utils::TRuntimeClassId* pNewClass);
00080 
00081                 /** Mostly for internal use within mrpt sources, to handle exceptional cases with multiple serialization names for backward compatibility (CMultiMetricMaps, CImage,...)
00082                   */
00083                 void  BASE_IMPEXP registerClassCustomName(const char*customName, const TRuntimeClassId* pNewClass);
00084 
00085                 /** Returns a list with all the classes registered in the system through mrpt::utils::registerClass.
00086                   * \sa registerClass, findRegisteredClass
00087                   */
00088                 std::vector<const mrpt::utils::TRuntimeClassId*> BASE_IMPEXP getAllRegisteredClasses();
00089 
00090                 /** Return info about a given class by its name, or NULL if the class is not registered
00091                   * \sa registerClass, getAllRegisteredClasses
00092                   */
00093                 const TRuntimeClassId BASE_IMPEXP * findRegisteredClass(const std::string &className);
00094 
00095 
00096                 /** Access to runtime class ID for a defined class name.
00097                   */
00098                 #define CLASS_ID(class_name) static_cast<const mrpt::utils::TRuntimeClassId*>(&class_name::class##class_name)
00099 
00100                 /** Access to runtime class ID for a defined class name.
00101                   */
00102                 #define CLASS_ID_NAMESPACE(class_name,namespaceName) static_cast<const mrpt::utils::TRuntimeClassId*>(&namespaceName::class_name::class##class_name)
00103 
00104                 /** Access to runtime class ID for a defined template class name.
00105                   */
00106                 #define CLASS_ID_TEMPLATE(class_name,T) static_cast<const mrpt::utils::TRuntimeClassId*>(& template <class T> class_name<T>::class##class_name)
00107 
00108                 /** Evaluates to true if the given pointer to an object (derived from mrpt::utils::CSerializable) is of the given class. */
00109                 #define IS_CLASS( ptrObj, class_name )  ((ptrObj)->GetRuntimeClass()==CLASS_ID(class_name))
00110 
00111                 /** Evaluates to true if the given pointer to an object (derived from mrpt::utils::CSerializable) is an instance of the given class or any of its derived classes. */
00112                 #define IS_DERIVED( ptrObj, class_name )  ((ptrObj)->GetRuntimeClass()->derivedFrom(CLASS_ID(class_name)))
00113 
00114                 /** Auxiliary structure used for CObject-based RTTI. */
00115                 struct BASE_IMPEXP CLASSINIT
00116                 {
00117                         CLASSINIT(const mrpt::utils::TRuntimeClassId* pNewClass)
00118                         {
00119                                 registerClass(pNewClass);
00120                         }
00121                 };
00122 
00123 
00124                 /** The virtual base class of all MRPT classes with a unified RTTI system.
00125                  *   For each class named <code>CMyClass</code>, a new type named <code>CMyClassPtr</code> will be created as a smart pointer suitable for
00126                  *    keeping referencing count smart pointers to objects of that class. By default the base class of all these smart pointers is CObjectPtr.
00127                  * \sa  mrpt::utils::CSerializable
00128                  */
00129                 class BASE_IMPEXP CObject
00130                 {
00131                 protected:
00132                         static  mrpt::utils::TRuntimeClassId* _GetBaseClass();
00133                 public:
00134                         static const mrpt::utils::TRuntimeClassId classCObject;
00135 
00136                         /** Returns information about the class of an object in runtime. */
00137                         virtual const mrpt::utils::TRuntimeClassId* GetRuntimeClass() const
00138                         {
00139                                 return CLASS_ID(CObject);
00140                         }
00141 
00142                         /** Returns a copy of the object, indepently of its class. */
00143                         virtual CObject *duplicate() const = 0;
00144 
00145                         /** Returns a copy of the object, indepently of its class, as a smart pointer (the newly created object will exist as long as any copy of this smart pointer). */
00146                         inline mrpt::utils::CObjectPtr duplicateGetSmartPtr() const { return mrpt::utils::CObjectPtr( this->duplicate() ); }
00147 
00148                         /** Cloning interface for smart pointers */
00149                         inline CObject *clone() const { return duplicate(); }
00150 
00151                         virtual ~CObject() {  }
00152 
00153                 }; // End of class def.
00154 
00155                 /** This declaration must be inserted in all CObject classes definition, within the class declaration.
00156                   */
00157                 #define DEFINE_MRPT_OBJECT(class_name) \
00158                 protected: \
00159                         static  const mrpt::utils::TRuntimeClassId* _GetBaseClass(); \
00160                         static mrpt::utils::CLASSINIT _init_##class_name;\
00161                 public: \
00162                         typedef class_name##Ptr SmartPtr; \
00163                         static  mrpt::utils::TRuntimeClassId  class##class_name; \
00164                         static  const mrpt::utils::TRuntimeClassId *classinfo; \
00165                         virtual const mrpt::utils::TRuntimeClassId* GetRuntimeClass() const; \
00166                         static  mrpt::utils::CObject* CreateObject(); \
00167                         static class_name##Ptr Create(); \
00168                         virtual mrpt::utils::CObject *duplicate() const;
00169 
00170                 // This macro is a workaround to avoid possibly empty arguments to MACROS (when _LINKAGE_ evals to nothing...)
00171                 #define DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
00172                         DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name)
00173 
00174                 // Use this one when there is NO import/export macro:
00175                 #define DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_NO_LINKAGE(class_name, base_name) \
00176                         DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, class_name)
00177 
00178                 /**  This declaration must be inserted in all CObject classes definition, before the class declaration.
00179                   */
00180                 #define DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, class_name_LINKAGE_ ) \
00181                         class class_name_LINKAGE_; \
00182                         struct class_name_LINKAGE_##Ptr : public base_name##Ptr \
00183                         { \
00184                                 inline class_name##Ptr() : base_name##Ptr(static_cast<base_name*>(NULL)) { } \
00185                                 inline explicit class_name##Ptr(class_name* p) : base_name##Ptr( reinterpret_cast<base_name*>(p) ) { } \
00186                                 inline explicit class_name##Ptr(const base_name##Ptr & p) : base_name##Ptr(p) { ASSERTMSG_( p->GetRuntimeClass()->derivedFrom(#class_name),::mrpt::format("Wrong typecasting of smart pointers: %s -> %s",p->GetRuntimeClass()->className, #class_name) )  } \
00187                                 inline explicit class_name##Ptr(const mrpt::utils::CObjectPtr & p) : base_name##Ptr(p) { ASSERTMSG_( p->GetRuntimeClass()->derivedFrom(#class_name),::mrpt::format("Wrong typecasting of smart pointers: %s -> %s",p->GetRuntimeClass()->className, #class_name) )  } \
00188                                 inline void setFromPointerDoNotFreeAtDtor(const class_name* p) { this->set(const_cast<mrpt::utils::CObject*>(reinterpret_cast<const mrpt::utils::CObject*>(p))); m_holder->increment(); } \
00189                                 inline class_name * pointer() { return reinterpret_cast<class_name*>(base_name##Ptr::pointer()); } \
00190                                 inline const class_name * pointer() const { return reinterpret_cast<const class_name*>(base_name##Ptr::pointer()); } \
00191                                 inline class_name* operator ->(void) { return reinterpret_cast<class_name*>( base_name##Ptr::operator ->() ); } \
00192                                 inline const class_name* operator ->(void) const { return reinterpret_cast<const class_name*>( base_name##Ptr::operator ->() ); } \
00193                                 inline class_name& operator *(void) { return *reinterpret_cast<class_name*>( base_name##Ptr::operator ->() ); } \
00194                                 inline const class_name& operator *(void) const { return *reinterpret_cast<const class_name*>( base_name##Ptr::operator ->() ); } \
00195                         };
00196 
00197 
00198                 // This macro is a workaround to avoid possibly empty arguments to MACROS (when _LINKAGE_ evals to nothing...)
00199                 #define DEFINE_MRPT_OBJECT_PRE_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
00200                         DEFINE_MRPT_OBJECT_PRE_CUSTOM_LINKAGE2(class_name, _LINKAGE_ class_name)
00201 
00202                 // Use this macro when there is NO export/import macro:
00203                 #define DEFINE_MRPT_OBJECT_PRE_NO_LINKAGE(class_name) \
00204                         DEFINE_MRPT_OBJECT_PRE_CUSTOM_LINKAGE2(class_name, class_name)
00205 
00206                 // This one is almost identical to the one above, but without a member:
00207                 /**  This declaration must be inserted in all CObject classes definition, before the class declaration. */
00208                 #define DEFINE_MRPT_OBJECT_PRE_CUSTOM_LINKAGE2(class_name,class_name_LINKAGE_) \
00209                         class class_name_LINKAGE_; \
00210                         struct class_name_LINKAGE_##Ptr : public mrpt::utils::CObjectPtr \
00211                         { \
00212                                 inline class_name##Ptr() : mrpt::utils::CObjectPtr(static_cast<mrpt::utils::CObject*>(NULL)) { } \
00213                                 inline explicit class_name##Ptr(class_name* p) : mrpt::utils::CObjectPtr( reinterpret_cast<mrpt::utils::CObject*>(p) ) { } \
00214                                 inline explicit class_name##Ptr(const mrpt::utils::CObjectPtr & p) : mrpt::utils::CObjectPtr(p) { ASSERTMSG_( p->GetRuntimeClass()->derivedFrom(#class_name),::mrpt::format("Wrong typecasting of smart pointers: %s -> %s",p->GetRuntimeClass()->className, #class_name) )  } \
00215                                 inline void setFromPointerDoNotFreeAtDtor(const class_name* p) { this->set(const_cast<mrpt::utils::CObject*>(reinterpret_cast<const mrpt::utils::CObject*>(p))); m_holder->increment(); } \
00216                                 inline class_name * pointer() { return reinterpret_cast<class_name*>(mrpt::utils::CObjectPtr::pointer()); } \
00217                                 inline const class_name * pointer() const { return reinterpret_cast<const class_name*>(mrpt::utils::CObjectPtr::pointer()); } \
00218                                 inline class_name* operator ->(void) { return reinterpret_cast<class_name*>( mrpt::utils::CObjectPtr::operator ->() ); } \
00219                                 inline const class_name* operator ->(void) const { return reinterpret_cast<const class_name*>( mrpt::utils::CObjectPtr::operator ->() ); } \
00220                                 inline class_name& operator *(void) { return *reinterpret_cast<class_name*>( mrpt::utils::CObjectPtr::operator ->() ); } \
00221                                 inline const class_name& operator *(void) const { return *reinterpret_cast<const class_name*>( mrpt::utils::CObjectPtr::operator ->() ); } \
00222                         };
00223 
00224                 /**  This declaration must be inserted in all CObject classes definition, before the class declaration.
00225                   */
00226                 #define DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE(class_name, base_name) \
00227                         DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP )
00228 
00229                 /**  This declaration must be inserted in all CObject classes definition, before the class declaration.
00230                   */
00231                 #define DEFINE_MRPT_OBJECT_PRE(class_name) \
00232                         DEFINE_MRPT_OBJECT_PRE_CUSTOM_LINKAGE(class_name, BASE_IMPEXP )  // This macro is valid for classes within mrpt-core only.
00233 
00234                 /** This must be inserted in all CObject classes implementation files
00235                   */
00236                 #define IMPLEMENTS_MRPT_OBJECT(class_name, base,NameSpace) \
00237                         mrpt::utils::CObject* NameSpace::class_name::CreateObject() \
00238                                 { return static_cast<mrpt::utils::CObject*>( new NameSpace::class_name ); } \
00239                         NameSpace::class_name##Ptr NameSpace::class_name::Create() \
00240                                 { return NameSpace::class_name##Ptr( new NameSpace::class_name ); } \
00241                         const mrpt::utils::TRuntimeClassId* NameSpace::class_name::_GetBaseClass() \
00242                                 { return CLASS_ID(base); } \
00243                         mrpt::utils::TRuntimeClassId NameSpace::class_name::class##class_name = { \
00244                                 #class_name, NameSpace::class_name::CreateObject, &class_name::_GetBaseClass }; \
00245                         const mrpt::utils::TRuntimeClassId *NameSpace::class_name::classinfo = & NameSpace::class_name::class##class_name; \
00246                         const mrpt::utils::TRuntimeClassId* NameSpace::class_name::GetRuntimeClass() const \
00247                         { return CLASS_ID_NAMESPACE(class_name,NameSpace); } \
00248                         mrpt::utils::CLASSINIT NameSpace::class_name::_init_##class_name(CLASS_ID(base)); \
00249                         mrpt::utils::CObject * NameSpace::class_name::duplicate() const \
00250                         { return static_cast<mrpt::utils::CObject*>( new NameSpace::class_name(*this) ); }
00251 
00252 
00253                 /** This declaration must be inserted in virtual CSerializable classes definition:
00254                   */
00255                 #define DEFINE_VIRTUAL_MRPT_OBJECT(class_name) \
00256                 protected: \
00257                         static const mrpt::utils::TRuntimeClassId* _GetBaseClass(); \
00258                 public: \
00259                         static const mrpt::utils::TRuntimeClassId class##class_name; \
00260                         virtual const mrpt::utils::TRuntimeClassId* GetRuntimeClass() const; \
00261                         friend class mrpt::utils::CStream; \
00262 
00263                 /** This must be inserted as implementation of some required members for
00264                   *  virtual CSerializable classes:
00265                   */
00266                 #define IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name,NameSpace) \
00267                         const mrpt::utils::TRuntimeClassId* class_name::_GetBaseClass() \
00268                                 { return CLASS_ID(base_class_name); } \
00269                         const mrpt::utils::TRuntimeClassId class_name::class##class_name = { \
00270                                 #class_name, NULL, &class_name::_GetBaseClass }; \
00271                         const mrpt::utils::TRuntimeClassId* class_name::GetRuntimeClass() const \
00272                                 { return CLASS_ID(class_name); }
00273 
00274         } // End of namespace
00275 } // End of namespace
00276 
00277 // JL: I want these operators to reside in std so STL algorithms can always find them.
00278 namespace std
00279 {
00280         /**  This operator enables comparing two smart pointers with "==" to test whether they point to the same object.
00281           */
00282         template <typename T,typename C>
00283         bool operator == ( const stlplus::smart_ptr_base<T,C>&a,const stlplus::smart_ptr_base<T,C>&b) {
00284                 return a.aliases(b);
00285         }
00286         /**  This operator enables comparing two smart pointers with "!=" to test whether they don't point to the same object.
00287           */
00288         template <typename T,typename C>
00289         bool operator != ( const stlplus::smart_ptr_base<T,C>&a,const stlplus::smart_ptr_base<T,C>&b) {
00290                 return !a.aliases(b);
00291         }
00292 }
00293 
00294 #endif