Eina module provides some helpers over POSIX dlopen(). More...
Macros | |
#define | EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f |
declares the given function as the module initializer (__eina_module_init). More... | |
#define | EINA_MODULE_SHUTDOWN(f) EAPI Eina_Module_Shutdown __eina_module_shutdown = &f |
declares the given function as the module shutdownializer (__eina_module_shutdown). More... | |
Typedefs | |
typedef struct _Eina_Module | Eina_Module |
Dynamic module loader handle. | |
typedef Eina_Bool(* | Eina_Module_Cb) (Eina_Module *m, void *data) |
Dynamic module loader callback. | |
typedef Eina_Bool(* | Eina_Module_Init) (void) |
If a function with such signature is exported by module as __eina_module_init, it will be called on the first load after dlopen() and if EINA_FALSE is returned, load will fail, EINA_TRUE means the module was successfully initialized. More... | |
typedef void(* | Eina_Module_Shutdown) (void) |
If a function with such signature is exported by module as __eina_module_shutdown, it will be called before calling dlclose() More... | |
Functions | |
Eina_Module * | eina_module_new (const char *file) |
Return a new module. More... | |
Eina_Bool | eina_module_free (Eina_Module *module) |
Delete a module. More... | |
Eina_Bool | eina_module_load (Eina_Module *module) |
Load a module. More... | |
Eina_Bool | eina_module_unload (Eina_Module *module) |
Unload a module. More... | |
void * | eina_module_symbol_get (const Eina_Module *module, const char *symbol) |
Retrieve the data associated to a symbol. More... | |
const char * | eina_module_file_get (const Eina_Module *module) |
Return the file name associated to the module. More... | |
char * | eina_module_symbol_path_get (const void *symbol, const char *sub_dir) |
Return the path built from the location of a library and a given sub directory. More... | |
char * | eina_module_environment_path_get (const char *env, const char *sub_dir) |
Return the path built from the value of an environment variable and a given sub directory. More... | |
Eina_Array * | eina_module_arch_list_get (Eina_Array *array, const char *path, const char *arch) |
Get an array of modules found on the directory path matching an arch type. More... | |
Eina_Array * | eina_module_list_get (Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) |
Get a list of modules found on the directory path. More... | |
void | eina_module_list_load (Eina_Array *array) |
Load every module on the list of modules. More... | |
void | eina_module_list_unload (Eina_Array *array) |
Unload every module on the list of modules. More... | |
void | eina_module_list_free (Eina_Array *array) |
Free every module on the list of modules. More... | |
Eina_Module * | eina_module_find (const Eina_Array *array, const char *module) |
Find an module in array. More... | |
Variables | |
Eina_Error | EINA_ERROR_WRONG_MODULE |
Eina_Error | EINA_ERROR_MODULE_INIT_FAILED |
Eina module provides some helpers over POSIX dlopen().
These functions provide module management.
It is not meant to replace, abstract or make a "portable" version of the POSIX, but enhance its usage by defining some good practices.
Modules are created with eina_module_new() and later loaded with eina_module_load(). Loads are reference counted and there must be the same number of eina_module_unload() in order to have it to call dlclose(). This makes simple to have different users for the same module.
The loaded shared objects may have two visible functions that will be called and might provide initialization and shutdown procedures. The symbols are __eina_module_init
and __eina_module_shutdown
and will be defined by the macros EINA_MODULE_INIT() and EINA_MODULE_SHUTDOWN().
There are some helpers to automatically create modules based on directory listing. See eina_module_arch_list_get(), eina_module_list_get() and eina_module_find().
#define EINA_MODULE_INIT | ( | f | ) | EAPI Eina_Module_Init __eina_module_init = &f |
declares the given function as the module initializer (__eina_module_init).
It must be of signature Eina_Module_Init
#define EINA_MODULE_SHUTDOWN | ( | f | ) | EAPI Eina_Module_Shutdown __eina_module_shutdown = &f |
declares the given function as the module shutdownializer (__eina_module_shutdown).
It must be of signature Eina_Module_Shutdown
Eina_Module_Init |
If a function with such signature is exported by module as __eina_module_init, it will be called on the first load after dlopen() and if EINA_FALSE is returned, load will fail, EINA_TRUE means the module was successfully initialized.
Eina_Module_Shutdown |
If a function with such signature is exported by module as __eina_module_shutdown, it will be called before calling dlclose()
Eina_Module* eina_module_new | ( | const char * | file | ) |
Return a new module.
file | The name of the file module to load. |
file
is NULL
, the function returns NULL
, otherwise, it allocates an Eina_Module, stores a duplicate string of file
, sets its reference to 0
and its handle to NULL
.When the new module is not needed anymore, use eina_module_free() to free the allocated memory.
Eina_Bool eina_module_free | ( | Eina_Module * | module | ) |
Delete a module.
module | The module to delete. |
This function calls eina_module_unload() if module
has been previously loaded and frees the allocated memory. On success this function returns EINA_TRUE and EINA_FALSE otherwise. If module
is NULL
, the function returns immediately.
References EINA_FALSE, eina_module_unload(), and EINA_TRUE.
Referenced by eina_module_list_free().
Eina_Bool eina_module_load | ( | Eina_Module * | module | ) |
Load a module.
module | The module to load. |
This function load the shared file object passed in eina_module_new(). If it is a internal Eina module (like the mempools), it also initialize it. If the shared file object can not be loaded, EINA_FALSE is returned. If it is an internal Eina module and the module can not be initialized, EINA_FALSE is returned. If the module has already been loaded, it's reference counter is increased by one and EINA_TRUE is returned. If module
is NULL
, the function returns immediately EINA_FALSE.
When the symbols of the shared file objects are not needed anymore, call eina_module_unload() to unload the module.
References dlclose(), dlerror(), dlopen(), dlsym(), EINA_FALSE, EINA_TRUE, RTLD_LAZY, and RTLD_NOW.
Referenced by eina_module_list_load().
Eina_Bool eina_module_unload | ( | Eina_Module * | module | ) |
Unload a module.
module | The module to load. |
This function unload the module module
that has been previously loaded by eina_module_load(). If the reference counter of module
is strictly greater than 1
, EINA_FALSE is returned. Otherwise, the shared object file is closed and if it is a internal Eina module, it is shutted down just before. In that case, EINA_TRUE is returned. In all case, the reference counter is decreased. If module
is NULL
, the function returns immediately EINA_FALSE.
References dlclose(), dlsym(), EINA_FALSE, and EINA_TRUE.
Referenced by eina_module_free(), and eina_module_list_unload().
void* eina_module_symbol_get | ( | const Eina_Module * | module, |
const char * | symbol | ||
) |
Retrieve the data associated to a symbol.
module | The module. |
symbol | The symbol. |
NULL
on failure.This function returns the data associated to symbol
of module
. module
must have been loaded before with eina_module_load(). If module
is NULL
, or if it has not been correctly loaded before, the function returns immediately NULL
.
References dlsym().
Referenced by ecore_evas_extn_plug_new(), ecore_evas_extn_socket_new(), ecore_evas_fb_new(), ecore_evas_gl_x11_new(), ecore_evas_gl_x11_pixmap_new(), ecore_evas_software_x11_new(), and ecore_evas_software_x11_pixmap_new().
const char* eina_module_file_get | ( | const Eina_Module * | module | ) |
Return the file name associated to the module.
module | The module. |
This function returns the file name passed in eina_module_new(). If module
is NULL
, the function returns immediately NULL
. The returned value must no be freed.
Referenced by eina_module_find().
char* eina_module_symbol_path_get | ( | const void * | symbol, |
const char * | sub_dir | ||
) |
Return the path built from the location of a library and a given sub directory.
symbol | The symbol to search for. |
sub_dir | The subdirectory to append. |
NULL
otherwise.This function returns the path built by concatenating the path of the library containing the symbol symbol
and sub_dir
. sub_dir
can be NULL
. The returned path must be freed when not used anymore. If the symbol is not found, or dl_addr() is not supported, or allocation fails, this function returns NULL
.
References dladdr(), and Dl_info::dli_fname.
char* eina_module_environment_path_get | ( | const char * | env, |
const char * | sub_dir | ||
) |
Return the path built from the value of an environment variable and a given sub directory.
env | The environment variable to expand. |
sub_dir | The subdirectory to append. |
NULL
otherwise.This function returns the path built by concatenating the value of the environment variable named env
and sub_dir
. sub_dir
can be NULL
. The returned path must be freed when not used anymore. If the symbol is not found, or env
does not exist, or allocation fails, this function returns NULL
.
Eina_Array* eina_module_arch_list_get | ( | Eina_Array * | array, |
const char * | path, | ||
const char * | arch | ||
) |
Get an array of modules found on the directory path matching an arch type.
array | The array that stores the list of the modules. |
path | The directory's path to search for modules. |
arch | The architecture string. |
path
matching arch
.This function adds to array
the module names found in path
which match the cpu architecture arch
. If path
or arch
is NULL
, the function returns immediately array
. array
can be NULL
. In that case, it is created with 4 elements.
References eina_array_new(), and eina_file_dir_list().
Eina_Array* eina_module_list_get | ( | Eina_Array * | array, |
const char * | path, | ||
Eina_Bool | recursive, | ||
Eina_Module_Cb | cb, | ||
void * | data | ||
) |
Get a list of modules found on the directory path.
array | The array that stores the list of the modules. |
path | The directory's path to search for modules. |
recursive | Iterate recursively on the path. |
cb | Callback function to call on each module. |
data | Data passed to the callback function. |
path
.This function adds to array
the list of modules found in path
. If recursive
is EINA_TRUE, then recursive search is done. The callback cb
is called on each module found, and data
is passed to cb
. If path
is NULL
, the function returns immediately array
. If the returned value of cb
is 0
, the module will not be added to the list, otherwise it will be added. array
can be NULL
. In that case, it is created with 4 elements. cb
can be NULL
.
References eina_array_new(), and eina_file_dir_list().
void eina_module_list_load | ( | Eina_Array * | array | ) |
Load every module on the list of modules.
array | The array of modules to load. |
This function calls eina_module_load() on each element found in array
. If array
is NULL
, this function does nothing.
References EINA_ARRAY_ITER_NEXT, and eina_module_load().
void eina_module_list_unload | ( | Eina_Array * | array | ) |
Unload every module on the list of modules.
array | The array of modules to unload. |
This function calls eina_module_unload() on each element found in array
. If array
is NULL
, this function does nothing.
References EINA_ARRAY_ITER_NEXT, and eina_module_unload().
void eina_module_list_free | ( | Eina_Array * | array | ) |
Free
every module on the list of modules.
array | The array of modules to free. |
This function calls eina_module_free() on each element found in array
. If array
is NULL
, this function does nothing.
References eina_array_flush(), EINA_ARRAY_ITER_NEXT, and eina_module_free().
Eina_Module* eina_module_find | ( | const Eina_Array * | array, |
const char * | module | ||
) |
Find an module in array.
array | The array to find the module. |
module | The name of module to be searched. |
NULL
otherwise.This function finds an module
in array
. If the element is found the function returns the module, else NULL
is returned.
References EINA_ARRAY_ITER_NEXT, and eina_module_file_get().