PluginTools Class Reference

#include <PluginTools.hh>

Collaboration diagram for PluginTools:

Public Member Functions
	PluginTools (bool lazyResolution=true, bool local=false)
virtual	~PluginTools ()
void	addSearchPath (const std::string &searchPath)
void	removeSearchPath (const std::string &searchPath)
void	clearSearchPaths ()
void	registerModule (const std::string &module)
void	unregisterModule (const std::string &module)
void	unregisterAllModules ()
template<typename T >
void	importSymbol (const std::string &symbolName, T *&target, const std::string &module)
template<typename T >
void	importSymbol (const std::string &symbolName, T *&target)

Private Types
typedef std::vector< std::string >::iterator	VecIter
typedef std::map< std::string, void * >::iterator	MapIter
typedef std::map< std::string, void * >::value_type	ValType

Private Member Functions
void *	loadSym (const std::string &symbolName, const std::string &module="")
std::string	findModule (const std::string &module)
	PluginTools (const PluginTools &)
	Copying not allowed.
PluginTools &	operator= (const PluginTools &)
	Assignment not allowed.

Private Attributes
std::vector< std::string >	searchPaths_
	Search paths of dynamic modules.
std::map< std::string, void * >	modules_
	Map containing opened module handles.
bool	lazyResolution_
	True if all undefined symbols should be resolved only when needed.
bool	localResolution_
	True if the symbols defined in the loaded library should be made available for symbol resolution of subsequently loaded libraries.

Detailed Description

Class that handles accessing of dynamic modules for providing run-time plug-in functionality.

Class allows defining search paths, in which modules are searched. This enables registering modules without absolut paths to modules. Symbols (variables, functions) are loaded from modules and automatically cast to correct types by means of the template mechanism.

Definition at line 53 of file PluginTools.hh.

Member Typedef Documentation

MapIter

typedef std::map<std::string,void*>::iterator PluginTools::MapIter

private

Definition at line 75 of file PluginTools.hh.

ValType

typedef std::map<std::string,void*>::value_type PluginTools::ValType

private

Definition at line 76 of file PluginTools.hh.

VecIter

typedef std::vector<std::string>::iterator PluginTools::VecIter

private

Definition at line 74 of file PluginTools.hh.

Constructor & Destructor Documentation

PluginTools() [1/2]

PluginTools::PluginTools	(	bool	lazyResolution = true,
		bool	local = false
	)

Constructor.

The created instance has no search paths registered.

Parameters

lazyResolution	True if symbol resolution should be done lazily.
localResolution	True in case the symbols are loaded locally to the process only and not made visible to later plugin loads.

Note

Throwing C++ exceptions from plugin to the loader might not work with the lazy resolution! It's probably safest to set the argument to "false".

Definition at line 73 of file PluginTools.cc.

                                                        :
    lazyResolution_(lazyResolution), localResolution_(local) {
}

~PluginTools()

PluginTools::~PluginTools ( )

virtual

Destructor.

Unregisters all modules.

Definition at line 83 of file PluginTools.cc.

                          {
    unregisterAllModules();
}

References unregisterAllModules().

Here is the call graph for this function:

PluginTools() [2/2]

PluginTools::PluginTools ( const PluginTools &  )

private

Copying not allowed.

Member Function Documentation

addSearchPath()

void PluginTools::addSearchPath

(

const std::string &

searchPath

)

Adds a new search path in search path list.

Parameters

searchPath

The search path to be added.

Exceptions

FileNotFound

If path doesn't exist.

Definition at line 95 of file PluginTools.cc.

                                                      {
    if (!(FileSystem::fileExists(searchPath))) {
        string method = "PluginTools::addSearchPath()";
        string message = "Path doesn't exist";
        throw FileNotFound(__FILE__, __LINE__, method, message);
    }
    searchPaths_.push_back(searchPath);
}

References FileSystem::fileExists(), and searchPaths_.

