Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

gwymoduleloader (HEAD)

gwymoduleloader — Basic module loader interface

Functions

#define	GWY_MODULE_QUERY()
#define	GWY_MODULE_QUERY2()
gboolean	(*GwyModuleRegisterFunc) ()
GwyModuleInfo *	(*GwyModuleQueryFunc) ()
const GwyModuleRecord *	(*GwyModuleBundleRegisterFunc) ()
GQuark	gwy_module_error_quark ()
void	gwy_module_register_modules ()
const GwyModuleInfo *	gwy_module_lookup ()
const gchar *	gwy_module_get_filename ()
GSList *	gwy_module_get_functions ()
void	gwy_module_foreach ()
void	gwy_module_failure_foreach ()
const GwyModuleInfo *	gwy_module_register_module ()
void	gwy_module_disable_registration ()
void	gwy_module_enable_registration ()
gboolean	gwy_module_is_enabled ()

Types and Values

#define	GWY_MODULE_ABI_VERSION
#define	GWY_MODULE_BUNDLE_FLAG
#define	GWY_MODULE_ERROR
enum	GwyModuleError
struct	GwyModuleRecord
struct	GwyModuleInfo
	GwyModuleFailureInfo

Includes

#include <libgwymodule/gwymodule.h>

Description

Functions

GWY_MODULE_QUERY()

#define             GWY_MODULE_QUERY(mod_info)

The module query must be the ONLY exported symbol from a module.

This macro does The Right Thing necessary to export module info in a way Gwyddion understands it. Put GWY_MODULE_QUERY with the module info (GwyModuleInfo) of your module as its argument on a line (with NO semicolon after).

If you write a module in C++ note the module query must have C linkage. This is achieved by marking it extern "C":

1
2
3

extern "C" {
GWY_MODULE_QUERY(module_info)
}

This has to be done manually in versions up to 2.24; since version 2.25 * GWY_MODULE_QUERY() includes extern "C" automatically if it is compiled using a C++ compiler.

Parameters

mod_info

The GwyModuleInfo structure to return as module info.

GWY_MODULE_QUERY2()

#define             GWY_MODULE_QUERY2(mod_info,mod_name)

The module query must be the ONLY exported symbol from a module.

See GWY_MODULE_QUERY for discussion.

This macro is intended for modules that can be bundled together to one big shared library for time and space optimization. This mostly makes sense only for modules included in Gwyddion itself as it contains hundreds of modules.

However, it safe to use in third party modules because if modules are not bundled the macro behaves exactly as GWY_MODULE_QUERY and the mod_name argument is just ignored. The macro expansion differs only when GWY_MODULE_BUNDLING is defined when including the "gwymoduleloader.h" header.

The module name mod_name is given as a C identifier, not a string. It must be identical to the file name of the module if it was installed standalone, with extension removed and with non-identifier characters converted to underscores. For instance module implemented in "nt-mdt.c" and installed as "nt-mdt.so" or "nt-mdt.dll" (or with other extensions, depending on the operating system) must pass nt_mdt. If it does not match the file name, linking will fail with a confusing message when bundling is enabled.

Parameters

mod_info	The GwyModuleInfo structure to return as module info.
mod_name	Module name, given as C identifier corresponding to file name withough extension.

Since: 2.49

GwyModuleRegisterFunc ()

gboolean
(*GwyModuleRegisterFunc) (void);

Module registration function type.

It actually runs particular featrue registration functions, like gwy_file_func_register() and gwy_process_func_register().

If the module has a complex initialisation it may be safer to simply not register any function but return TRUE even if it fails to set up itself correctly. The module feature unregistration is somewhat crude and, generally, unregisteration may lead to disaster when shared library unloading has unexpected side effects.

Returns

Whether the registration succeeded. When it returns FALSE, the module and its features are unregistered.

GwyModuleQueryFunc ()

GwyModuleInfo *
(*GwyModuleQueryFunc) (void);

Module query function type.

The module query function should be simply declared as GWY_MODULE_QUERY(mod_info), where mod_info is module info struct for the module.

Returns

The module info struct.

GwyModuleBundleRegisterFunc ()

const GwyModuleRecord *
(*GwyModuleBundleRegisterFunc) (void);

Module bundle query function type.

It returns an array of module records for all modules in the bundle, terminated by {NULL, NULL}.

Since: 2.49

gwy_module_error_quark ()

GQuark
gwy_module_error_quark (void);

Returns error domain for module loading.

See and use GWY_MODULE_ERROR.

Returns

The error domain.

gwy_module_register_modules ()

void
gwy_module_register_modules (const gchar **paths);

Registers all modules in given directories.

It can be called several times (on different directories). No errors are reported, register modules individually with gwy_module_register_module() to get registration errors.

If you need to prevent specific modules from loading use gwy_module_disable_registration() beforehand.

Parameters

paths

A NULL-terminated list of directory names.

gwy_module_lookup ()

const GwyModuleInfo *
gwy_module_lookup (const gchar *name);

Returns information about one module.

Parameters

name

A module name.

Returns

The module info, of NULL if not found. It must be considered constant and never modified or freed.

gwy_module_get_filename ()

const gchar *
gwy_module_get_filename (const gchar *name);

Returns full file name of a module.

Parameters

name

A module name.

Returns

Module file name as a string that must be modified or freed.

gwy_module_get_functions ()

GSList *
gwy_module_get_functions (const gchar *name);

