dynobj.h

The library provides supports for run-time loaded plugin classes in C++

	
protected:    
   /** doDtor provides access to the object object destructor.
    * Currently not used. The intention with this member is to provide a way to 
    * invoke an object destructor without freeing its memory. It would allow for 
    * creating objects as sub-objects of other main objects. The way to implement 
    * it would be:  MyClass::doDtor(){ this->~MyClass(); } 
    */
	virtual void    docall doDtor( ){ }
    //@}
public:
    
    /** @name Others
     *  Other functions */
    //@{ 

    #if DO_FAT_VOBJ==1
   /** This destructor will notify the object tracker if activated. */
    ~DynObj();
    #endif // DO_FAT_VOBJ
    
    #if DO_ENABLE_OPERATOR_DELETE==1
	/** Route operator delete back to doDestroy. 
	 * NOTE: When an application defines its own operator new and/or redefines
	 * the new/delete keywords (to support memory tracking), this may not work.
	 * To be safe its best to call doDestroy directly.
     */
	void operator delete( void *pv ){ 
		if( !pv ) return;
        if( pv!=this )
            SetError( "DynObj::operator delete on wrong object", DOERR_DELETE_ON_WRONG_OBJECT );
        else
            doDestroy();
	}
    #endif // DO_ENABLE_OPERATOR_DELETE
    //@}
};

/** @ingroup DynI 
 * This is the base class for a ref-counted object. Derive from DynSharedI and 
 * implement ref-counting (support for atomic ref handling in pi/Atomic.h). 
 *
 * It adds ref counting methods to the object: doAddRef, doRelease. On object
 * creation, it is assumed that the internal ref counter is set to 1 (NOTE: not 0).
 *
 * DynSharedI derives from DynObj (more fundamental) since a ref-counted object 
 * depends on a mechanism to delete itself (which DynObj provides). 
 *
 * The DynSharedC is a default implementation that implements the ref counting
 * methods. 
 *
 * There are some other helpful classes: 
 *
 * -  ToDynShared<T> when converting a DynObj (or really any other object)
 *    to a shared object at compile time. do_cast<SomeType*>(p) will work for 
 *    querying types.
 *    
 * -  RTDynShared does the same at run-time, given a DynObj*. do_cast<SomeType*>(p) 
 *    will work (partially) for querying types.
 */
// %%DYNOBJ class(dyni)                         <- Tag for header file preprocessing 
class DynSharedI : public DynObj {
public:
	// All DynI derived types overrides this
	virtual DynObjType* docall doGetType( const DynI **pself=0 ) const;
	
	/** Increases the reference count of the object 
     * @return the updated ref count value
    */
	virtual int docall doAddRef( ) = 0;
	
	/** Decreares the reference count of the object and destroy if zero.
     * @return the updated ref count value
     */
	virtual int docall doRelease( ) = 0;
};


#if DO_NO_TYPEINFO!=1

/** @addtogroup Utils*/
//@{ 

/** Macro to declare type registration info.
 * Can use preprocessor pdoh instead to automate this. */
