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 void lttv_library_unload(LttvLibrary *l);
 115
 116
 117 /* Obtain information about the library */
 118
 119 void lttv_library_info(LttvLibrary *l, LttvLibraryInfo *info);
 120
 121
 122 /* List the modules contained in a library */
 123
 124 unsigned lttv_library_module_number(LttvLibrary *l);
 125
 126 LttvModule *lttv_library_module_get(LttvLibrary *l, unsigned i);
 127
 128
 129 /* List the currently loaded libraries */
 130
 131 unsigned lttv_library_number();
 132
 133 LttvLibrary *lttv_library_get(unsigned i);
 134
 135
 136
 137 /* Add or remove directory names to the library search path */
 138
 139 void lttv_library_path_add(const char *name);
 140
 141 void lttv_library_path_remove(const char *name);
 142
 143
 144 /* List the directory names in the library search path */
 145
 146 unsigned lttv_library_path_number();
 147
 148 char *lttv_library_path_get(unsigned i);
 149
 150
 151 /* To define a module, simply call the LTTV_MODULE macro with the needed
 152    arguments: single word name, one line short description, larger
 153    description, initialization function, destruction function, and
 154    list of names for required modules (e.g., "moduleA", "moduleB").
 155    This will insure that the module is registered at library load time.
 156
 157    Example:
 158
 159    LTTV_MODULE("option", "Command line options processing", "...", \
 160        init, destroy, "moduleA", "moduleB")
 161 */
 162
 163 #define LTTV_MODULE(name, short_desc, desc, init, destroy, ...) \
 164   \
 165   static void _LTTV_MODULE_REGISTER(__LINE__)() \
 166       __attribute__((constructor));              \
 167   \
 168   static void _LTTV_MODULE_REGISTER(__LINE__)() \
 169   { \
 170     static char *module_prerequisites[] = { __VA_ARGS__ };      \
 171     \
 172     static struct _LttvModuleDescription module = { \
 173         name, short_desc, desc, init, destroy, \
 174         sizeof(module_prerequisites) / sizeof(char *), \
 175         module_prerequisites, NULL}; \
 176         \
 177     lttv_module_register(&module); \
 178   }
 179
 180
 181 /* Internal structure and function used to register modules, called by
 182    LTTV_MODULE */
 183
 184 #define __LTTV_MODULE_REGISTER(line) _lttv_module_register_ ## line
 185 #define _LTTV_MODULE_REGISTER(line) __LTTV_MODULE_REGISTER(line)
 186
 187 struct _LttvModuleDescription
 188 {
 189   char *name;
 190   char *short_description;
 191   char *description;
 192   LttvModuleInit init;
 193   LttvModuleDestroy destroy;
 194   unsigned prerequisites_number;
 195   char **prerequisites;
 196   struct _LttvModuleDescription *next;
 197 };
 198
 199 void lttv_module_register(struct _LttvModuleDescription *d);
 200
 201 #endif // MODULES_H
 202
 203
 204
 205
 206
 207