Glib::Module Class Reference

Dynamic loading of modules. More...

#include <glibmm/module.h>

Public Types
enum class	Flags {   Flags::LAZY = 1 << 0 ,   Flags::LOCAL = 1 << 1 ,   Flags::MASK = 0x03 }
	Flags passed to g_module_open(). More...

Public Member Functions
	Module (const std::string & file_name, Flags flags=Flags(0))
	Opens a module. More...
	Module (const Module &)=delete
Module &	operator= (const Module &)=delete
	Module (Module && other) noexcept
Module &	operator= (Module && other) noexcept
virtual	~Module ()
	Close a module. More...
	operator bool () const
	Check whether the module was found. More...
void	make_resident ()
	Ensures that a module will never be unloaded. More...
bool	get_symbol (const std::string & symbol_name, void *& symbol) const
	Gets a symbol pointer from the module. More...
std::string	get_name () const
	Get the name of the module. More...
GModule *	gobj ()
const GModule *	gobj () const

Static Public Member Functions
static bool	get_supported ()
	Checks if modules are supported on the current platform. More...
static std::string	get_last_error ()
	Gets a string describing the last module error. More...
static std::string	build_path (const std::string & directory, const std::string & module_name)
	A portable way to build the filename of a module. More...

Protected Attributes
GModule *	gobject_

Detailed Description

Dynamic loading of modules.

These functions provide a portable way to dynamically load object files (commonly known as 'plug-ins'). The current implementation supports all systems that provide an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its shl_load() mechanism, and Windows platforms via DLLs.

Constructor & Destructor Documentation

Module() [1/3]

Glib::Module::Module ( const std::string &  file_name, Flags  flags = Flags(0)  )

explicit

Opens a module.

If the module has already been opened, its reference count is incremented. If not, the module is searched in the following order:

1. If file_name exists as a regular file, it is used as-is; else
2. If file_name doesn't have the correct suffix and/or prefix for the platform, then possible suffixes and prefixes will be added to the basename till a file is found and whatever is found will be used; else
3. If file_name doesn't have the ".la"-suffix, ".la" is appended. Either way, if a matching .la file exists (and is a libtool archive) the libtool archive is parsed to find the actual file name, and that is used.

At the end of all this, we would have a file path that we can access on disk, and it is opened as a module. If not, file_name is opened as a module verbatim in the hopes that the system implementation will somehow be able to access it.

Use operator bool() to see whether the operation succeeded. For instance,

Glib::Module module("plugins/helloworld");
if(module)
{
  void* func = nullptr;
  bool found = get_symbol("some_function", func);
}

Parameters

file_name	The name or path to the file containing the module, or an empty string to obtain a module representing the main program itself.
flags	The flags used for opening the module.

Module() [2/3]

Glib::Module::Module ( const Module &  )

delete

Module() [3/3]

Glib::Module::Module ( Module &&  other )

noexcept

~Module()

virtual Glib::Module::~Module ( )

virtual

Close a module.

The module will be removed from memory, unless make_resident has been called.

Member Function Documentation

build_path()

static std::string Glib::Module::build_path ( const std::string &  directory, const std::string &  module_name  )

static

A portable way to build the filename of a module.

The platform-specific prefix and suffix are added to the filename, if needed, and the result is added to the directory, using the correct separator character.

The directory should specify the directory where the module can be found. It can be an empty string to indicate that the module is in a standard platform-specific directory, though this is not recommended since the wrong module may be found.

For example, calling build_path() on a Linux system with a directory of /lib and a module_name of "mylibrary" will return /lib/libmylibrary.so. On a Windows system, using \Windows as the directory it will return \Windows\mylibrary.dll.

Parameters

directory	The directory the module is in
module_name	The name of the module

Returns

The system-specific filename of the module

Deprecated:

2.76: You will get the wrong results most of the time. Use the constructor instead with module_name as the basename of the file_name argument.

get_last_error()

static std::string Glib::Module::get_last_error ( )

static

Gets a string describing the last module error.

Returns

The error string

get_name()

std::string Glib::Module::get_name

(

)

const

Get the name of the module.

Returns

The name of the module

get_supported()

static bool Glib::Module::get_supported ( )

static

Checks if modules are supported on the current platform.

Returns

true if available, false otherwise

get_symbol()

bool Glib::Module::get_symbol	(	const std::string &	symbol_name,
		void *&	symbol
	)		const

Gets a symbol pointer from the module.

Parameters

symbol_name	The name of the symbol to lookup
symbol	A pointer to set to the symbol

Returns

True if the symbol was found, false otherwise.

gobj() [1/2]

GModule * Glib::Module::gobj ( )

inline

gobj() [2/2]

const GModule * Glib::Module::gobj ( ) const

inline

make_resident()

void Glib::Module::make_resident

(

)

Ensures that a module will never be unloaded.

Any calls to the Glib::Module destructor will not unload the module.

operator bool()

Glib::Module::operator bool ( ) const

explicit

Check whether the module was found.

operator=() [1/2]

Module & Glib::Module::operator= ( const Module &  )

delete

operator=() [2/2]

Module & Glib::Module::operator= ( Module &&  other )

noexcept

Member Data Documentation

gobject_

GModule* Glib::Module::gobject_

protected