NCBI C++ ToolKit
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Private Attributes | List of all members
CPluginManager< TClass > Class Template Reference

Search Toolkit Book for CPluginManager

CPluginManager<> –. More...

#include <corelib/plugin_manager.hpp>

+ Inheritance diagram for CPluginManager< TClass >:
+ Collaboration diagram for CPluginManager< TClass >:

Classes

struct  SDriverInfo
 Information about a driver, with maybe a pointer to an instantiated class factory that contains the driver. More...
 

Public Types

enum  EEntryPointRequest { eGetFactoryInfo, eInstantiateFactory }
 Actions performed by the entry point. More...
 
typedef IClassFactory< TClass > TClassFactory
 
typedef CDefaultDriverVersion< TClass > TDefaultDriverVersion
 
typedef vector< stringTSearchPaths
 Container for the DLL search paths. More...
 
typedef list< SDriverInfoTDriverInfoList
 List of driver information. More...
 
typedef void(* FNCBI_EntryPoint) (TDriverInfoList &info_list, EEntryPointRequest method)
 Entry point to get drivers' info, and (if requested) their class factories. More...
 
- Public Types inherited from CObject
enum  EAllocFillMode { eAllocFillNone = 1, eAllocFillZero, eAllocFillPattern }
 Control filling of newly allocated memory. More...
 
typedef CObjectCounterLocker TLockerType
 Default locker type for CRef. More...
 
typedef CAtomicCounter TCounter
 Counter type is CAtomiCounter. More...
 
typedef TCounter::TValue TCount
 Alias for value type of counter. More...
 

Public Member Functions

TClass * CreateInstance (const string &driver=kEmptyStr, const CVersionInfo &version=GetDefaultDrvVers(), const TPluginManagerParamTree *params=0)
 Create class instance. More...
 
TClass * CreateInstanceFromList (const TPluginManagerParamTree *params, const string &driver_list, const CVersionInfo &version=GetDefaultDrvVers())
 Create first available driver from the list of drivers. More...
 
TClass * CreateInstanceFromKey (const TPluginManagerParamTree *params, const string &driver_key, const CVersionInfo &version=GetDefaultDrvVers())
 Detect driver from the parameters using the key to get list of drivers. More...
 
TClassFactoryGetFactory (const string &driver=kEmptyStr, const CVersionInfo &version=GetDefaultDrvVers())
 Get class factory. More...
 
bool RegisterFactory (TClassFactory &factory)
 Try to register factory in the manager. More...
 
bool WillExtendCapabilities (TClassFactory &factory) const
 Check if a given factory will extend capabilities of the Plugin Manager (add either new drivers or new driver versions to already available). More...
 
bool UnregisterFactory (TClassFactory &factory)
 Unregister and release (un-own) More...
 
template<typename TEntryPoint >
bool RegisterWithEntryPoint (TEntryPoint plugin_entry_point)
 Register all factories exported by the plugin entry point. More...
 
template<typename TEntryPoint >
bool RegisterWithEntryPoint (TEntryPoint plugin_entry_point, const string &driver_name, const CVersionInfo &driver_version=CVersionInfo::kLatest)
 Register all compatible factories for the driver with the particular version exported by the plugin entry point. More...
 
void AddResolver (CPluginManager_DllResolver *resolver)
 Attach DLL resolver to plugin manager. More...
 
CPluginManager_DllResolverDetachResolver (CPluginManager_DllResolver *resolver)
 Remove resolver from the list of active resolvers. More...
 
void AddDllSearchPath (const string &path)
 Add path for the DLL lookup (for all resolvers) More...
 
void ResetDllSearchPath (TSearchPaths *previous_paths=NULL)
 Delete all user-installed paths for the DLL lookup (for all resolvers) More...
 
CDllResolver::TExtraDllPath SetDllStdSearchPath (CDllResolver::TExtraDllPath standard_paths)
 Specify which standard locations should be used for the DLL lookup (for all resolvers). More...
 
CDllResolver::TExtraDllPath GetDllStdSearchPath (void) const
 Get standard locations which should be used for the DLL lookup. More...
 
void ResolveFile (const string &driver=kEmptyStr, const CVersionInfo &version=GetDefaultDrvVers())
 Scan DLLs for specified driver using attached resolvers. More...
 
void FreezeResolution (bool value=true)
 Disable/enable DLL resolution (search for class factories in DLLs) More...
 
void FreezeResolution (const string &driver, bool value=true)
 Disable/enable DLL resolution (search for class factories in DLLs) for the specified driver. More...
 
 CPluginManager (void)
 
virtual ~CPluginManager (void)
 