#define DO_DECL_TYPE_INFO(CLASS,ID) \
template<>                          \
struct doTypeInfo<CLASS> { \
public:                             \
    static int Id( ){ return ID; }  \
    static const char* Name( ){ return #CLASS; } \
};

/*
#define DO_DECL_TYPE_INFO_ALIAS(CLASS,REALCLASS)     \
template<>                                           \
struct doTypeInfo<CLASS> {                           \
public:                                              \
    static int Id( ){ doTypeInfo<REALCLASS>::Id(); } \
    static const char* Name( ){ return doTypeInfo<REALCLASS>::Name(); } \
};                             
//	enum { TypeId=doTypeInfo<REALCLASS>::TypeId };    \
*/

#else   // DO_NO_TYPEINFO
#define DO_DECL_TYPE_INFO(CLASS,ID)
#define DO_DECL_TYPE_INFO_ALIAS(CLASS,REALCLASS)
#endif  // DO_NO_TYPEINFO


// doTypeInfo for VObj, DynI and DynObj and DynSharedI
/// @cond internal
DO_DECL_TYPE_INFO(VObj,VOBJ_TYPE_ID);
DO_DECL_TYPE_INFO(DynI,DYNI_TYPE_ID);
DO_DECL_TYPE_INFO(DynObj,DYNOBJ_TYPE_ID);
DO_DECL_TYPE_INFO(DynSharedI,DYNSHAREDI_TYPE_ID);
/// @endcond   // internal


/** Retrieve the type of the object. 
  * @param pobj Object 
  * @return DynObjType of object or NULL if not found. */
DynObjType* doGetType( const void* pobj );

/** Retrieve the type of the object. 
  * @param pdi Object 
  * @return DynObjType of object or NULL if not found. */
DynObjType* doGetType( const DynI* pdi );


/** Get sub-object or interface. 
  * @param pobj Query object 
  * @param type string 
  * @param self_type Type of pobj or NULL if not known 
  * @param algo Algoithm to use in cast
  * @param found_type Pointer-to-pointer: store found type here if non-NULL
  * @return Pointer to interface/object */
void* doGetObj( void* pobj, const char *type, DynObjType *self_type, doCastAlgo algo, DynObjType **found_type );

/** Get sub-object or interface. 
  * @param pobj Query object 
  * @param type_id Integer type ID
  * @param self_type Type of pobj or NULL if not known 
  * @param algo Algoithm to use in cast
  * @param found_type Pointer-to-pointer: store found type here if non-NULL
  * @return Pointer to interface/object */
void* doGetObj( void* pobj, int type_id, DynObjType *self_type, doCastAlgo algo, DynObjType **found_type );

/** Version of doGetType (with type string) for DynI */
void* doGetObj( DynI* pdi, const char *type, doCastAlgo algo, DynObjType **found_type );

/** Version of doGetType (with type ID) for DynI */
void* doGetObj( DynI* pdi, int type_id, doCastAlgo algo, DynObjType **found_type );


/** Find DynObjType by type string. 
  * @param type Type name string
  * @return Pointer to DynObjType or NULL if not found */
DynObjType *doFindType( const char *type );

/** Find DynObjType by type ID. 
  * @param type Type name string
  * @return Pointer to DynObjType or NULL if not found */
DynObjType *doFindType( int type_id );


/** Ends startup phase and checks that initializion went OK. 
  * Registers all known types with DoRunTimeI. Verifies that all types 
  * were correctly resolved. 
  * Usually called only by main program.
  * @return true on success */
bool doInit( );


/** Set up a type from an instance and register it. 
  * This should be done 
  * - For the first instance of each type created
  * - If using VTable correction, it must be done for each object of a type 
  *   that needs correction (if it has virtual methods to protect from derived /
  *   compound overriding [for example DynI]).
  * NOTE: This is done automatically when creating objects through DoRunTime. 
  * When creating instantiating objects in other ways, one must us DoConstruct
  * manually
  * @param obj The object to register 
  * @param self_type Type of the object or NULL if not known 
  * @param is_outer set to true when registering an object from outside
  * (when it is not a side base class) 
  * @return true if successful.
  */
bool doConstruct( const VObj *obj, DynObjType *self_type, bool is_outer=true );


/** Call doRelease or doDestroy on the object. 
  * Used to end ownership of a DynObj which can derive either
  * directly from DynObj or from DynSharedI. 
  * @param pdo Object to release or destroy
  */ 
void doReleaseDestroy( DynObj *pdo );

/** Check if an object is a static/global instance.
  * A static instance will have equal or longer lifetime compared to 
  * the calling module.  
  * @param pdo Object to release or destroy
  * @param type if of object if known
  * @return true if valid object and it is static 
  */
bool doIsStatic( const VObj *pvo, DynObjType *type=NULL );
bool doIsStatic( const DynI *pdi );

/** Returns a pointer to the shared instance of doRunTime. Valid if we're compiling 
  * with DO_USE_RUNTIME, and after the pointer has been setup.
  */ 
class DoRunTimeI;
DoRunTimeI &doGetRunTime();

// Add implemented type for exporting (a type for which the user can give 
// its name to the library and receive a new instance)
bool doAddImplemented( const char *type, int type_id );
const char *doGetImplemented( );

// Use global variable to automatically register exported type on module load
class doUserTypeDecl {
public: 
	doUserTypeDecl( const char *type, int type_id ) {
		doAddImplemented(type,type_id);
	}
};
//@} // Utils



//
//	Functionality implemented by DynObj libraries.
//

/** @addtogroup Library*/
//@{ 

// Used in library init functions below
class DoRunTimeI;
struct DynObjLibImpl;


//
// The object creation function should be named 'CreateDynObj'.
//
// The object destroy function should be named 'DestroyDynObj'.
//
// Library init function is named 'InitDynLib' and returns a pointer to a 
// DynObjLibImpl structure (if library is compiled fromDynObj.cpp 
// this is not necessary, unless custom initialization must be done).
//
// Library exit function named 'ExitDynLib' (not mandatory).
// - not implemented - The set base creation function should be named 'SetBaseCreate'.
// All these functions are exported with 'extern "C" SYM_EXPORT'. 

/** Protoptype for library functions that create objects .
  * This function is usually named 'CreateDynObj'.
  * The create function is free to create an object even if only one of
  * type_id or type is defined.
  * @param type The type string naming type of object to be created
  * @param type_id The type ID of the object to be created
  * @param di_init A DynI object to be passed to constructor of new object
  * @param obj_size Size of memory to allocate for object. Currently not used and always
  * set to 0 which means don't care.
  * @return The returned object is derived from DynObj (directly or indirectly)
  */
typedef DynObj* (*CreateDynObjFn)( const char *type, int type_id, const DynI* pdi_init, int object_size );


/** Protoptype for library init functions. 
  * Library init function is named 'InitDynLib' and returns a pointer to a 
  * DynObjLibImpl structure. If library is linked with DynObj.cpp 
  * this is not necessary it can return NULL. 
  * @param pdort The pointer to DoRunTimeI. Allows the library to connect with 
  * shared resources.
  * @return A pointer to a DynObjLibImpl structure that describes types
  * implemented by the plugin library and the compiler used to generate it.
  */
typedef DynObjLibImpl* (*InitDynLibFn)( DoRunTimeI* pdort );

/** Prototype for function called at library unload. 
  * If is_query is true, the library will not be closed now, given that the 
  * function returns false.
  * @param is_query is set to true if the library can 'object' to shutdown.
  * @return true if library is ready to shut down (it may be shutdown anyway).
  */
typedef bool (*ExitDynLibFn)(bool is_query);

/** Protoptype for library functions that destroys objects. 
  * The default way to delete is through doDestroy, so this is not necessary to
  * implement. When destroying objects not derived from DynObj/DynSharedI
  * it is required.
  * @param pv is a pointer to object to destroy
  * @param pdt is a pointer to the type of the object
  * @return true on succesful destroy.
  */
typedef bool (*DestroyDynObjFn)( VObj *pv, DynObjType *pdt );

class DoModuleC;

/** Holds information about a DynObj library. 
  * Returned on library initialization. 
  */
struct DynObjLibImpl {
    DynObjLibImpl(const char *cs, const char *impl, int dt, int pf);
  