Referenced by ProgramImageGenerator::createCompressor(), LLVMBackend::createPlugin(), GenerateProcessor::listICDecPluginParameters(), DesignSpaceExplorer::loadExplorerPlugin(), ProGe::ProGeUI::loadICDecoderGeneratorPlugin(), GenerateProcessorDialog::loadICDecoderGeneratorPlugin(), ProcessorImplementationWindow::loadICDecoderPlugin(), and CompiledSimController::reset().

Here is the call graph for this function:

clearSearchPaths()

void PluginTools::clearSearchPaths

(

)

Clears all search paths from search path list.

Definition at line 119 of file PluginTools.cc.

                              {
    searchPaths_.clear();
}

References searchPaths_.

findModule()

string PluginTools::findModule ( const std::string &  module )

private

Looks for the path for the module and returns it if it is found.

Parameters

module

The module to be searched for.

Returns

The path for the module.

Exceptions

MultipleInstacesFound	If multiple instances of module are found.
FileNotFOund	If module is not found at all.

Definition at line 346 of file PluginTools.cc.

                                               {
    string path = "";
    bool moduleFound = false;
    for (MapIter mt = modules_.begin(); mt != modules_.end(); mt++) {
 
        const string fullPath = (*mt).first;
        const string fileName = FileSystem::fileOfPath(fullPath);
        if (module == fullPath ||
            module == fileName ||
            StringTools::endsWith(fullPath, std::string("/") + module)) {
 
            if (moduleFound) {
                string method = "PluginTools::findModule()";
                string message = "Multiple modules found";
                throw MultipleInstancesFound(
                    __FILE__, __LINE__, method, message);
            }
 
            path = (*mt).first;
            moduleFound = true;
        }
    }
 
    if (!moduleFound) {
        string method = "PluginTools::findModule()";
        string message = "Module not found";
        throw FileNotFound(__FILE__, __LINE__, method, message);
    }
 
    return path;
}

References StringTools::endsWith(), FileSystem::fileOfPath(), and modules_.

Referenced by loadSym(), and unregisterModule().

Here is the call graph for this function:

importSymbol() [1/2]

template<typename T >

void PluginTools::importSymbol	(	const std::string &	symbolName,
		T *&	target
	)

importSymbol() [2/2]

template<typename T >

void PluginTools::importSymbol	(	const std::string &	symbolName,
		T *&	target,
		const std::string &	module
	)

Referenced by LLVMBackend::compile(), CompiledSimulation::compileAndLoadFunction(), ProgramImageGenerator::createCompressor(), LLVMBackend::createPlugin(), OperationBehaviorLoader::importBehavior(), GenerateProcessor::listICDecPluginParameters(), DesignSpaceExplorer::loadExplorerPlugin(), ProGe::ProGeUI::loadICDecoderGeneratorPlugin(), GenerateProcessorDialog::loadICDecoderGeneratorPlugin(), ProcessorImplementationWindow::loadICDecoderPlugin(), and CompiledSimController::reset().

loadSym()

void * PluginTools::loadSym ( const std::string &  symbolName, const std::string &  module = ""  )

private

Loads symbol from module.

If module is not given, then all modules are searched in order to find the symbol. Note that the search order of modules is not necessarily the same as the registration order!

Parameters

symbolName	The symbol being loaded.
module	The module where symbol is loaded.

Returns

Pointer to loaded symbol.

Exceptions

MultipleInstancesFound	If multiple instances of module are found.
DynamicLibraryException	If dlsym() fails.
FileNotFound	If module is not found.
SymbolNotFound	If symbol to be loaded is not found.

