Fawkes API  Fawkes Development Version
fawkes::Module Class Reference

Dynamic module loader for Linux, FreeBSD, and MacOS X. More...

#include <>>

Public Types

enum  ModuleFlags {
  MODULE_FLAGS_NONE = 0, MODULE_FLAGS_DEFAULT = 0x000E, MODULE_BIND_LAZY = 0x0001, MODULE_BIND_NOW = 0x0002,
  MODULE_BIND_LOCAL = 0x0000, MODULE_BIND_GLOBAL = 0x0004, MODULE_BIND_MASK = 0x0003, MODULE_BIND_DEEP = 0x0008,
  MODULE_NODELETE = 0x1000
}
 Flags for the loading process. More...
 

Public Member Functions

 Module (std::string filename, ModuleFlags flags=MODULE_FLAGS_DEFAULT)
 Constructor. More...
 
virtual ~Module ()
 Destructor. More...
 
virtual void open ()
 Open the module. More...
 
virtual bool close ()
 Close the module. More...
 
virtual void ref ()
 Increment the reference count of this module. More...
 
virtual void unref ()
 Decrease the reference count of this module. More...
 
virtual bool notref ()
 Check if there are no reference to this module. More...
 
virtual unsigned int get_ref_count ()
 Get the reference count of this module. More...
 
virtual bool has_symbol (const char *symbol_name)
 Check if the module has the given symbol. More...
 
virtual void * get_symbol (const char *symbol_name)
 Get a symbol from the module. More...
 
virtual std::string get_filename ()
 Get the full file name of the module. More...
 
virtual std::string get_base_filename ()
 Get the base file name of the module. More...
 
virtual bool operator== (const Module &cmod)
 Compare to another Module instance. More...
 

Static Public Member Functions

static const char * get_file_extension ()
 Get file extension for dl modules. More...
 

Detailed Description

Dynamic module loader for Linux, FreeBSD, and MacOS X.

A Module implementation for the dl dynamic loader library that comes with glibc, applicable for Linux, FreeBSD, and MacOS X Systems.

For nice reading and hints about using dynamic module loading with C++ you should have a look at http://www.isotton.com/howtos/C++-dlopen-mini-HOWTO/C++-dlopen-mini-HOWTO.html

Author
Tim Niemueller

Definition at line 40 of file module.h.

Member Enumeration Documentation

◆ ModuleFlags

Flags for the loading process.

Enumerator
MODULE_FLAGS_NONE 

No flags.

MODULE_FLAGS_DEFAULT 

Default flags, these are MODULE_BIND_GLOBAL, MODULE_BIND_NOW and MODULE_BIND_DEEP.

MODULE_BIND_LAZY 

Perform lazy binding.

Only resolve symbols as thecode that references them is executed. If the symbol is never referenced,then it is never resolved. (Lazy binding is only performed for function references; references to variables are always immediately bound when the library is loaded.)

MODULE_BIND_NOW 

Resolve all symbols immediately when loading the library.

It's the opposite of MODULE_BIND_LAZY. It shall be the the default (makes sense for the framework robotics).

MODULE_BIND_LOCAL 

Symbols defined in this library are not made available to resolve references in subsequently loaded libraries.

It's the opposite of MODULE_BIND_GLOBAL. It shall be the default and MODULE_BIND_GLOBAL shall automatically override it.

MODULE_BIND_GLOBAL 

Symbols defined in this library are not made available to resolve references in subsequently loaded libraries.

MODULE_BIND_MASK 

Can be used to encode flags in a longer data field.

MODULE_BIND_DEEP 

Place the lookup scope of the symbols in this library ahead of the global scope.

This means that a self-contained library will use its own symbols in preference to global symbols with the same name contained in libraries that have already been loaded.

MODULE_NODELETE 

Do not unload the library during dlclose().

Consequently, the library's static variables are not reinitialized if the library is reloaded with dlopen() at a later time.

Definition at line 44 of file module.h.

Constructor & Destructor Documentation

◆ Module()

fawkes::Module::Module ( std::string  filename,
Module::ModuleFlags  flags = MODULE_FLAGS_DEFAULT 
)

Constructor.

Parameters
filenamefull filename of the module
flagsmodule flags

Definition at line 64 of file module.cpp.

◆ ~Module()

fawkes::Module::~Module ( )
virtual

