C++ Library containing a lot of needful things: Stack Trace, Command Line Parser, Resource Handling, Configuration Files, Unix Command Execution, Directories, Regular Expressions, Tokenizer, Function Trace, Standard Extensions.
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
325 lines
10 KiB
325 lines
10 KiB
/** @file |
|
|
|
$Id$ |
|
|
|
$Date$ |
|
$Author$ |
|
|
|
@copy © Marc Wäckerlin |
|
@license LGPL, see file <a href="license.html">COPYING</a> |
|
|
|
$Log$ |
|
Revision 1.3 2005/11/29 12:39:42 marc |
|
make it compilable with gcc 4.0.2 and newer doxygen |
|
|
|
Revision 1.2 2005/02/21 16:16:47 marc |
|
finished and documented |
|
|
|
Revision 1.1 2005/02/18 15:53:56 marc |
|
initial release |
|
|
|
|
|
1 2 3 4 5 6 7 8 |
|
5678901234567890123456789012345678901234567890123456789012345678901234567890 |
|
*/ |
|
|
|
#ifndef __MRW_DYNAMICLIBRARY_HPP__ |
|
#define __MRW_DYNAMICLIBRARY_HPP__ |
|
|
|
#include <ltdl.h> |
|
#include <mrw/string.hxx> |
|
#include <mrw/stdext.hxx> |
|
#include <mrw/exception.hxx> |
|
|
|
namespace mrw { |
|
|
|
/** @defgroup dll Dynamic Library Loading (ltdl) |
|
|
|
Implements a C++ wrapper around the Libtool's |
|
platform independent dynamic library loading library named |
|
libltdl. See <code>info libtool</code> for more |
|
information. |
|
|
|
Loading a symbol from a shared library: |
|
|
|
@code |
|
void fn() { |
|
static DynamicLibrary lib("libsomething"); |
|
static void(*theRealFunction)() = |
|
(void(*)())lib.symbol("theRealFunction"); |
|
(*theRealFunction)(); // call the loaded function |
|
} |
|
@endcode |
|
|
|
@pre \#include <mrw/dynamiclibrary.hxx> |
|
|
|
@pre Files that use this wrapper must be linked with libltdl, |
|
with GNU g++ on UNIX, this is link option: @c -lltdl |
|
*/ |
|
//@{ |
|
|
|
//============================================================================ |
|
/** @brief Dynamic Library loaded from the filesystem at runtime. |
|
|
|
This class is responsible for loading dynamic / shared |
|
libraries from the filesystem and extract symbols, means |
|
functions to assign them to function pointers that can then be |
|
accessed. |
|
|
|
@copydoc dll |
|
*/ |
|
class DynamicLibrary { |
|
|
|
//............................................................... typedefs |
|
public: |
|
/// failure in access to shared libraries |
|
class failure: public mrw::runtime_error { |
|
public: |
|
failure(const std::string& arg) : |
|
mrw::runtime_error("DynamicLibrary failure "+arg |
|
+"; ltdl reason: "+ |
|
+mrw::ifelse(lt_dlerror(), "<none>")) { |
|
} |
|
}; |
|
|
|
//................................................................ methods |
|
public: |
|
|
|
/** @brief initialize, but open dynamic library later |
|
@throw failure if initialisation fails |
|
*/ |
|
DynamicLibrary() : _opened(false) { |
|
if (lt_dlinit()>0) |
|
throw failure("cannot initialize dynamic library loader"); |
|
_opened = true; |
|
} |
|
|
|
/** @brief load a dynamic library from a file |
|
|
|
It is not necessary to specify the extension, the system |
|
dependant shared object / dynamic library extension is |
|
automatically added. Also, if no path is given, the library |
|
is automatically looked for in your system's library |
|
paths. You can also specify additional paths to look in, |
|
e.g. with addSearchDir. |
|
|
|
@param lib the name of the library without the extension |
|
@throw failure if initialisation fails |
|
@throw failure if opeing the library fails |
|
*/ |
|
DynamicLibrary(const std::string& lib) : |
|
_opened(false) { |
|
if (lt_dlinit()>0) |
|
throw failure("cannot initialize dynamic library loader"); |
|
_opened = true; |
|
_lib.open(lib); |
|
} |
|
|
|
/// close and clean up |
|
~DynamicLibrary() noexcept { |
|
try {close();} catch (...) {} |
|
if (_opened) lt_dlexit(); |
|
} |
|
|
|
/** @brief load a dynamic library from a file |
|
|
|
It is not necessary to specify the extension, the system |
|
dependant shared object / dynamic library extension is |
|
automatically added. Also, if no path is given, the library |
|
is automatically looked for in your system's library |
|
paths. You can also specify additional paths to look in, |
|
e.g. with addSearchDir. |
|
|
|
@param lib the name of the library without the extension |
|
@throw failure if opeing the library fails |
|
*/ |
|
DynamicLibrary& open(const std::string& lib) { |
|
_lib.open(lib); |
|
return *this; |
|
} |
|
|
|
/** @brief close the dynamic library |
|
@throw failure if the library was open and close failed |
|
*/ |
|
DynamicLibrary& close() { |
|
if (!isResident()) _lib.close(); |
|
return *this; |
|
} |
|
|
|
/** @brief make the library resident |
|
|
|
Makes the library resident, so that it cannot be |
|
closed. This can be useful if a module implements some core |
|
functionality in your project, which would cause your code |
|
to crash if removed. |
|
|
|
@throw failure in case of an error |
|
*/ |
|
DynamicLibrary& resident() { |
|
if (lt_dlmakeresident(_lib.handle())!=0) |
|
throw failure("cannot make library resident"); |
|
return *this; |
|
} |
|
|
|
/** @brief check whether the library is resident |
|
@throw failure if the library is not open */ |
|
bool isResident() { |
|
return lt_dlisresident(_lib.handle())==1; |
|
} |
|
|
|
/** @brief load a symbol from the library |
|
|
|
@warning The symbol is returned as void* and must be |
|
converted to the correct function pointer. If this |
|
conversion is wrong, then your process will crash, or even |
|
worse, behave in an unexpected way, so be careful! |
|
*/ |
|
lt_ptr symbol(const std::string& name) { |
|
lt_ptr sym(lt_dlsym(_lib.handle(), name.c_str())); |
|
if (!sym) |
|
throw failure("cannot load dynamic library symbol: "+name); |
|
return sym; |
|
} |
|
|
|
/** register a list of preloaded modules |
|
|
|
@code |
|
const lt_dlsymlist symbols[] = { |
|
{"symbol1", &fnptr1}, {"symbol2", &fnptr2}, 0 |
|
} |
|
lib.preload(symbols); |
|
@endcode |
|
|
|
@param symbols a null terminated C array of structs of name |
|
character pointer and function pointer |
|
@note if symbols is @c 0, all previousely registered |
|
symbols except the list set by preloadDefault are deleted |
|
*/ |
|
DynamicLibrary& preload(const lt_dlsymlist symbols[]) |
|
{ |
|
if (lt_dlpreload(symbols)!=0) |
|
throw failure("error in preloading libraries"); |
|
return *this; |
|
} |
|
|
|
/** register the default list of preloaded modules |
|
|
|
@code |
|
const lt_dlsymlist symbols[] = { |
|
{"symbol1", &fnptr1}, {"symbol2", &fnptr2}, 0 |
|
} |
|
lib.preloadDefault(symbols); |
|
@endcode |
|
|
|
@param symbols a null terminated C array of structs of name |
|
character pointer and function pointer |
|
*/ |
|
static void preloadDefault(const lt_dlsymlist symbols[]) |
|
{ |
|
if (lt_dlpreload_default(symbols)!=0) |
|
throw failure("error in preloading libraries"); |
|
} |
|
|
|
/** @brief set the default list of preloaded symbols */ |
|
static void preloadedSymbols() { |
|
LTDL_SET_PRELOADED_SYMBOLS(); |
|
} |
|
|
|
/** @brief append a directory to the library search path */ |
|
static void addSearchDir(const std::string& dir) { |
|
if (lt_dladdsearchdir(dir.c_str())!=0) |
|
throw failure("cannot add search dir: "+dir); |
|
} |
|
|
|
/** @brief insert a directory at a given position to the library |
|
search path */ |
|
static void insertSearchDir(const std::string& before, |
|
const std::string& dir) |
|
{ |
|
if (lt_dlinsertsearchdir(before.c_str(), dir.c_str())!=0) |
|
throw failure("cannot add search dir: "+dir); |
|
} |
|
|
|
/** @brief set the library search path |
|
|
|
The search path is a colon separated list of paths. */ |
|
static void setSearchPath(const std::string& dirs) { |
|
if (lt_dlsetsearchpath(dirs.c_str())) |
|
throw failure("cannot set search path to "+dirs); |
|
} |
|
|
|
/** @brief get the library search path */ |
|
static std::string getSearchPath() { |
|
char const * const path(lt_dlgetsearchpath()); |
|
if (!path) |
|
throw failure("cannot get search path"); |
|
return path; |
|
} |
|
|
|
/** @brief calls a callback function for all directories in a |
|
search path |
|
|
|
In some applications you may not want to load individual |
|
modules with known names, but rather find all of the modules |
|
in a set of directories and load them all during |
|
initialisation. With this function you can have |
|
DynamicLibrary scan the colon delimited directory list in |
|
searchPath for candidates, and pass them, along with data to |
|
your own callback function, function. If searchPath is @c 0, |
|
then search all of the standard locations that open would |
|
examine. This function will continue to make calls to |
|
function for each file that it discovers in searchPath until |
|
one of these calls returns non-zero, or until the files are |
|
exhausted. |
|
|
|
@return value returned by the last call made to function |
|
*/ |
|
int foreachfile(const char* searchPath, |
|
int(*function)(const char*, lt_ptr), |
|
lt_ptr data) noexcept { |
|
return lt_dlforeachfile(searchPath, function, data); |
|
} |
|
|
|
private: |
|
class Lib { |
|
Lib() noexcept: _lib(0) {} |
|
Lib(const std::string& lib) : _lib(0) { |
|
open(lib); |
|
} |
|
~Lib() noexcept { |
|
try {close();} catch(...) {} |
|
} |
|
operator bool() noexcept { |
|
return _lib; |
|
} |
|
Lib& open(const std::string& lib) { |
|
close(); |
|
if (!(_lib = lt_dlopenext(lib.c_str()))) |
|
throw failure("cannot open dynamic library "+lib); |
|
return *this; |
|
} |
|
Lib& close() { |
|
if (_lib && lt_dlclose(_lib)!=0) |
|
throw failure("cannot close dynamic library"); |
|
_lib = 0; |
|
return *this; |
|
} |
|
private: |
|
friend class DynamicLibrary; |
|
lt_dlhandle handle() { |
|
if (!_lib) |
|
throw failure("library not open"); |
|
return _lib; |
|
} |
|
private: |
|
lt_dlhandle _lib; |
|
}; |
|
private: |
|
bool _opened; |
|
Lib _lib; |
|
}; |
|
|
|
//@} |
|
} |
|
|
|
#endif
|
|
|