ltt/branches/poly/lttv/lttv/module.h

   1 /* This file is part of the Linux Trace Toolkit viewer
   2  * Copyright (C) 2003-2004 Michel Dagenais
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License Version 2 as
   6  * published by the Free Software Foundation;
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  16  * MA 02111-1307, USA.
  17  */
  18
  19 #ifndef MODULES_H
  20 #define MODULES_H
  21
  22 #include <glib.h>
  23
  24 /* A module contains some functionality which becomes available atfer it is
  25    initialized and before it is destroyed. A module is characterized by a name,
  26    a description (short and long), a list of names of other modules on which
  27    it depends, and an initialization and a destruction function.
  28
  29    A library contains one or more modules and may be loaded dynamically.
  30    The modules contained in a library are automatically registered through
  31    constructors which are called when the library is loaded. For modules
  32    directly linked with the main program (builtin), the constructors are
  33    called before the main program starts. (However, neither malloc nor glib
  34    functions are used during the registration process).
  35
  36    The library loading path is a set of directories, where requested
  37    libraries and modules are searched for.
  38 */
  39
  40 typedef struct _LttvModule LttvModule;
  41
  42 typedef struct _LttvLibrary LttvLibrary;
  43
  44 typedef void (*LttvModuleInit)();
  45
  46 typedef void (*LttvModuleDestroy)();
  47
  48 typedef struct _LttvModuleInfo
  49 {
  50   char *name;
  51   char *short_description;
  52   char *description;
  53   LttvModuleInit init;
  54   LttvModuleDestroy destroy;
  55   LttvLibrary *library;
  56   unsigned require_count;
  57   unsigned use_count;
  58   unsigned prerequisites_number;
  59 } LttvModuleInfo;
  60
  61
  62 typedef struct _LttvLibraryInfo
  63 {
  64   char *name;
  65   char *path;
  66   unsigned load_count;
  67 } LttvLibraryInfo;
  68
  69
  70 typedef enum _LttvModuleError
  71 {
  72   LTTV_MODULE_NOT_FOUND,
  73   LTTV_MODULE_NO_INIT
  74 } LttvModuleError;
  75
  76
  77 /* Insure that a module is loaded and initialized. Require count
  78    (number of times the module was required) and use count
  79    (number of times required or used as prerequisite) serve to
  80    insure that a module is destroyed only after it has been released
  81    as many times as it was required (and prerequired).
  82
  83    The module is searched among the modules currently loaded, then as a
  84    similarly named library to load which should contain the named module.
  85    If the module cannot be found or loaded, NULL is returned and an
  86    explanation is provided in error. */
  87
  88 LttvModule *lttv_module_require(char *name, GError **error);
  89
  90 void lttv_module_release(LttvModule *m);
  91
  92
  93 /* Obtain information about the module, including the containing library */
  94
  95 void lttv_module_info(LttvModule *m, LttvModuleInfo *info);
  96
  97
  98 /* List the modules on which this module depends */
  99
 100 unsigned lttv_module_prerequisite_number(LttvModule *m);
 101
 102 LttvModule *lttv_module_prerequisite_get(LttvModule *m, unsigned i);
 103
 104
 105 /* Insure that a library is loaded. A load count insures that a library
 106    is unloaded only after it has been asked to unload as
 107    many times as it was loaded, and its modules are not in use. The library
 108    is searched along the library path if name is a relative pathname.
 109    If the library cannot be found or loaded, NULL is returned and an
 110    explanation is provided in error. */
 111
 112 LttvLibrary *lttv_library_load(char *name, GError **error);
 113
 114 /* Returns 0 if library is unloaded, > 0 otherwise */
 115 gint lttv_library_unload(LttvLibrary *l);
 116
 117
 118 /* Obtain information about the library */
 119
 120 void lttv_library_info(LttvLibrary *l, LttvLibraryInfo *info);
 121
 122
 123 /* List the modules contained in a library */
 124
 125 unsigned lttv_library_module_number(LttvLibrary *l);
 126
 127 LttvModule *lttv_library_module_get(LttvLibrary *l, unsigned i);
 128
 129
 130 /* List the currently loaded libraries */
 131
 132 unsigned lttv_library_number();
 133
 134 LttvLibrary *lttv_library_get(unsigned i);
 135
 136
 137
 138 /* Add or remove directory names to the library search path */
 139
 140 void lttv_library_path_add(const char *name);
 141
 142 void lttv_library_path_remove(const char *name);
 143
 144
 145 /* List the directory names in the library search path */
 146
 147 unsigned lttv_library_path_number();
 148
 149 char *lttv_library_path_get(unsigned i);
 150
 151
 152 /* To define a module, simply call the LTTV_MODULE macro with the needed
 153    arguments: single word name, one line short description, larger
 154    description, initialization function, destruction function, and
 155    list of names for required modules (e.g., "moduleA", "moduleB").
 156    This will insure that the module is registered at library load time.
 157
 158    Example:
 159
 160    LTTV_MODULE("option", "Command line options processing", "...", \
 161        init, destroy, "moduleA", "moduleB")
 162 */
 163
 164 #define LTTV_MODULE(name, short_desc, desc, init, destroy, ...) \
 165   \
 166   static void _LTTV_MODULE_REGISTER(__LINE__)() \
 167       __attribute__((constructor));              \
 168   \
 169   static void _LTTV_MODULE_REGISTER(__LINE__)() \
 170   { \
 171     static char *module_prerequisites[] = { __VA_ARGS__ };      \
 172     \
 173     static struct _LttvModuleDescription module = { \
 174         name, short_desc, desc, init, destroy, \
 175         sizeof(module_prerequisites) / sizeof(char *), \
 176         module_prerequisites, NULL}; \
 177         \
 178     lttv_module_register(&module); \
 179   }
 180
 181
 182 /* Internal structure and function used to register modules, called by
 183    LTTV_MODULE */
 184
 185 #define __LTTV_MODULE_REGISTER(line) _lttv_module_register_ ## line
 186 #define _LTTV_MODULE_REGISTER(line) __LTTV_MODULE_REGISTER(line)
 187
 188 struct _LttvModuleDescription
 189 {
 190   char *name;
 191   char *short_description;
 192   char *description;
 193   LttvModuleInit init;
 194   LttvModuleDestroy destroy;
 195   unsigned prerequisites_number;
 196   char **prerequisites;
 197   struct _LttvModuleDescription *next;
 198 };
 199
 200 void lttv_module_register(struct _LttvModuleDescription *d);
 201
 202 #endif // MODULES_H
 203
 204
 205
 206
 207
 208