PageRenderTime 29ms CodeModel.GetById 20ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

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