Definition at line 271 of file PluginTools.cc.

                                                                         {
    string path = module;
    if (module != "") {
 
        if (!FileSystem::isAbsolutePath(module)) {
            try {
                path = findModule(module);
            } catch (const FileNotFound& f) {
                // file was not found, so let's try to register it.
                registerModule(module);
                path = findModule(module);
            }
        } else {
            if (!MapTools::containsKey(modules_, path)) {
                registerModule(path);
            }
        }
 
        MapIter mt = modules_.find(path);
        void* handle = (*mt).second;
        const char* error = NULL;
 
        // clear possible old errors
        dlerror();
 
        void* sym = dlsym(handle, symbolName.c_str());
        if ((error = dlerror()) != NULL) {
            if (sym == NULL) {
                // it does not seem to be possible to separate the
                // symbol not found error from other errors, thus this will 
                // probably always throw SymbolNotFound in case the symbol
                // could not be loaded for any reason
                string message = "Symbol not found: ";
                message += symbolName;
                throw SymbolNotFound(__FILE__, __LINE__, __func__, message);
            } else {
                throw DynamicLibraryException(
                    __FILE__, __LINE__, __func__, error);
            }
        }
 
        return sym;
 
    } else {
 
        // seek all registered modules for the symbol and return the first
        // one found
        for (MapIter mt = modules_.begin(); mt != modules_.end(); mt++) {
            void* handle = (*mt).second;
            const char* error = NULL;
            dlerror();
            void* sym = dlsym(handle, symbolName.c_str());
            if ((error = dlerror()) == NULL) {
                return sym;
            }
        }
 
        // symbol was not found, exception is thrown
        string method = "PluginTools::loadSym()";
        string message = "Symbol not found";
        throw SymbolNotFound(__FILE__, __LINE__, method, message);
    }
 
    return NULL;
}

References __func__, MapTools::containsKey(), findModule(), FileSystem::isAbsolutePath(), modules_, and registerModule().

Here is the call graph for this function:

operator=()

PluginTools & PluginTools::operator= ( const PluginTools &  )

private

Assignment not allowed.

registerModule()

void PluginTools::registerModule

(

const std::string &

module

)

Registers a module in registry.

If module is not an absolute path, then it is searched from search paths added with addSearchPath() in the order of addition. First module found is used. If module already exists in the registry, it's not opened again. RTLD_LOCAL and RTLD_NOW flags are used by default when opening the module.

Parameters

module

The module to be registered.

Exceptions

FileNotFound	If module is not found.
DynamicLibraryException	if dlopen() fails.

Definition at line 138 of file PluginTools.cc.

                                                   {
    if (module.empty()) {
        string method = "PluginTools::registerModule()";
        string message = "Empty module file name.";
        throw FileNotFound(__FILE__, __LINE__, method, message);
    }
 
    const string DIR_SEP = FileSystem::DIRECTORY_SEPARATOR;
 
    string path = module;                     
    if (!FileSystem::isAbsolutePath(module)) {
 
        bool moduleFound = false;
 
        // module is not an absolute path
        for (unsigned int i = 0; i < searchPaths_.size(); i++) {
            path = searchPaths_[i] + DIR_SEP + module;
            if (FileSystem::fileExists(path)) {
                moduleFound = true;                   
                break;
            }
        }
 
        if (!moduleFound) {
            string method = "PluginTools::registerModule()";
            string message = "Module not found";
            throw FileNotFound(__FILE__, __LINE__, method, message);
        }
    }
 
    // multiple registrations are ignored
    if (!MapTools::containsKey(modules_, path)) {
 
        void* handle = NULL;
 
        int flags = 0;
        if (lazyResolution_) {
            flags |= RTLD_LAZY;
        } else {
            flags |= RTLD_NOW;
        }
 
        if (localResolution_) {
            flags |= RTLD_LOCAL;
        } else {
            flags |= RTLD_GLOBAL;
        }
 
        handle = dlopen(path.c_str(), flags);
 
        if (handle == NULL) {
            string method = "PluginTools::registerModule()";
            string message = dlerror();
            throw DynamicLibraryException(__FILE__, __LINE__, method, message);
        }
 
        modules_.insert(ValType(path, handle));
    }
}

References MapTools::containsKey(), DIR_SEP, FileSystem::DIRECTORY_SEPARATOR, FileSystem::fileExists(), FileSystem::isAbsolutePath(), lazyResolution_, localResolution_, modules_, RTLD_LOCAL, and searchPaths_.

