ERC-CISST Software

These macros can be divided in three sets, one of each should be used for any registered class.

The macros ending with _EXPORT are required to handle the generation of DLLs correctly with the different Microsoft compilers (see also CISST_EXPORT) and the macro ending with _TEMPLATED is required to register a specialized version of a templated class.

Defines

These macros are used to declare the required methods and data members for the class registration (see also cmnClassRegister). Every class which needs to be registered should include one of these macros within its declaration AND be derived from cmnGenericObject.

To declare a registered class without dynamic creation, the header file myClass.h should have:

    class CISST_EXPORT myClass: public cmnGenericObject
    {
        CMN_DECLARE_SERVICES(#CMN_NO_DYNAMIC_CREATION, CMN_LOG_DEFAULT_LOD);
    public:
        ...
    };

The macro CMN_DECLARE_SERVICES defines amongst other things a static method which can not be inlined. Therefore, when one wants to create a Dll (shared libraries on Windows) with a C++ compiler from Microsoft, one must explicitly export it. In most cases, the class itself is "exported" using CISST_EXPORT. If the class is not wholly exported, it is possible to export some methods explicitly. In this case, the macro CMN_DECLARE_SERVICES_EXPORT should be used:

    class myClass: public cmnGenericObject
    {
        CMN_DECLARE_SERVICES_EXPORT(CMN_NO_DYNAMIC_CREATION, CMN_LOG_DEFAULT_LOD);
    public:
        CISST_EXPORT void MethodA(void);
        ...
    };

Finally, the macro CMN_DECLARE_SERVICES_EXPORT_ALWAYS was introduced as a temporary fix for template classes, such as mtsGenericObjectProxy.

Parameters:

	hasDynamicCreation	Set this parameter to CMN_DYNAMIC_CREATION to enable dynamic creation and CMN_NO_DYNAMIC_CREATION to disable dynamic creation. Dynamic creation requires a public default constructor.
	lod	The default Level of Detail used for this class (see also CMN_LOG and CMN_LOG_DEFAULT_LOD.

The templated function cmnClassServicesInstantiate is used to generate a unique object of type cmnClassServices for each class defined in cisst. It contains a static data member which will be constructed the first time it is called. The header file myClass.h should have to following code after the class declaration of myClass:

    CMN_DECLARE_SERVICES_INSTANTIATION_EXPORT(myClass)

In most case, CMN_DECLARE_SERVICES_INSTANTIATION_EXPORT should be used. One case where CMN_DECLARE_SERVICES_INSTANTIATION should be used in when the class instantiation will reside in the executable, i.e. the programmer is not creating a library but is linking all is binaries directly into and executable.

For a template class, it is necessary to specify which template specialization is being registered. To do so, it is recommended to create a typedef before using this macro:

    template <class _templateParameter>
    myClass<_templateParameter>: public cmnGenericObject
    {
        CMN_DECLARE_SERVICES_EXPORT(CMN_NO_DYNAMIC_CREATION, CMN_LOG_DEFAULT_LOD);
    public:
        ...
    };

    typedef myClass<double> myClassDouble;
    CMN_DECLARE_SERVICES_INSTANTIATION_EXPORT(myClassDouble)

Parameters:

className

The name of the class being registered, without any quote.

These macros implements the methods and function declared by CMN_DECLARE_SERVICES and CMN_DECLARE_SERVICES_INSTANTIATION_EXPORT. For a non templated class, the source file myClass.cpp must have:

    CMN_IMPLEMENT_SERVICES(myClass);

For a templated class specialized and define using typedef ... myClassDouble, the source file must have:

    CMN_IMPLEMENT_SERVICES_TEMPLATED(myClassDouble);

Parameters:

className

The name of the class being registered, without any quote.

CMN_DECLARE_SERVICES and CMN_DECLARE_SERVICES_EXPORT.

Define Documentation

#define CMN_DECLARE_SERVICES	(	hasDynamicCreation,
		lod		)

Value:

public: \
      enum {HAS_DYNAMIC_CREATION = hasDynamicCreation}; \
      enum {InitialLoD = lod}; \
      static cmnClassServicesBase * ClassServices(void); \
      virtual const cmnClassServicesBase * Services(void) const \
      { \
          return this->ClassServices(); \
      } \
    private: \
      static cmnClassServicesBase * ClassServicesPointer;

Definition at line 115 of file cmnClassRegisterMacros.h.

#define CMN_DECLARE_SERVICES_EXPORT	(	hasDynamicCreation,
		lod		)

Value:

public: \
      enum {HAS_DYNAMIC_CREATION = hasDynamicCreation}; \
      enum {InitialLoD = lod}; \
      CISST_EXPORT static cmnClassServicesBase * ClassServices(void); \
      virtual const cmnClassServicesBase * Services(void) const \
      { \
          return this->ClassServices(); \
      } \
    private: \
      static cmnClassServicesBase * ClassServicesPointer;

Definition at line 132 of file cmnClassRegisterMacros.h.

#define CMN_DECLARE_SERVICES_INSTANTIATION_EXPORT ( className )

Value:

template<> CISST_EXPORT \
cmnClassServicesBase * cmnClassServicesInstantiate<className>(void);

Definition at line 217 of file cmnClassRegisterMacros.h.

#define CMN_IMPLEMENT_SERVICES ( className )

Value:

cmnClassServicesBase * className::ClassServices(void) \
{ \
    static cmnClassServicesBase * classServices = cmnClassServicesInstantiate<className>(); \
    return classServices; \
} \
cmnClassServicesBase * className::ClassServicesPointer = className::ClassServices(); \
template<> \
cmnClassServicesBase * cmnClassServicesInstantiate<className>(void) \
{ \
    static cmnClassServices<className::HAS_DYNAMIC_CREATION, className> classServices(#className, \
                                                                                      &typeid(className), \
                                                                                      static_cast<cmnLogLoD>(className::InitialLoD)); \
    return static_cast<cmnClassServicesBase *>(&classServices); \
} \
static cmnClassServicesBase * className##ClassServicesPointer = className::ClassServices();

Definition at line 250 of file cmnClassRegisterMacros.h.

#define CMN_IMPLEMENT_SERVICES_TEMPLATED ( className )

Value:

template<> \
cmnClassServicesBase * className::ClassServices(void) \
{ \
    static cmnClassServicesBase * classServices = cmnClassServicesInstantiate<className>(); \
    return classServices; \
} \
template<> \
cmnClassServicesBase * className::ClassServicesPointer = className::ClassServices(); \
template<> \
const cmnClassServicesBase * className::Services(void) const \
{ \
   return this->ClassServices(); \
} \
template<> \
cmnClassServicesBase * cmnClassServicesInstantiate<className>(void) \
{ \
    static cmnClassServices<className::HAS_DYNAMIC_CREATION, className> classServices(#className, \
                                                                                      &typeid(className), \
                                                                                      static_cast<cmnLogLoD>(className::InitialLoD)); \
    return static_cast<cmnClassServicesBase *>(&classServices); \
} \
static cmnClassServicesBase * className##ClassServicesPointer = className::ClassServices();

Definition at line 271 of file cmnClassRegisterMacros.h.

cmnClassRegisterMacros.h File Reference

Detailed Description

Defines

Define Documentation