    StructHeader _sh;           /**< Verifies that this is a struct of the right type */
    
    const char *_lib_name;      /**< Name of library */
    const char *_lib_descr;     /**< Description of library */
    const char *_lib_author;    /**< Author of library */
    
    const char *_call_str;      /**< Calling convention */
    const char *_implements;    /**< Interfaces & classes implemented */
    int   _do_traits;           /**< Describing object layout properties */
    int   _platform;            /**< Platform where library was built */
    int       _lib_major_ver;   /**< Library major version */
    int       _lib_minor_ver;   /**< Library minor version */
    
    DynObjType **&_types;       /**< Pointer to types used/implemented in library (NULL terminated array) */
    DoModuleC  *_module;        /**< ModuleI for this library */
    
    const char *_compiler;      /**< Library compiler */
    int        _comp_major_ver; /**< Major version of library compiler */
    int        _comp_minor_ver; /**< Minor version of library compiler */
    int        _lib_flags;      /**< Library flags */
    int        _dynobj_major_ver; /**< Major version of DynObj framework */
    int        _dynobj_minor_ver; /**< Minor version of DynObj framework */
};

#define DOLI_USES_RUNTIME       1
#define DOLI_OBJECT_TRACKING    2

//@} // Library


// Macros to generate and extract platform info above
#define DO_PLATFORM_FLAGS ( PLATFORM_FLAGS | (PFM_INT_SIZE<<16) | (PFM_PTR_SIZE<<18) | (PFM_WCHART_SIZE<<20) )


// The compiler will likely set sizeof(VObj) to 0 or 1, however, we want 
// the VPTR to be part of the size
#define VOBJ_SIZE sizeof(void*)

// %%DYNOBJ section implement
// This section is auto-generated and manual changes will be lost when regenerated!!
#ifdef DO_IMPLEMENT_DYNOBJ

// Generate type information that auto-registers on module load
DynObjType g_do_vtype_VObj("VObj",VOBJ_TYPE_ID,1,VOBJ_SIZE);
DynObjType g_do_vtype_DynI("DynI:VObj",DYNI_TYPE_ID,1,sizeof(DynI));
DynObjType* DynI::doGetType( const DynI **pself ) const {
   if(pself) *pself=(const DynI*)(const void*)this;
   return &g_do_vtype_DynI;
}
DynObjType g_do_vtype_DynObj("DynObj:DynI",DYNOBJ_TYPE_ID,1,sizeof(DynObj));
DynObjType* DynObj::doGetType( const DynI **pself ) const {
   if(pself) *pself=(const DynI*)(const void*)this;
   return &g_do_vtype_DynObj;
}
DynObjType g_do_vtype_DynSharedI("DynSharedI:DynObj",DYNSHAREDI_TYPE_ID,1,sizeof(DynSharedI));
DynObjType* DynSharedI::doGetType( const DynI **pself ) const {
   if(pself) *pself=(const DynI*)(const void*)this;
   return &g_do_vtype_DynSharedI;
}
#endif //DO_IMPLEMENT_...
// %%DYNOBJ section end

#endif // DYNOBJ_H