- Public Member Functions inherited from CObject
 CObject (void)
 Constructor. More...
 
 CObject (const CObject &src)
 Copy constructor. More...
 
virtual ~CObject (void)
 Destructor. More...
 
CObjectoperator= (const CObject &src) THROWS_NONE
 Assignment operator. More...
 
bool CanBeDeleted (void) const THROWS_NONE
 Check if object can be deleted. More...
 
bool IsAllocatedInPool (void) const THROWS_NONE
 Check if object is allocated in memory pool (not system heap) More...
 
bool Referenced (void) const THROWS_NONE
 Check if object is referenced. More...
 
bool ReferencedOnlyOnce (void) const THROWS_NONE
 Check if object is referenced only once. More...
 
void AddReference (void) const
 Add reference to object. More...
 
void RemoveReference (void) const
 Remove reference to object. More...
 
void ReleaseReference (void) const
 Remove reference without deleting object. More...
 
virtual void DoNotDeleteThisObject (void)
 Mark this object as not allocated in heap – do not delete this object. More...
 
virtual void DoDeleteThisObject (void)
 Mark this object as allocated in heap – object can be deleted. More...
 
void * operator new (size_t size)
 Define new operator for memory allocation. More...
 
void * operator new[] (size_t size)
 Define new[] operator for 'array' memory allocation. More...
 
void operator delete (void *ptr)
 Define delete operator for memory deallocation. More...
 
void operator delete[] (void *ptr)
 Define delete[] operator for memory deallocation. More...
 
void * operator new (size_t size, void *place)
 Define new operator. More...
 
void operator delete (void *ptr, void *place)
 Define delete operator. More...
 
void * operator new (size_t size, CObjectMemoryPool *place)
 Define new operator using memory pool. More...
 
void operator delete (void *ptr, CObjectMemoryPool *place)
 Define delete operator. More...
 
virtual void DebugDump (CDebugDumpContext ddc, unsigned int depth) const
 Define method for dumping debug information. More...
 
- Public Member Functions inherited from CDebugDumpable
 CDebugDumpable (void)
 
virtual ~CDebugDumpable (void)
 
void DebugDumpText (ostream &out, const string &bundle, unsigned int depth) const
 
void DebugDumpFormat (CDebugDumpFormatter &ddf, const string &bundle, unsigned int depth) const
 
void DumpToConsole (void) const
 

Static Public Member Functions

static const CVersionInfoGetDefaultDrvVers (void)
 
- Static Public Member Functions inherited from CObject
static NCBI_NORETURN void ThrowNullPointerException (void)
 Define method to throw null pointer exception. More...
 
static NCBI_NORETURN void ThrowNullPointerException (const type_info &type)
 
static EAllocFillMode GetAllocFillMode (void)
 
static void SetAllocFillMode (EAllocFillMode mode)
 
static void SetAllocFillMode (const string &value)
 Set mode from configuration parameter value. More...
 
- Static Public Member Functions inherited from CDebugDumpable
static void EnableDebugDump (bool on)
 

Protected Types

typedef set< FNCBI_EntryPointTEntryPoints
 
typedef set< TClassFactory * > TFactories
 
typedef vector< CDllResolver::SResolvedEntryTResolvedEntries
 
typedef vector< CPluginManager_DllResolver * > TDllResolvers
 
typedef set< stringTStringSet
 
typedef map< string, stringTSubstituteMap
 

Protected Member Functions

TClassFactoryFindClassFactory (const string &driver, const CVersionInfo &version) const
 
- Protected Member Functions inherited from CObject
virtual void DeleteThis (void)
 Virtual method "deleting" this object. More...
 

Protected Attributes

CMutex m_Mutex
 Protective mutex to synchronize the access to the plugin manager from different threads. More...
 

Private Attributes

TFactories m_Factories
 List of factories presently registered with (and owned by) the plugin manager. More...
 
TEntryPoints m_EntryPoints
 List of entry points registered in this plugin manager. More...
 
TDllResolvers m_Resolvers
 DLL resolvers. More...
 
TSearchPaths m_DllSearchPaths
 Paths used for DLL search. More...
 
TResolvedEntries m_RegisteredEntries
 DLL entries resolved and registered with dll resolver(s) More...
 
bool m_BlockResolution
 Flag, prohibits DLL resolution. More...
 
TStringSet m_FreezeResolutionDrivers
 Set of drivers prohibited from DLL resolution. More...
 
CDllResolver::TExtraDllPath m_StdDllPath
 Standard locations that should be used for the DLL lookup. More...
 
TSubstituteMap m_SubstituteMap
 Driver name substitution map. More...
 

Additional Inherited Members

