/src/wrappers/glib/library/core/glib_dynamic_loading_of_modules.e
http://github.com/tybor/Liberty · Specman e · 303 lines · 2 code · 97 blank · 204 comment · 0 complexity · 07821c677096ee5faec35f0b765dd454 MD5 · raw file
- deferred class GLIB_DYNAMIC_LOADING_OF_MODULES
-
- -- Dynamic Loading of Modules
- -- Dynamic Loading of Modules -- portable method for dynamically loading
- -- 'plug-ins'.
- -- Synopsis
- -- #include <gmodule.h>
- -- GModule;
- -- gboolean g_module_supported (void);
- -- gchar* g_module_build_path (const gchar *directory,
- -- const gchar *module_name);
- -- GModule* g_module_open (const gchar *file_name,
- -- GModuleFlags flags);
- -- enum GModuleFlags;
- -- gboolean g_module_symbol (GModule *module,
- -- const gchar *symbol_name,
- -- gpointer *symbol);
- -- const gchar* g_module_name (GModule *module);
- -- void g_module_make_resident (GModule *module);
- -- gboolean g_module_close (GModule *module);
- -- const gchar* g_module_error (void);
- -- const gchar* (*GModuleCheckInit) (GModule *module);
- -- void (*GModuleUnload) (GModule *module);
- -- #define G_MODULE_SUFFIX
- -- #define G_MODULE_EXPORT
- -- #define G_MODULE_IMPORT
- -- Description
- -- 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.
- -- A program which wants to use these functions must be linked to the libraries
- -- output by the command pkg-config --libs gmodule-2.0.
- -- To use them you must first determine whether dynamic loading is supported on the
- -- platform by calling g_module_supported(). If it is, you can open a module with
- -- g_module_open(), find the module's symbols (e.g. function names) with
- -- g_module_symbol(), and later close the module with g_module_close().
- -- g_module_name() will return the file name of a currently opened module.
- -- If any of the above functions fail, the error status can be found with
- -- g_module_error().
- -- The GModule implementation features reference counting for opened modules, and
- -- supports hook functions within a module which are called when the module is
- -- loaded and unloaded (see GModuleCheckInit and GModuleUnload).
- -- If your module introduces static data to common subsystems in the running
- -- program, e.g. through calling g_quark_from_static_string ("my-module-stuff"), it
- -- must ensure that it is never unloaded, by calling g_module_make_resident().
- -- Example 12. Calling a function defined in a GModule
- -- /* the function signature for 'say_hello' */
- -- typedef void (* SayHelloFunc) (const char *message);
- -- gboolean
- -- just_say_hello (const char *filename, GError **error)
- -- {
- -- SayHelloFunc say_hello;
- -- GModule *module;
- -- module = g_module_open (filename, G_MODULE_BIND_LAZY);
- -- if (!module)
- -- {
- -- g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
- -- "%s", g_module_error ());
- -- return FALSE;
- -- }
- -- if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
- -- {
- -- g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
- -- "%s: %s", filename, g_module_error ());
- -- if (!g_module_close (module))
- -- g_warning ("%s: %s", filename, g_module_error ());
- -- return FALSE;
- -- }
- -- /* call our function in the module */
- -- say_hello ("Hello world!");
- -- if (!g_module_close (module))
- -- g_warning ("%s: %s", filename, g_module_error ());
- -- return TRUE;
- -- }
- -- Details
- -- GModule
- -- typedef struct _GModule GModule;
- -- The GModule struct is an opaque data structure to represent a Dynamically-Loaded
- -- Module. It should only be accessed via the following functions.
- -- ---------------------------------------------------------------------------------
- -- g_module_supported ()
- -- gboolean g_module_supported (void);
- -- Checks if modules are supported on the current platform.
- -- Returns : TRUE if modules are supported.
- -- ---------------------------------------------------------------------------------
- -- g_module_build_path ()
- -- gchar* g_module_build_path (const gchar *directory,
- -- const gchar *module_name);
- -- 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 NULL or 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 g_module_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.
- -- directory : the directory where the module is. This can be NULL or the empty
- -- string to indicate that the standard platform-specific directories
- -- will be used, though that is not recommended.
- -- module_name : the name of the module.
- -- Returns : the complete path of the module, including the standard library
- -- prefix and suffix. This should be freed when no longer needed.
- -- ---------------------------------------------------------------------------------
- -- g_module_open ()
- -- GModule* g_module_open (const gchar *file_name,
- -- GModuleFlags flags);
- -- Opens a module. If the module has already been opened, its reference count is
- -- incremented.
- -- First of all g_module_open() tries to open file_name as a module. If that fails
- -- and file_name has the ".la"-suffix (and is a libtool archive) it tries to open
- -- the corresponding module. If that fails and it doesn't have the proper module
- -- suffix for the platform (G_MODULE_SUFFIX), this suffix will be appended and the
- -- corresponding module will be opended. If that fails and file_name doesn't have
- -- the ".la"-suffix, this suffix is appended and g_module_open() tries to open the
- -- corresponding module. If eventually that fails as well, NULL is returned.
- -- file_name : the name of the file containing the module, or NULL to obtain a
- -- GModule representing the main program itself.
- -- flags : the flags used for opening the module. This can be the logical OR of
- -- any of the GModuleFlags.
- -- Returns : a GModule on success, or NULL on failure.
- -- ---------------------------------------------------------------------------------
- -- enum GModuleFlags
- -- typedef enum
- -- {
- -- G_MODULE_BIND_LAZY = 1 << 0,
- -- G_MODULE_BIND_LOCAL = 1 << 1,
- -- G_MODULE_BIND_MASK = 0x03
- -- } GModuleFlags;
- -- Flags passed to g_module_open(). Note that these flags are not supported on all
- -- platforms.
- -- G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed. The
- -- default action is to bind all symbols when the module is
- -- loaded.
- -- G_MODULE_BIND_LOCAL specifies that symbols in the module should not be added to
- -- the global name space. The default action on most platforms
- -- is to place symbols in the module in the global name space,
- -- which may cause conflicts with existing symbols.
- -- G_MODULE_BIND_MASK mask for all flags.
- -- ---------------------------------------------------------------------------------
- -- g_module_symbol ()
- -- gboolean g_module_symbol (GModule *module,
- -- const gchar *symbol_name,
- -- gpointer *symbol);
- -- Gets a symbol pointer from a module.
- -- module : a GModule.
- -- symbol_name : the name of the symbol to find.
- -- symbol : returns the pointer to the symbol value.
- -- Returns : TRUE on success.
- -- ---------------------------------------------------------------------------------
- -- g_module_name ()
- -- const gchar* g_module_name (GModule *module);
- -- Gets the filename from a GModule.
- -- module : a GModule.
- -- Returns : the filename of the module, or "main" if the module is the main program
- -- itself.
- -- ---------------------------------------------------------------------------------
- -- g_module_make_resident ()
- -- void g_module_make_resident (GModule *module);
- -- Ensures that a module will never be unloaded. Any future g_module_close() calls
- -- on the module will be ignored.
- -- module : a GModule to make permanently resident.
- -- ---------------------------------------------------------------------------------
- -- g_module_close ()
- -- gboolean g_module_close (GModule *module);
- -- Closes a module.
- -- module : a GModule to close.
- -- Returns : TRUE on success.
- -- ---------------------------------------------------------------------------------
- -- g_module_error ()
- -- const gchar* g_module_error (void);
- -- Gets a string describing the last module error.
- -- Returns : a string describing the last module error.
- -- ---------------------------------------------------------------------------------
- -- GModuleCheckInit ()
- -- const gchar* (*GModuleCheckInit) (GModule *module);
- -- Specifies the type of the module initialization function. If a module contains a
- -- function named g_module_check_init() it is called automatically when the module
- -- is loaded. It is passed the GModule structure and should return NULL on success
- -- or a string describing the initialization error.
- -- module : the GModule corresponding to the module which has just been loaded.
- -- Returns : NULL on success, or a string describing the initialization error.
- -- ---------------------------------------------------------------------------------
- -- GModuleUnload ()
- -- void (*GModuleUnload) (GModule *module);
- -- Specifies the type of the module function called when it is unloaded. If a module
- -- contains a function named g_module_unload() it is called automatically when the
- -- module is unloaded. It is passed the GModule structure.
- -- module : the GModule about to be unloaded.
- -- ---------------------------------------------------------------------------------
- -- G_MODULE_SUFFIX
- -- #define G_MODULE_SUFFIX "so"
- -- Expands to the proper shared library suffix for the current platform without the
- -- leading dot. For the most Unices and Linux this is "so", for some HP-UX versions
- -- this is "sl" and for Windows this is "dll".
- -- ---------------------------------------------------------------------------------
- -- G_MODULE_EXPORT
- -- #define G_MODULE_EXPORT
- -- Used to declare functions exported by modules.
- -- ---------------------------------------------------------------------------------
- -- G_MODULE_IMPORT
- -- #define G_MODULE_IMPORT extern
- -- Used to declare functions imported from modules.
- end -- class GLIB_DYNAMIC_LOADING_OF_MODULES