This group of 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 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 it simple to have different users for the same module.

The loaded shared objects may have two visible functions that are called and might provide initialization and shutdown procedures. The symbols are __eina_module_init and __eina_module_shutdown and are 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_Module *	eina_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)
	Gets the data associated to a symbol.
const char *	eina_module_file_get (const Eina_Module *module)
	Gets the file name associated to the module.
char *	eina_module_symbol_path_get (const void symbol, const char sub_dir)
	Gets 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)
	Gets the path built from the value of an environment variable and a given sub directory.
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.
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.
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)
	Frees every module on the list of modules.
Eina_Module *	eina_module_find (const Eina_Array array, const char module)
	Finds a module in an array.
Typedefs
typedef struct _Eina_Module	Eina_Module
	The structure type for the dynamic module loader handle.
typedef Eina_Bool(*	Eina_Module_Cb )(Eina_Module m, void data)
	The dynamic module loader callback.
typedef Eina_Bool(*	Eina_Module_Init )(void)
	If a function with such a signature is exported by the module as __eina_module_init, it is called on the first load after dlopen() and if `EINA_FALSE` is returned, the load fails, `EINA_TRUE` means the module is successfully initialized.
typedef void(*	Eina_Module_Shutdown )(void)
	If a function with such a signature is exported by the module as __eina_module_shutdown, it is called before calling dlclose()
Defines
#define	EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f
	Definition that 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
	Defintion that declares the given function as the module shutdown initializer (__eina_module_shutdown). It must be of signature Eina_Module_Shutdown.

Typedef Documentation

Eina_Module_Init

If a function with such a signature is exported by the module as __eina_module_init, it is called on the first load after dlopen() and if EINA_FALSE is returned, the load fails, EINA_TRUE means the module is successfully initialized.

See also:: Eina_Module_Shutdown

Eina_Module_Shutdown

If a function with such a signature is exported by the module as __eina_module_shutdown, it is 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.

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 array immediately. array can be NULL. In that case, it is created with 4 elements.

Since :: 2.3.1

Parameters:

[in]	array	The array that stores the list of the modules
[in]	path	The directory path to search for modules
[in]	arch	The architecture string

Returns:: The array of modules found in path matching arch

char* eina_module_environment_path_get	(	const char *	env,
		const char *	sub_dir
	)

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

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

Parameters:

[in]	env	The environment variable to expand
[in]	sub_dir	The subdirectory to append

Returns:: The built path on success, otherwise NULL

const char* eina_module_file_get ( const Eina_Module * module )

Gets the file name associated to the module.

This function returns the file name passed in eina_module_new(). If module is NULL, the function returns NULL immediately. The returned value must no be freed.

Since :: 2.3.1

Parameters:

[in] module The module

Returns:: The file name

Eina_Module* eina_module_find	(	const Eina_Array *	array,
		const char *	module
	)

Finds a module in an array.

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

Since :: 2.3.1

Parameters:

[in]	array	The array to find the module in
[in]	module	The name of the module to be searched

Returns:: The module to find on success, otherwise NULL

Eina_Bool eina_module_free ( Eina_Module * module )

Deletes a module.

This function calls eina_module_unload() if module has been previously loaded and frees the allocated memory. On success this function returns EINA_TRUE, otherwise it returns EINA_FALSE. If module is NULL, the function returns immediately.

Since :: 2.3.1

Parameters:

[in] module The module to delete

Returns:: EINA_TRUE on success, otherwise EINA_FALSE

void eina_module_list_free ( Eina_Array * array )

Frees every module on the list of modules.

This function calls eina_module_free() on each element found in array. If array is NULL, this function does nothing.

Since :: 2.3.1

Parameters:

[in] array The array of modules to free

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.

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 array immediately. If the returned value of cb is 0, the module is not added to the list, otherwise it is added. array can be NULL. In that case, it is created with 4 elements. cb can be NULL.

Since :: 2.3.1

Parameters:

[in]	array	The array that stores the list of the modules
[in]	path	The directory path to search for modules
[in]	recursive	The boolean value to iterate recursively on the path
[in]	cb	The callback function to call on each module
[in]	data	The data passed to the callback function

Returns:: The array of modules found in path

void eina_module_list_load ( Eina_Array * array )

Loads every module on the list of modules.

This function calls eina_module_load() on each element found in array. If array is NULL, this function does nothing.

Since :: 2.3.1

Parameters:

[in] array The array of modules to load

void eina_module_list_unload ( Eina_Array * array )

Unloads every module on the list of modules.

This function calls eina_module_unload() on each element found in array. If array is NULL, this function does nothing.

Since :: 2.3.1

Parameters:

[in] array The array of modules to unload

Eina_Bool eina_module_load ( Eina_Module * module )

Loads a module.

This function loads the shared file object passed in eina_module_new(). If it is an internal Eina module (like the mempools), it also initializes it. If the shared file object cannot be loaded, the error EINA_ERROR_WRONG_MODULE is set and and EINA_FALSE is returned. If it is an internal Eina module and the module cannot be initialized, the error EINA_ERROR_MODULE_INIT_FAILED is set and 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 EINA_FALSE immediately.

Since :: 2.3.1

Remarks:: When the symbols of the shared file objects are not needed anymore, call eina_module_unload() to unload the module.

Parameters:

[in] module The module to load

Returns:: EINA_TRUE on success, otherwise EINA_FALSE

Eina_Module* eina_module_new ( const char * file )

Returns a new module.

Since :: 2.3.1

Remarks:: When the new module is not needed anymore, use eina_module_free() to free the allocated memory.

Parameters:

[in] file The name of the file module to load

Returns:: A new module
If 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.

See also:: eina_module_load

void* eina_module_symbol_get	(	const Eina_Module *	module,
		const char *	symbol
	)

Gets the data associated to a symbol.

This function returns the data associated to symbol of module. module must have been loaded earlier with eina_module_load(). If module is NULL, or if it has not been correctly loaded before, the function returns NULL immediately.

Since :: 2.3.1

Parameters:

[in]	module	The module
[in]	symbol	The symbol

Returns:: The data associated to the symbol, otherwise NULL on failure

char* eina_module_symbol_path_get	(	const void *	symbol,
		const char *	sub_dir
	)

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

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

Parameters:

[in]	symbol	The symbol to search for
[in]	sub_dir	The subdirectory to append

Returns:: The built path on success, otherwise NULL

Eina_Bool eina_module_unload ( Eina_Module * module )

Unloads a module.

This function unloads 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 an internal Eina module, it is shut down just before. In that case, EINA_TRUE is returned. In all cases, the reference counter is decreased. If module is NULL, the function returns EINA_FALSE immediately.

Since :: 2.3.1

Parameters:

[in] module The module to unload

Returns:: EINA_TRUE on success, otherwise EINA_FALSE

Functions

Typedefs

Defines

Typedef Documentation

Function Documentation