- Static Public Attributes inherited from CObject
static const TCount eCounterBitsCanBeDeleted = 1 << 0
 Define possible object states. More...
 
static const TCount eCounterBitsInPlainHeap = 1 << 1
 Heap signature was found. More...
 
static const TCount eCounterBitsPlaceMask
 Mask for 'in heap' state flags. More...
 
static const int eCounterStep = 1 << 2
 Skip over the "in heap" bits. More...
 
static const TCount eCounterValid = TCount(1) << (sizeof(TCount) * 8 - 2)
 Minimal value for valid objects (reference counter is zero) Must be a single bit value. More...
 
static const TCount eCounterStateMask
 Valid object, and object in heap. More...
 

Detailed Description

template<class TClass>
class CPluginManager< TClass >

CPluginManager<> –.

To register (either directly, or via an "entry point") class factories for the given interface.

Then, to facilitate the process of instantiating the class given the registered pool of drivers, and also taking into account the driver name and/or version as requested by the calling code.

Template class is protected by mutex and safe for use from different threads

Definition at line 293 of file plugin_manager.hpp.

Member Typedef Documentation

template<class TClass>
typedef void(* CPluginManager< TClass >::FNCBI_EntryPoint) (TDriverInfoList &info_list, EEntryPointRequest method)

Entry point to get drivers' info, and (if requested) their class factories.

This function is usually (but not necessarily) called by RegisterWithEntryPoint().

Usually, it's called twice – the first time to get the info about the drivers exported by the entry point, and then to instantiate selected factories.

Caller is responsible for the proper destruction (deallocation) of the instantiated factories.

Definition at line 442 of file plugin_manager.hpp.

template<class TClass>
typedef IClassFactory<TClass> CPluginManager< TClass >::TClassFactory

Definition at line 296 of file plugin_manager.hpp.

template<class TClass>
typedef CDefaultDriverVersion<TClass> CPluginManager< TClass >::TDefaultDriverVersion

Definition at line 297 of file plugin_manager.hpp.

template<class TClass>
typedef vector<CPluginManager_DllResolver*> CPluginManager< TClass >::TDllResolvers
protected

Definition at line 540 of file plugin_manager.hpp.

template<class TClass>
typedef list<SDriverInfo> CPluginManager< TClass >::TDriverInfoList

List of driver information.

It is used to communicate using the entry points mechanism.

See also
FNCBI_EntryPoint

Definition at line 391 of file plugin_manager.hpp.

template<class TClass>
typedef set<FNCBI_EntryPoint> CPluginManager< TClass >::TEntryPoints
protected

Definition at line 535 of file plugin_manager.hpp.

template<class TClass>
typedef set<TClassFactory*> CPluginManager< TClass >::TFactories
protected

Definition at line 536 of file plugin_manager.hpp.

template<class TClass>
typedef vector<CDllResolver::SResolvedEntry> CPluginManager< TClass >::TResolvedEntries
protected

Definition at line 538 of file plugin_manager.hpp.

template<class TClass>
typedef vector<string> CPluginManager< TClass >::TSearchPaths

Container for the DLL search paths.

See also
ResetDllSearchPath

Definition at line 301 of file plugin_manager.hpp.

template<class TClass>
typedef set<string> CPluginManager< TClass >::TStringSet
protected

Definition at line 542 of file plugin_manager.hpp.

template<class TClass>
typedef map<string, string> CPluginManager< TClass >::TSubstituteMap
protected

Definition at line 543 of file plugin_manager.hpp.

Constructor & Destructor Documentation

template<class TClass >
CPluginManager< TClass >::CPluginManager ( void  )
template<class TClass >
CPluginManager< TClass >::~CPluginManager ( void  )
virtual

Definition at line 1263 of file plugin_manager.hpp.

References ITERATE, and NON_CONST_ITERATE.

Member Function Documentation

template<class TClass >
void CPluginManager< TClass >::AddDllSearchPath ( const string path)

Add path for the DLL lookup (for all resolvers)

Parameters
pathAdditional path for the DLL lookup
See also
ResetDllSearchPath

Definition at line 1108 of file plugin_manager.hpp.

template<class TClass >
void CPluginManager< TClass >::AddResolver ( CPluginManager_DllResolver resolver)

Attach DLL resolver to plugin manager.

Plugin manager uses all attached resolvers to search for DLLs exporting drivers of this interface.

Parameters
resolverDLL resolver. Plugin manager takes ownership of the resolver.
See also
DetachResolver

Definition at line 1088 of file plugin_manager.hpp.

References _ASSERT.

Referenced by CPluginManager< TClass >::CPluginManager().