Destructor.

Closes the module.

Definition at line 78 of file module.cpp.

Member Function Documentation

◆ close()

bool fawkes::Module::close ( )
virtual

Close the module.

Returns
Returns true if the module could be closed, false otherwise

Definition at line 151 of file module.cpp.

◆ get_base_filename()

std::string fawkes::Module::get_base_filename ( )
virtual

Get the base file name of the module.

Returns
Returns the base file name of the module. On Unix systems this is everything after the last slash

Definition at line 289 of file module.cpp.

Referenced by fawkes::ModuleManager::close_module(), and fawkes::ModuleManager::open_module().

◆ get_file_extension()

const char * fawkes::Module::get_file_extension ( )
static

Get file extension for dl modules.

Returns
Returns the file extension for dl modules, this is "so" on Linux and FreeBSD systems, and dylib on MacOS X. It is defined at compile time in config.mk.

Definition at line 268 of file module.cpp.

Referenced by fawkes::ModuleManager::get_module_file_extension().

◆ get_filename()

std::string fawkes::Module::get_filename ( )
virtual

Get the full file name of the module.

Returns
Returns a string with the full file name of the module

Definition at line 278 of file module.cpp.

◆ get_ref_count()

unsigned int fawkes::Module::get_ref_count ( )
virtual

Get the reference count of this module.

Returns
Returns the number of references to this module

Definition at line 202 of file module.cpp.

◆ get_symbol()

void * fawkes::Module::get_symbol ( const char *  symbol_name)
virtual

Get a symbol from the module.

Parameters
symbol_nameThe name of the symbol. NOTE: C++ symbols are mangled with type info and thus are not plainly available as symbol name. Use extern "C" to avoid this. Read http://www.isotton.com/howtos/C++-dlopen-mini-HOWTO/C++-dlopen-mini-HOWTO.html for more information on this topic.
Returns
Returns a pointer to the symbol or NULL if symbol was not found

Definition at line 253 of file module.cpp.

Referenced by fawkes::BlackBoardInstanceFactory::delete_interface_instance(), fawkes::PluginLoader::get_description(), fawkes::PluginLoader::get_module_manager(), and fawkes::BlackBoardInstanceFactory::new_interface_instance().

◆ has_symbol()

bool fawkes::Module::has_symbol ( const char *  symbol_name)
virtual

Check if the module has the given symbol.

Parameters
symbol_nameThe name of the symbol. NOTE: C++ symbols are mangled with type info and thus are not plainly available as symbol name. Use extern "C" to avoid this. Read http://www.isotton.com/howtos/C++-dlopen-mini-HOWTO/C++-dlopen-mini-HOWTO.html for more information on this topic.
Returns
Returns true if the symbol was found, false otherwise

Definition at line 230 of file module.cpp.

Referenced by fawkes::BlackBoardInstanceFactory::delete_interface_instance(), fawkes::PluginLoader::get_description(), fawkes::PluginLoader::get_module_manager(), and fawkes::BlackBoardInstanceFactory::new_interface_instance().

◆ notref()

bool fawkes::Module::notref ( )
virtual

Check if there are no reference to this module.

Returns
Returns true if there are no references to this module, false if there is at least one reference

Definition at line 192 of file module.cpp.

◆ open()

void fawkes::Module::open ( )
virtual

Open the module.

Returns
true if the module could be opened, false otherwise
Exceptions
ModuleOpenExceptionthrown if there was any problem while loading the module

Definition at line 89 of file module.cpp.

References fawkes::Exception::append(), fawkes::File::is_regular(), and fawkes::ModuleOpenException::ModuleOpenException().

Referenced by fawkes::ModuleManager::open_module().

◆ operator==()

bool fawkes::Module::operator== ( const Module cmod)
virtual

Compare to another Module instance.

Parameters
cmoda reference to the other comparison instance
Returns
Returns true, if the full file names of both modules are the same, false otherwise

Definition at line 214 of file module.cpp.

◆ ref()

void fawkes::Module::ref ( )
virtual

Increment the reference count of this module.

Definition at line 171 of file module.cpp.

◆ unref()

void fawkes::Module::unref ( )
virtual

Decrease the reference count of this module.

Definition at line 179 of file module.cpp.

Referenced by fawkes::BlackBoardInstanceFactory::delete_interface_instance().


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