Referenced by CompiledSimulation::compileAndLoadFunction(), ProgramImageGenerator::createCompressor(), LLVMBackend::createPlugin(), GenerateProcessor::listICDecPluginParameters(), DesignSpaceExplorer::loadExplorerPlugin(), ProGe::ProGeUI::loadICDecoderGeneratorPlugin(), GenerateProcessorDialog::loadICDecoderGeneratorPlugin(), ProcessorImplementationWindow::loadICDecoderPlugin(), loadSym(), and CompiledSimController::reset().

Here is the call graph for this function:

removeSearchPath()

void PluginTools::removeSearchPath

(

const std::string &

searchPath

)

Removes search path from search path list if it is found.

Parameters

searchPath

the search path to be removed.

Definition at line 110 of file PluginTools.cc.

                                                         {
    ContainerTools::removeValueIfExists(searchPaths_, searchPath);
}

References ContainerTools::removeValueIfExists(), and searchPaths_.

Here is the call graph for this function:

unregisterAllModules()

void PluginTools::unregisterAllModules

(

)

Unregisters all modules.

All modules are closed by using dlclose() and registry is emptied.

Exceptions

DynamicLibraryException

If dlclose() fails.

Definition at line 236 of file PluginTools.cc.

                                  {
    MapIter mt;
    for (mt = modules_.begin(); mt != modules_.end(); mt++) {
        void* handle = (*mt).second;
        std::string moduleName = (*mt).first;
        dlclose(handle);
    // Removing check. This is called on the global destructor
    // stage and in some systems (FreeBSD) libraries are already
    // unloaded by then which would cause this to fail unneccessarily.
//         if (dlclose(handle) != 0) {
//             string method = "PluginTools::unregisterAllModules()";
//             string message = dlerror();
//             throw DynamicLibraryException(__FILE__, __LINE__, method, message);
//         }
    }
    modules_.clear();
}

References modules_.

Referenced by OperationBehaviorLoader::freeBehavior(), and ~PluginTools().

unregisterModule()

void PluginTools::unregisterModule

(

const std::string &

module

)

A module is closed using dlclose() and it is removed from registry.

Parameters

module

The module to be unregistered.

Exceptions

FileNotFound	If module is not found.
DynamicLibraryException	If dlclose() fails.
MultipleInstancesFound	If multiple modules are found.

Definition at line 207 of file PluginTools.cc.

                                                     {
    string method = "PluginTools::unregisterModule()";
    string path = module;
    if (!FileSystem::isAbsolutePath(module)) {
        path = findModule(module);
    }
 
    MapIter mt = modules_.find(path);
    if (mt == modules_.end()) {
        string msg = "Module not found";
        throw FileNotFound(__FILE__, __LINE__, method, msg);
    }
 
    void* handle = (*mt).second;
    modules_.erase(mt);
    if (dlclose(handle) != 0) {
        string message = dlerror();
        throw DynamicLibraryException(__FILE__, __LINE__, method, message);
    }
}

References findModule(), FileSystem::isAbsolutePath(), and modules_.

Here is the call graph for this function:

Member Data Documentation

lazyResolution_

bool PluginTools::lazyResolution_

private

True if all undefined symbols should be resolved only when needed.

Definition at line 94 of file PluginTools.hh.

Referenced by registerModule().

localResolution_

bool PluginTools::localResolution_

private

True if the symbols defined in the loaded library should be made available for symbol resolution of subsequently loaded libraries.

Definition at line 97 of file PluginTools.hh.

Referenced by registerModule().

modules_

std::map<std::string, void*> PluginTools::modules_

private

Map containing opened module handles.

Definition at line 91 of file PluginTools.hh.

Referenced by findModule(), loadSym(), registerModule(), unregisterAllModules(), and unregisterModule().

searchPaths_

std::vector<std::string> PluginTools::searchPaths_

private

Search paths of dynamic modules.

Definition at line 89 of file PluginTools.hh.

Referenced by addSearchPath(), clearSearchPaths(), registerModule(), and removeSearchPath().

---

The documentation for this class was generated from the following files:

• PluginTools.hh
• PluginTools.cc