template<class TClass>
TClass* CPluginManager< TClass >::CreateInstance ( const string driver = kEmptyStr,
const CVersionInfo version = GetDefaultDrvVers(),
const TPluginManagerParamTree params = 0 
)
inline

Create class instance.

Returns
Never returns NULL – always throw exception on error.
See also
GetFactory()

Definition at line 317 of file plugin_manager.hpp.

Referenced by CNetScheduleClientFactory::CreateInstance(), and CObjectManager::RegisterDataLoader().

template<class TClass >
TClass * CPluginManager< TClass >::CreateInstanceFromKey ( const TPluginManagerParamTree params,
const string driver_key,
const CVersionInfo version = GetDefaultDrvVers() 
)

Detect driver from the parameters using the key to get list of drivers.

Definition at line 776 of file plugin_manager.hpp.

References _TRACE, CTreeNode< TValue, TKeyGetter >::FindNode(), and CTreeNode< TValue, TKeyGetter >::GetValue().

template<class TClass >
TClass * CPluginManager< TClass >::CreateInstanceFromList ( const TPluginManagerParamTree params,
const string driver_list,
const CVersionInfo version = GetDefaultDrvVers() 
)

Create first available driver from the list of drivers.

Several driver names may be separated with ":".

Definition at line 745 of file plugin_manager.hpp.

References _TRACE, ERR_POST_XX, CTreeNode< TValue, TKeyGetter >::FindNode(), NStr::fSplit_MergeDelimiters, NStr::fSplit_Truncate, ITERATE, and NStr::Split().

template<class TClass >
CPluginManager_DllResolver * CPluginManager< TClass >::DetachResolver ( CPluginManager_DllResolver resolver)

Remove resolver from the list of active resolvers.

Method is used when we need to freeze some of the resolution variants Resolver is not deleted, and can be reattached again by AddResolver

Parameters
resolverDLL resolver. Ownership is returned to the caller and resolver should be deleted by the caller
Returns
Pointer on the detached resolver (same as resolver parameter) or NULL if resolver not found

Definition at line 1096 of file plugin_manager.hpp.

References NON_CONST_ITERATE.

template<class TClass >
CPluginManager< TClass >::TClassFactory * CPluginManager< TClass >::FindClassFactory ( const string driver,
const CVersionInfo version 
) const
protected
template<class TClass>
void CPluginManager< TClass >::FreezeResolution ( bool  value = true)
inline

Disable/enable DLL resolution (search for class factories in DLLs)

Definition at line 516 of file plugin_manager.hpp.

template<class TClass >
void CPluginManager< TClass >::FreezeResolution ( const string driver,
bool  value = true 
)

Disable/enable DLL resolution (search for class factories in DLLs) for the specified driver.

Definition at line 1143 of file plugin_manager.hpp.

template<class TClass>
static const CVersionInfo& CPluginManager< TClass >::GetDefaultDrvVers ( void  )
inlinestatic

Definition at line 303 of file plugin_manager.hpp.

template<class TClass >
CDllResolver::TExtraDllPath CPluginManager< TClass >::GetDllStdSearchPath ( void  ) const

Get standard locations which should be used for the DLL lookup.

See also
SetDllStdSearchPath

Definition at line 1137 of file plugin_manager.hpp.

template<class TClass >
CPluginManager< TClass >::TClassFactory * CPluginManager< TClass >::GetFactory ( const string driver = kEmptyStr,
const CVersionInfo version = GetDefaultDrvVers() 
)

Get class factory.

If more than one (of registered) class factory contain eligible driver candidates, then pick the class factory containing driver of the latest version.