Returns list of names of functions a module implements.

Parameters

name

A module name.

Returns

List of module function names, as a GSList that is owned by module loader and must not be modified or freed.

gwy_module_foreach ()

void
gwy_module_foreach (GHFunc function,
                    gpointer data);

Runs function on each registered module.

It passes module name as the key and pointer to module info (GwyModuleInfo) as the value. Neither should be modified.

Parameters

function	A GHFunc run for each module.
data	User data.

gwy_module_failure_foreach ()

void
gwy_module_failure_foreach (GFunc function,
                            gpointer data);

Runs function for each module that failed to register.

It passes the failure info (GwyModuleFailureInfo) as the data argument. It should be modified.

Parameters

function	A GFunc run for each module registration failure.
data	User data.

Since: 2.49

gwy_module_register_module ()

const GwyModuleInfo *
gwy_module_register_module (const gchar *name,
                            GError **error);

Loads a single module.

This function also works with bundles. The returned module info is for the bundle and thus not of much use.

Parameters

name	Module file name to load, including full path and extension.
error	Location to store error, or `NULL` to ignore them. Errors from GwyModuleError domain can occur.

Returns

Module info on success, NULL on failure.

gwy_module_disable_registration ()

void
gwy_module_disable_registration (const gchar *name);

Prevents the registration of a module of given name.

This function blocks future module registration using gwy_module_register_modules(). Already loaded modules are unaffected. The low-level module loading function gwy_module_register_module() always attempts to load the module, even if blocked.

Parameters

name

A module name.

Since: 2.48

gwy_module_enable_registration ()

void
gwy_module_enable_registration (const gchar *name);

Unblocks the registration of a module of given name.

This function influences future module registration. Already loaded modules are unaffected.

Parameters

name

A module name.

Since: 2.48

gwy_module_is_enabled ()

gboolean
gwy_module_is_enabled (const gchar *name);

Reports whether the registration of a module is enabled.

If the registration of module name was prevented using gwy_module_disable_registration() and not subsequently re-enabled using gwy_module_enabled_registration() this function returns FALSE.

The reported values only represents the current state of blocking. A module name could have been loaded when it was not blocked.

Parameters

name

A module name.

Returns

TRUE if module name can be registered; FALSE when it is blocked from registration.

Since: 2.48

Types and Values

GWY_MODULE_ABI_VERSION

#define GWY_MODULE_ABI_VERSION 2

Gwyddion module ABI version.

To be filled as abi_version in GwyModuleInfo.

GWY_MODULE_BUNDLE_FLAG

#define GWY_MODULE_BUNDLE_FLAG 256u

Value to bitwise combine with GWY_MODULE_ABI_VERSION to indicate a bundle.

Since: 2.49

GWY_MODULE_ERROR

#define GWY_MODULE_ERROR gwy_module_error_quark()

enum GwyModuleError

Type of module loading and registration error.

Members

GWY_MODULE_ERROR_NAME	Module has an invalid name. It is recommended that module names are valid C identifiers, possibly with dashes instead of underscores, but only really broken names are rejected.
GWY_MODULE_ERROR_DUPLICATE	A module of the same name has already been registered.
GWY_MODULE_ERROR_OPEN	Calling `g_module_open()` on the module failed.
GWY_MODULE_ERROR_QUERY	Module does not contain any query function.
GWY_MODULE_ERROR_ABI	Module has different ABI version than expected/supported; or required info field are missing.
GWY_MODULE_ERROR_INFO	Module query function provided `NULL` info.
GWY_MODULE_ERROR_REGISTER	The registration function returned `FALSE`; or the module did not register any function.
GWY_MODULE_ERROR_NESTING	Nested module bundle found. (Since 2.49)

struct GwyModuleRecord

struct GwyModuleRecord {
    GwyModuleQueryFunc query;
    const gchar *name;
};

Module record returned by bundle query function.

Members

GwyModuleQueryFunc `query`;	Module query function.
const gchar *`name`;	Module name (base file name without extensions).

Since: 2.49

struct GwyModuleInfo

struct GwyModuleInfo {
    guint32 abi_version;
    GwyModuleRegisterFunc register_func;
    const gchar *blurb;
    const gchar *author;
    const gchar *version;
    const gchar *copyright;
    const gchar *date;
};

Module information returned by GWY_MODULE_QUERY().

Members

guint32 `abi_version`;	Gwyddion module ABI version, should be always GWY_MODULE_ABI_VERSION.
GwyModuleRegisterFunc `register_func`;	Module registration function (the function run by Gwyddion module system, actually registering particular module features).
const gchar *`blurb`;	Some module description.
const gchar *`author`;	Module author(s).
const gchar *`version`;	Module version.
const gchar *`copyright`;	Who has copyright on this module.
const gchar *`date`;	Date (year).

GwyModuleFailureInfo

typedef struct {
    const gchar *filename;
    const gchar *modname;
    const gchar *err_message;
    gint err_domain;
    gint err_code;
} GwyModuleFailureInfo;

Information about a failed module registration.

Members

const gchar *`filename`;	Name of the file the module was loaded from.
const gchar *`modname`;	Module name (can be `NULL` and contain odd bytes).
const gchar *`err_message`;	Error message from the failed module registration.
gint `err_domain`;	GError domain from the failed module registration.
gint `err_code`;	GError code from the failed module registration.

Since: 2.49