gwymoduleloader

gwymoduleloader — Basic module loader interface

Functions

Types and Values

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

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

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

gwy_module_lookup ()

const GwyModuleInfo *
gwy_module_lookup (const gchar *name);

Returns information about one module.

Parameters

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

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

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

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

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

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

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

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

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

struct GwyModuleRecord

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

Module record returned by bundle query function.

Members

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

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

Since: 2.49