src/include/eina_module.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2007-2008 Jorge Luis Zapata Muga
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_MODULE_H_
  20 #define EINA_MODULE_H_
  21
  22 #include "eina_types.h"
  23 #include "eina_array.h"
  24 #include "eina_error.h"
  25
  26 /**
  27  * @addtogroup Eina_Module_Group Module
  28  *
  29  * @brief These functions provide module management.
  30  */
  31
  32 /**
  33  * @addtogroup Eina_Tools_Group Tools
  34  *
  35  * @{
  36  */
  37
  38 /**
  39  * @defgroup Eina_Module_Group Module
  40  *
  41  * Eina module provides some helpers over POSIX dlopen(). It is not
  42  * meant to replace, abstract or make a "portable" version of the
  43  * POSIX, but enhance its usage by defining some good practices.
  44  *
  45  * Modules are created with eina_module_new() and later loaded with
  46  * eina_module_load(). Loads are reference counted and there must be
  47  * the same number of eina_module_unload() in order to have it to call
  48  * dlclose(). This makes simple to have different users for the same
  49  * module.
  50  *
  51  * The loaded shared objects may have two visible functions that will
  52  * be called and might provide initialization and shutdown
  53  * procedures. The symbols are @c __eina_module_init and
  54  * @c __eina_module_shutdown and will be defined by the macros
  55  * EINA_MODULE_INIT() and EINA_MODULE_SHUTDOWN().
  56  *
  57  * There are some helpers to automatically create modules based on
  58  * directory listing. See eina_module_arch_list_get(),
  59  * eina_module_list_get() and eina_module_find().
  60  *
  61  * @{
  62  */
  63
  64 /**
  65  * @typedef Eina_Module
  66  * Dynamic module loader handle.
  67  */
  68 typedef struct _Eina_Module Eina_Module;
  69
  70 /**
  71  * @typedef Eina_Module_Cb
  72  * Dynamic module loader callback.
  73  */
  74 typedef Eina_Bool         (*Eina_Module_Cb)(Eina_Module *m, void *data);
  75
  76 /**
  77  * @typedef Eina_Module_Init
  78  * If a function with such signature is exported by module as
  79  * __eina_module_init, it will be called on the first load after
  80  * dlopen() and if #EINA_FALSE is returned, load will fail, #EINA_TRUE
  81  * means the module was successfully initialized.
  82  * @see Eina_Module_Shutdown
  83  */
  84 typedef Eina_Bool (*Eina_Module_Init)(void);
  85
  86 /**
  87  * @typedef Eina_Module_Shutdown
  88  * If a function with such signature is exported by module as
  89  * __eina_module_shutdown, it will be called before calling dlclose()
  90  * @see Eina_Module_Init
  91  */
  92 typedef void (*Eina_Module_Shutdown)(void);
  93
  94 /**
  95  * @def EINA_MODULE_INIT
  96  * declares the given function as the module initializer (__eina_module_init).
  97  * It must be of signature #Eina_Module_Init
  98  */
  99 #define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f
 100
 101 /**
 102  * @def EINA_MODULE_SHUTDOWN
 103  * declares the given function as the module shutdownializer
 104  * (__eina_module_shutdown). It must be of signature #Eina_Module_Shutdown
 105  */
 106 #define EINA_MODULE_SHUTDOWN(f) EAPI Eina_Module_Shutdown __eina_module_shutdown = &f
 107
 108 /**
 109  * @var EINA_ERROR_WRONG_MODULE
 110  * Error identifier corresponding to a wrong module.
 111  */
 112 extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE;
 113
 114 /**
 115  * @var EINA_ERROR_MODULE_INIT_FAILED
 116  * Error identifier corresponding to a failure during the initialisation of a module.
 117  */
 118 extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED;
 119
 120 /**
 121  * @brief Return a new module.
 122  *
 123  * @param file The name of the file module to load.
 124  * @return A new module. If @p file is @c NULL, the function
 125  * returns @c NULL, otherwise, it allocates an Eina_Module, stores
 126  * a duplicate string of @p file, sets its reference to @c 0 and
 127  * its handle to @c NULL.
 128  *
 129  * When the new module is not needed anymore, use eina_module_free()
 130  * to free the allocated memory.
 131  *
 132  * @see eina_module_load
 133  */
 134 EAPI Eina_Module *
 135  eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 136
 137 /**
 138  * @brief Delete a module.
 139  *
 140  * @param module The module to delete.
 141  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 142  *
 143  * This function calls eina_module_unload() if @p module has been previously
 144  * loaded and frees the allocated memory. On success this function
 145  * returns #EINA_TRUE and #EINA_FALSE otherwise. If @p module is @c NULL, the
 146  * function returns immediately.
 147  */
 148 EAPI Eina_Bool
 149  eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1);
 150
 151 /**
 152  * @brief Load a module.
 153  *
 154  * @param module The module to load.
 155  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 156  *
 157  * This function load the shared file object passed in
 158  * eina_module_new(). If it is a internal Eina module (like the
 159  * mempools), it also initialize it. It the shared file object can not
 160  * be loaded, the error #EINA_ERROR_WRONG_MODULE is set and
 161  * and #EINA_FALSE is returned. If it is a internal Eina module and the
 162  * module can not be initialized, the error #EINA_ERROR_MODULE_INIT_FAILED
 163  * is set and #EINA_FALSE is returned. If the module has already been loaded,
 164  * it's reference counter is increased by one and #EINA_TRUE is returned.
 165  * If @p module is @c NULL, the function returns immediately #EINA_FALSE.
 166  *
 167  * When the symbols of the shared file objects are not needed
 168  * anymore, call eina_module_unload() to unload the module.
 169  */
 170 EAPI Eina_Bool
 171  eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
 172
 173 /**
 174  * @brief Unload a module.
 175  *
 176  * @param module The module to load.
 177  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 178  *
 179  * This function unload the module @p module that has been previously
 180  * loaded by eina_module_load(). If the reference counter of @p module is
 181  * strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the
 182  * shared object file is closed and if it is a internal Eina module, it
 183  * is shutted down just before. In that case, #EINA_TRUE is
 184  * returned. In all case, the reference counter is decreased. If @p module
 185  * is @c NULL, the function returns immediately #EINA_FALSE.
 186  */
 187 EAPI Eina_Bool
 188  eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1);
 189
 190 /**
 191  * @brief Retrieve the data associated to a symbol.
 192  *
 193  * @param module The module.
 194  * @param symbol The symbol.
 195  * @return The data associated to the symbol, or @c NULL on failure.
 196  *
 197  * This function returns the data associated to @p symbol of @p module. @p
 198  * module must have been loaded before with eina_module_load(). If @p module
 199  * is @c NULL, or if it has not been correctly loaded before, the
 200  * function returns immediately @c NULL.
 201  */
 202 EAPI void *
 203  eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
 204
 205 /**
 206  * @brief Return the file name associated to the module.
 207  *
 208  * @param module The module.
 209  * @return The file name.
 210  *
 211  * This function returns the file name passed in eina_module_new(). If
 212  * @p module is @c NULL, the function returns immediately @c NULL. The
 213  * returned value must no be freed.
 214  */
 215 EAPI const char *
 216  eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 217
 218
 219 /**
 220  * @brief Return the path built from the location of a library and a
 221  * given sub directory.
 222  *
 223  * @param symbol The symbol to search for.
 224  * @param sub_dir The subdirectory to append.
 225  * @return The built path on success, @c NULL otherwise.
 226  *
 227  * This function returns the path built by concatenating the path of
 228  * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir
 229  * can be @c NULL. The returned path must be freed when not used
 230  * anymore. If the symbol is not found, or dl_addr() is not supported,
 231  * or allocation fails, this function returns @c NULL.
 232  */
 233 EAPI char *
 234  eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
 235
 236 /**
 237  * @brief Return the path built from the value of an environment variable and a
 238  * given sub directory.
 239  *
 240  * @param env The environment variable to expand.
 241  * @param sub_dir The subdirectory to append.
 242  * @return The built path on success, @c NULL otherwise.
 243  *
 244  * This function returns the path built by concatenating the value of
 245  * the environment variable named @p env and @p sub_dir. @p sub_dir
 246  * can be @c NULL. The returned path must be freed when not used
 247  * anymore. If the symbol is not found, or @p env does not exist, or
 248  * allocation fails, this function returns @c NULL.
 249  */
 250 EAPI char *
 251  eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
 252
 253
 254 /**
 255  * @brief Get an array of modules found on the directory path matching an arch type.
 256  *
 257  * @param array The array that stores the list of the modules.
 258  * @param path The directory's path to search for modules.
 259  * @param arch The architecture string.
 260  * @return The array of modules found in @p path matching @p arch.
 261  *
 262  * This function adds to @p array the module names found in @p path
 263  * which match the cpu architecture @p arch. If @p path or @p arch is
 264  * @c NULL, the function returns immediately @p array. @p array can be
 265  * @c NULL. In that case, it is created with 4 elements.
 266  */
 267 EAPI Eina_Array *
 268  eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch);
 269
 270 /**
 271  * @brief Get a list of modules found on the directory path.
 272  *
 273  * @param array The array that stores the list of the modules.
 274  * @param path The directory's path to search for modules.
 275  * @param recursive Iterate recursively on the path.
 276  * @param cb Callback function to call on each module.
 277  * @param data Data passed to the callback function.
 278  * @return The array of modules found in @p path.
 279  *
 280  * This function adds to @p array the list of modules found in
 281  * @p path. If @p recursive is #EINA_TRUE, then recursive search is
 282  * done. The callback @p cb is called on each module found, and @p data
 283  * is passed to @p cb. If @p path is @c NULL, the function returns
 284  * immediately @p array. If the returned value of @p cb is @c 0, the
 285  * module will not be added to the list, otherwise it will be added.
 286  * @p array can be @c NULL. In that case, it is created with 4
 287  * elements. @p cb can be @c NULL.
 288  */
 289 EAPI Eina_Array *
 290  eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 291
 292 /**
 293  * @brief Load every module on the list of modules.
 294  *
 295  * @param array The array of modules to load.
 296  *
 297  * This function calls eina_module_load() on each element found in
 298  * @p array. If @p array is @c NULL, this function does nothing.
 299  */
 300 EAPI void
 301  eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1);
 302
 303 /**
 304  * @brief Unload every module on the list of modules.
 305  *
 306  * @param array The array of modules to unload.
 307  *
 308  * This function calls eina_module_unload() on each element found in
 309  * @p array. If @p array is @c NULL, this function does nothing.
 310  */
 311 EAPI void
 312  eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1);
 313
 314 /**
 315  * @p Free every module on the list of modules.
 316  *
 317  * @param array The array of modules to free.
 318  *
 319  * This function calls eina_module_free() on each element found in
 320  * @p array. If @p array is @c NULL, this function does nothing.
 321  */
 322 EAPI void
 323  eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1);
 324
 325 /**
 326  * @brief Find an module in array.
 327  *
 328  * @param array The array to find the module.
 329  * @param module The name of module to be searched.
 330  * @return The module to find on success, @c NULL otherwise.
 331  *
 332  * This function finds an @p module in @p array.
 333  * If the element is found  the function returns the module, else
 334  * @c NULL is returned.
 335  */
 336 EAPI Eina_Module *
 337  eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2);
 338
 339 /**
 340  * @}
 341  */
 342
 343 /**
 344  * @}
 345  */
 346
 347 #endif /*EINA_MODULE_H_*/