/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

  1. deferred class GLIB_DYNAMIC_LOADING_OF_MODULES
  2. -- Dynamic Loading of Modules
  3. -- Dynamic Loading of Modules -- portable method for dynamically loading
  4. -- 'plug-ins'.
  5. -- Synopsis
  6. -- #include <gmodule.h>
  7. -- GModule;
  8. -- gboolean g_module_supported (void);
  9. -- gchar* g_module_build_path (const gchar *directory,
  10. -- const gchar *module_name);
  11. -- GModule* g_module_open (const gchar *file_name,
  12. -- GModuleFlags flags);
  13. -- enum GModuleFlags;
  14. -- gboolean g_module_symbol (GModule *module,
  15. -- const gchar *symbol_name,
  16. -- gpointer *symbol);
  17. -- const gchar* g_module_name (GModule *module);
  18. -- void g_module_make_resident (GModule *module);
  19. -- gboolean g_module_close (GModule *module);
  20. -- const gchar* g_module_error (void);
  21. -- const gchar* (*GModuleCheckInit) (GModule *module);
  22. -- void (*GModuleUnload) (GModule *module);
  23. -- #define G_MODULE_SUFFIX
  24. -- #define G_MODULE_EXPORT
  25. -- #define G_MODULE_IMPORT
  26. -- Description
  27. -- These functions provide a portable way to dynamically load object files (commonly
  28. -- known as 'plug-ins'). The current implementation supports all systems that
  29. -- provide an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its
  30. -- shl_load() mechanism, and Windows platforms via DLLs.
  31. -- A program which wants to use these functions must be linked to the libraries
  32. -- output by the command pkg-config --libs gmodule-2.0.
  33. -- To use them you must first determine whether dynamic loading is supported on the
  34. -- platform by calling g_module_supported(). If it is, you can open a module with
  35. -- g_module_open(), find the module's symbols (e.g. function names) with
  36. -- g_module_symbol(), and later close the module with g_module_close().
  37. -- g_module_name() will return the file name of a currently opened module.
  38. -- If any of the above functions fail, the error status can be found with
  39. -- g_module_error().
  40. -- The GModule implementation features reference counting for opened modules, and
  41. -- supports hook functions within a module which are called when the module is
  42. -- loaded and unloaded (see GModuleCheckInit and GModuleUnload).
  43. -- If your module introduces static data to common subsystems in the running
  44. -- program, e.g. through calling g_quark_from_static_string ("my-module-stuff"), it
  45. -- must ensure that it is never unloaded, by calling g_module_make_resident().
  46. -- Example 12. Calling a function defined in a GModule
  47. -- /* the function signature for 'say_hello' */
  48. -- typedef void (* SayHelloFunc) (const char *message);
  49. -- gboolean
  50. -- just_say_hello (const char *filename, GError **error)
  51. -- {
  52. -- SayHelloFunc say_hello;
  53. -- GModule *module;
  54. -- module = g_module_open (filename, G_MODULE_BIND_LAZY);
  55. -- if (!module)
  56. -- {
  57. -- g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
  58. -- "%s", g_module_error ());
  59. -- return FALSE;
  60. -- }
  61. -- if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
  62. -- {
  63. -- g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
  64. -- "%s: %s", filename, g_module_error ());
  65. -- if (!g_module_close (module))
  66. -- g_warning ("%s: %s", filename, g_module_error ());
  67. -- return FALSE;
  68. -- }
  69. -- /* call our function in the module */
  70. -- say_hello ("Hello world!");
  71. -- if (!g_module_close (module))
  72. -- g_warning ("%s: %s", filename, g_module_error ());
  73. -- return TRUE;
  74. -- }
  75. -- Details
  76. -- GModule
  77. -- typedef struct _GModule GModule;
  78. -- The GModule struct is an opaque data structure to represent a Dynamically-Loaded
  79. -- Module. It should only be accessed via the following functions.
  80. -- ---------------------------------------------------------------------------------
  81. -- g_module_supported ()
  82. -- gboolean g_module_supported (void);
  83. -- Checks if modules are supported on the current platform.
  84. -- Returns : TRUE if modules are supported.
  85. -- ---------------------------------------------------------------------------------
  86. -- g_module_build_path ()
  87. -- gchar* g_module_build_path (const gchar *directory,
  88. -- const gchar *module_name);
  89. -- A portable way to build the filename of a module. The platform-specific prefix
  90. -- and suffix are added to the filename, if needed, and the result is added to the
  91. -- directory, using the correct separator character.
  92. -- The directory should specify the directory where the module can be found. It can
  93. -- be NULL or an empty string to indicate that the module is in a standard
  94. -- platform-specific directory, though this is not recommended since the wrong
  95. -- module may be found.
  96. -- For example, calling g_module_build_path() on a Linux system with a directory of
  97. -- /lib and a module_name of "mylibrary" will return /lib/libmylibrary.so. On a
  98. -- Windows system, using \Windows as the directory it will return
  99. -- \Windows\mylibrary.dll.
  100. -- directory : the directory where the module is. This can be NULL or the empty
  101. -- string to indicate that the standard platform-specific directories
  102. -- will be used, though that is not recommended.
  103. -- module_name : the name of the module.
  104. -- Returns : the complete path of the module, including the standard library
  105. -- prefix and suffix. This should be freed when no longer needed.
  106. -- ---------------------------------------------------------------------------------
  107. -- g_module_open ()
  108. -- GModule* g_module_open (const gchar *file_name,
  109. -- GModuleFlags flags);
  110. -- Opens a module. If the module has already been opened, its reference count is
  111. -- incremented.
  112. -- First of all g_module_open() tries to open file_name as a module. If that fails
  113. -- and file_name has the ".la"-suffix (and is a libtool archive) it tries to open
  114. -- the corresponding module. If that fails and it doesn't have the proper module
  115. -- suffix for the platform (G_MODULE_SUFFIX), this suffix will be appended and the
  116. -- corresponding module will be opended. If that fails and file_name doesn't have
  117. -- the ".la"-suffix, this suffix is appended and g_module_open() tries to open the
  118. -- corresponding module. If eventually that fails as well, NULL is returned.
  119. -- file_name : the name of the file containing the module, or NULL to obtain a
  120. -- GModule representing the main program itself.
  121. -- flags : the flags used for opening the module. This can be the logical OR of
  122. -- any of the GModuleFlags.
  123. -- Returns : a GModule on success, or NULL on failure.
  124. -- ---------------------------------------------------------------------------------
  125. -- enum GModuleFlags
  126. -- typedef enum
  127. -- {
  128. -- G_MODULE_BIND_LAZY = 1 << 0,
  129. -- G_MODULE_BIND_LOCAL = 1 << 1,
  130. -- G_MODULE_BIND_MASK = 0x03
  131. -- } GModuleFlags;
  132. -- Flags passed to g_module_open(). Note that these flags are not supported on all
  133. -- platforms.
  134. -- G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed. The
  135. -- default action is to bind all symbols when the module is
  136. -- loaded.
  137. -- G_MODULE_BIND_LOCAL specifies that symbols in the module should not be added to
  138. -- the global name space. The default action on most platforms
  139. -- is to place symbols in the module in the global name space,
  140. -- which may cause conflicts with existing symbols.
  141. -- G_MODULE_BIND_MASK mask for all flags.
  142. -- ---------------------------------------------------------------------------------
  143. -- g_module_symbol ()
  144. -- gboolean g_module_symbol (GModule *module,
  145. -- const gchar *symbol_name,
  146. -- gpointer *symbol);
  147. -- Gets a symbol pointer from a module.
  148. -- module : a GModule.
  149. -- symbol_name : the name of the symbol to find.
  150. -- symbol : returns the pointer to the symbol value.
  151. -- Returns : TRUE on success.
  152. -- ---------------------------------------------------------------------------------
  153. -- g_module_name ()
  154. -- const gchar* g_module_name (GModule *module);
  155. -- Gets the filename from a GModule.
  156. -- module : a GModule.
  157. -- Returns : the filename of the module, or "main" if the module is the main program
  158. -- itself.
  159. -- ---------------------------------------------------------------------------------
  160. -- g_module_make_resident ()
  161. -- void g_module_make_resident (GModule *module);
  162. -- Ensures that a module will never be unloaded. Any future g_module_close() calls
  163. -- on the module will be ignored.
  164. -- module : a GModule to make permanently resident.
  165. -- ---------------------------------------------------------------------------------
  166. -- g_module_close ()
  167. -- gboolean g_module_close (GModule *module);
  168. -- Closes a module.
  169. -- module : a GModule to close.
  170. -- Returns : TRUE on success.
  171. -- ---------------------------------------------------------------------------------
  172. -- g_module_error ()
  173. -- const gchar* g_module_error (void);
  174. -- Gets a string describing the last module error.
  175. -- Returns : a string describing the last module error.
  176. -- ---------------------------------------------------------------------------------
  177. -- GModuleCheckInit ()
  178. -- const gchar* (*GModuleCheckInit) (GModule *module);
  179. -- Specifies the type of the module initialization function. If a module contains a
  180. -- function named g_module_check_init() it is called automatically when the module
  181. -- is loaded. It is passed the GModule structure and should return NULL on success
  182. -- or a string describing the initialization error.
  183. -- module : the GModule corresponding to the module which has just been loaded.
  184. -- Returns : NULL on success, or a string describing the initialization error.
  185. -- ---------------------------------------------------------------------------------
  186. -- GModuleUnload ()
  187. -- void (*GModuleUnload) (GModule *module);
  188. -- Specifies the type of the module function called when it is unloaded. If a module
  189. -- contains a function named g_module_unload() it is called automatically when the
  190. -- module is unloaded. It is passed the GModule structure.
  191. -- module : the GModule about to be unloaded.
  192. -- ---------------------------------------------------------------------------------
  193. -- G_MODULE_SUFFIX
  194. -- #define G_MODULE_SUFFIX "so"
  195. -- Expands to the proper shared library suffix for the current platform without the
  196. -- leading dot. For the most Unices and Linux this is "so", for some HP-UX versions
  197. -- this is "sl" and for Windows this is "dll".
  198. -- ---------------------------------------------------------------------------------
  199. -- G_MODULE_EXPORT
  200. -- #define G_MODULE_EXPORT
  201. -- Used to declare functions exported by modules.
  202. -- ---------------------------------------------------------------------------------
  203. -- G_MODULE_IMPORT
  204. -- #define G_MODULE_IMPORT extern
  205. -- Used to declare functions imported from modules.
  206. end -- class GLIB_DYNAMIC_LOADING_OF_MODULES