Parameters
driverName of the driver. If passed empty, then – any.
versionRequested version. The returned driver can have a different (newer) version (provided that the new implementation is backward-compatible with the requested version.
Returns
Never return NULL – always throw exception on error.

Definition at line 800 of file plugin_manager.hpp.

References _TRACE, msg, and NCBI_THROW.

Referenced by CPluginManager< SNetScheduleAPIImpl >::CreateInstance().

template<class TClass >
bool CPluginManager< TClass >::RegisterFactory ( TClassFactory factory)

Try to register factory in the manager.

The registered factory will be owned by the manager.

Returns
true if a factory was registered.
See also
UnregisterFactory()

Definition at line 889 of file plugin_manager.hpp.

template<class TClass >
template<typename TEntryPoint >
bool CPluginManager< TClass >::RegisterWithEntryPoint ( TEntryPoint  plugin_entry_point)

Register all factories exported by the plugin entry point.

Returns
true if at least one factory was registered.
See also
RegisterFactory()

Definition at line 976 of file plugin_manager.hpp.

References _TRACE, and ITERATE.

Referenced by CNetScheduleClientFactory::CNetScheduleClientFactory().

template<class TClass >
template<typename TEntryPoint >
bool CPluginManager< TClass >::RegisterWithEntryPoint ( TEntryPoint  plugin_entry_point,
const string driver_name,
const CVersionInfo driver_version = CVersionInfo::kLatest 
)

Register all compatible factories for the driver with the particular version exported by the plugin entry point.

Returns
true if at least one factory was registered.
See also
RegisterFactory()

Definition at line 1034 of file plugin_manager.hpp.

References _TRACE, and ITERATE.

template<class TClass >
void CPluginManager< TClass >::ResetDllSearchPath ( TSearchPaths previous_paths = NULL)

Delete all user-installed paths for the DLL lookup (for all resolvers)

Parameters
previous_pathsIf non-NULL, store the previously set search paths in this container
See also
AddDllSearchPath

Definition at line 1114 of file plugin_manager.hpp.

template<class TClass >
void CPluginManager< TClass >::ResolveFile ( const string driver = kEmptyStr,
const CVersionInfo version = GetDefaultDrvVers() 
)
template<class TClass >
CDllResolver::TExtraDllPath CPluginManager< TClass >::SetDllStdSearchPath ( CDllResolver::TExtraDllPath  standard_paths)

Specify which standard locations should be used for the DLL lookup (for all resolvers).

If standard locations are not set explicitly using this method CDllResolver::fDefaultDllPath will be used by default.

See also
CDllResolver

Definition at line 1127 of file plugin_manager.hpp.

template<class TClass >
bool CPluginManager< TClass >::UnregisterFactory ( TClassFactory factory)

Unregister and release (un-own)

See also
RegisterFactory()

Definition at line 959 of file plugin_manager.hpp.

References _TRACE.

template<class TClass >
bool CPluginManager< TClass >::WillExtendCapabilities ( TClassFactory factory) const

Check if a given factory will extend capabilities of the Plugin Manager (add either new drivers or new driver versions to already available).

See also
RegisterFactory()

Definition at line 905 of file plugin_manager.hpp.

References _TRACE, CVersionInfo::eFullyCompatible, ERR_POST_XX, IClassFactory< TClass >::GetDriverVersions(), ITERATE, and Warning().

Member Data Documentation

template<class TClass>
bool CPluginManager< TClass >::m_BlockResolution
private

Flag, prohibits DLL resolution.

Definition at line 558 of file plugin_manager.hpp.

Referenced by CPluginManager< SNetScheduleAPIImpl >::FreezeResolution().

template<class TClass>
TSearchPaths CPluginManager< TClass >::m_DllSearchPaths
private

Paths used for DLL search.

Definition at line 554 of file plugin_manager.hpp.

template<class TClass>
TEntryPoints CPluginManager< TClass >::m_EntryPoints
private

List of entry points registered in this plugin manager.

Definition at line 550 of file plugin_manager.hpp.

template<class TClass>
TFactories CPluginManager< TClass >::m_Factories
private

List of factories presently registered with (and owned by) the plugin manager.

Definition at line 548 of file plugin_manager.hpp.

template<class TClass>
TStringSet CPluginManager< TClass >::m_FreezeResolutionDrivers
private

Set of drivers prohibited from DLL resolution.

Definition at line 560 of file plugin_manager.hpp.

template<class TClass>
CMutex CPluginManager< TClass >::m_Mutex
protected

Protective mutex to synchronize the access to the plugin manager from different threads.

Definition at line 533 of file plugin_manager.hpp.

template<class TClass>
TResolvedEntries CPluginManager< TClass >::m_RegisteredEntries
private

DLL entries resolved and registered with dll resolver(s)

Definition at line 556 of file plugin_manager.hpp.

template<class TClass>
TDllResolvers CPluginManager< TClass >::m_Resolvers
private

DLL resolvers.

Definition at line 552 of file plugin_manager.hpp.

template<class TClass>
CDllResolver::TExtraDllPath CPluginManager< TClass >::m_StdDllPath
private

Standard locations that should be used for the DLL lookup.

Definition at line 562 of file plugin_manager.hpp.

template<class TClass>
TSubstituteMap CPluginManager< TClass >::m_SubstituteMap
private

Driver name substitution map.

Definition at line 564 of file plugin_manager.hpp.

Referenced by CPluginManager< TClass >::CPluginManager(), and CPluginManager< SNetScheduleAPIImpl >::CreateInstance().


The documentation for this class was generated from the following file:
Modified on Sun Aug 20 16:47:01 2017 by modify_doxy.py rev. 533848