Tizen Native API  5.5

These functions provide module management.

Eina module provides some helpers over POSIX dlopen(). It is not meant to replace, abstract or make a "portable" version of 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().

Functions

Eina_Moduleeina_module_new (const char *file)
 Returns a new module.
Eina_Bool eina_module_free (Eina_Module *module)
 Deletes a module.
Eina_Bool eina_module_load (Eina_Module *module)
 Loads a module.
Eina_Bool eina_module_unload (Eina_Module *module)
 Unloads a module.
void * eina_module_symbol_get (const Eina_Module *module, const char *symbol)
 Retrieves the data associated with a symbol.
const char * eina_module_file_get (const Eina_Module *module)
 Returns the file name associated with the module.
void eina_module_symbol_global_set (Eina_Module *module, Eina_Bool global)
 Defines if on module load we should expose all symbol.
char * eina_module_symbol_path_get (const void *symbol, const char *sub_dir)
 Returns the path built from the location of a library and a given sub directory.
char * eina_module_environment_path_get (const char *env, const char *sub_dir)
 Returns the path built from the value of an environment variable and a given sub directory.
Eina_Arrayeina_module_arch_list_get (Eina_Array *array, const char *path, const char *arch)
 Gets an array of modules found on the directory path matching an arch type.
Eina_Arrayeina_module_list_get (Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data)
 Gets a list of modules found on the directory path.
void eina_module_list_load (Eina_Array *array)
 Loads every module on the list of modules.
void eina_module_list_unload (Eina_Array *array)
 Unloads every module on the list of modules.
void eina_module_list_free (Eina_Array *array)
Eina_Moduleeina_module_find (const Eina_Array *array, const char *module)
 Finds a module in array.

Typedefs

typedef struct _Eina_Module Eina_Module
typedef Eina_Bool(* Eina_Module_Cb )(Eina_Module *m, void *data)
typedef Eina_Bool(* Eina_Module_Init )(void)
typedef void(* Eina_Module_Shutdown )(void)

Defines

#define EINA_MODULE_INIT(f)   EXPORTAPI Eina_Module_Init __eina_module_init = &f
#define EINA_MODULE_SHUTDOWN(f)   EXPORTAPI Eina_Module_Shutdown __eina_module_shutdown = &f

Define Documentation

#define EINA_MODULE_INIT (   f)    EXPORTAPI 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)    EXPORTAPI Eina_Module_Shutdown __eina_module_shutdown = &f

declares the given function as to be called on shutdown (__eina_module_shutdown). It must be of signature Eina_Module_Shutdown


Typedef Documentation

Dynamic module loader handle.

Dynamic module loader callback.

If a function with this 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.

See also:
Eina_Module_Shutdown

If a function with this signature is exported by module as __eina_module_shutdown, it will be called before calling dlclose()

See also:
Eina_Module_Init

Function Documentation

Eina_Array* eina_module_arch_list_get ( Eina_Array array,
const char *  path,
const char *  arch 
)

Gets an array of modules found on the directory path matching an arch type.

Parameters:
[in,out]arrayThe array that stores the list of the modules.
[in]pathThe directory's path to search for modules.
[in]archThe architecture string.
Returns:
The array of modules found in 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.

Since :
2.3
char* eina_module_environment_path_get ( const char *  env,
const char *  sub_dir 
)

Returns the path built from the value of an environment variable and a given sub directory.

Parameters:
[in]envThe environment variable to expand.
[in]sub_dirThe subdirectory to append.
Returns:
The built path on success, 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.

Since :
2.3
const char* eina_module_file_get ( const Eina_Module module)

Returns the file name associated with the module.

Parameters:
[in]moduleThe module.
Returns:
The file name.

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.

Since :
2.3
Eina_Module* eina_module_find ( const Eina_Array array,
const char *  module 
)

Finds a module in array.

Parameters:
[in]arrayThe array to find the module.
[in]moduleThe name of module to be searched.
Returns:
The module to find on success, NULL otherwise.

This function finds a module in array. If the element is found the function returns the module, else NULL is returned.

Since :
2.3

Deletes a module.

Parameters:
[in,out]moduleThe module to delete.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

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.

Since :
2.3
void eina_module_list_free ( Eina_Array array)

Frees every module on the list of modules.

Parameters:
[in,out]arrayThe 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.

Since :
2.3
Eina_Array* eina_module_list_get ( Eina_Array array,
const char *  path,
Eina_Bool  recursive,
Eina_Module_Cb  cb,
void *  data 
)

Gets a list of modules found on the directory path.

Parameters:
[in,out]arrayThe array that stores the list of the modules.
[in]pathThe directory's path to search for modules.
[in]recursiveIterate recursively on the path.
[in]cbCallback function to call on each module.
[in]dataData passed to the callback function.
Returns:
The array of modules found in 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.

Since :
2.3
void eina_module_list_load ( Eina_Array array)

Loads every module on the list of modules.

Parameters:
[in,out]arrayThe 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.

Since :
2.3

Unloads every module on the list of modules.

Parameters:
[in,out]arrayThe 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.

Since :
2.3

Loads a module.

Parameters:
[in,out]moduleThe module to load.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

This function load the shared file object passed in eina_module_new(). If it is a internal Eina module (like the mempools), it also initializes it. If the shared file object cannot be loaded, EINA_FALSE is returned. If it is an internal Eina module and the module cannot be initialized, EINA_FALSE is returned. If the module has already been loaded, its 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.

Since :
2.3
Eina_Module* eina_module_new ( const char *  file)

Returns a new module.

Parameters:
[in]fileThe name of the file module to load.
Returns:
A new module. If file is NULL, or if it does not exist, 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.

See also:
eina_module_load
Since :
2.3
void* eina_module_symbol_get ( const Eina_Module module,
const char *  symbol 
)

Retrieves the data associated with a symbol.

Parameters:
[in]moduleThe module.
[in]symbolThe symbol.
Returns:
The data associated with the symbol, or NULL on failure.

This function returns the data associated with 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.

Since :
2.3
void eina_module_symbol_global_set ( Eina_Module module,
Eina_Bool  global 
)

Defines if on module load we should expose all symbol.

Parameters:
moduleThe module to turn off/on symbol to be exposed
globaltrue to turn on symbol to be exposed, false otherwise
Since (EFL) :
1.11
Since :
3.0f(2.3.1)
char* eina_module_symbol_path_get ( const void *  symbol,
const char *  sub_dir 
)

Returns the path built from the location of a library and a given sub directory.

Parameters:
[in]symbolThe symbol to search for.
[in]sub_dirThe subdirectory to append.
Returns:
The built path on success, 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.

Since :
2.3

Unloads a module.

Parameters:
[in,out]moduleThe module to load.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

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 shut 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.

Since :
2.3

Variable Documentation

Since :
3.0f(2.3.1)