From 11ed8ad05fc0bdfc945d8e9d9e67e2c61b656414 Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Thu, 7 Apr 2011 12:57:44 +0000 Subject: [PATCH] more dox -> .h SVN revision: 58437 --- legacy/eina/src/include/eina_error.h | 4 +- legacy/eina/src/include/eina_module.h | 205 +++++++++++++++++++++++++- legacy/eina/src/lib/eina_module.c | 182 ----------------------- 3 files changed, 206 insertions(+), 185 deletions(-) diff --git a/legacy/eina/src/include/eina_error.h b/legacy/eina/src/include/eina_error.h index ec35c5438f..c6736a92c8 100644 --- a/legacy/eina/src/include/eina_error.h +++ b/legacy/eina/src/include/eina_error.h @@ -176,6 +176,8 @@ typedef int Eina_Error; * Error identifier corresponding to a lack of memory. */ +EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY; + /** * @brief Register a new error type. * @@ -190,8 +192,6 @@ typedef int Eina_Error; * * @see eina_error_msg_static_register() */ -EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY; - EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** diff --git a/legacy/eina/src/include/eina_module.h b/legacy/eina/src/include/eina_module.h index 547f6ac428..ca9a57068e 100644 --- a/legacy/eina/src/include/eina_module.h +++ b/legacy/eina/src/include/eina_module.h @@ -23,6 +23,14 @@ #include "eina_array.h" #include "eina_error.h" +/** + * @addtogroup Eina_Module_Group Module + * + * @brief These functions provide module management. + * + * @{ + */ + /** * @addtogroup Eina_Tools_Group Tools * @@ -86,7 +94,7 @@ typedef void (*Eina_Module_Shutdown)(void); * declares the given function as the module initializer (__eina_module_init). * It must be of signature #Eina_Module_Init */ -#define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f +#define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f /** * @def EINA_MODULE_SHUTDOWN @@ -108,34 +116,221 @@ extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE; */ extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED; +/** + * @brief Return a new module. + * + * @param file The name of the file module to load. + * + * This function returns a new module. If @p file is @c NULL, the + * function returns @c NULL, otherwise, it allocates an Eina_Module, + * stores a duplicate string of @p file, sets its reference to @c 0 + * and its handle to @c NULL. + * + * When the new module is not needed anymore, use eina_module_free() + * to free the allocated memory. + * + * @see eina_module_load + */ EAPI Eina_Module * eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Delete a module. + * + * @param m The module to delete. + * @return EINA_TRUE on success, EINA_FALSE otherwise. + * + * This function calls eina_module_unload() if @p m has been previously + * loaded and frees the allocated memory. On success this function + * returns EINA_TRUE and EINA_FALSE otherwise. If @p m is @c NULL, the + * function returns immediately. + */ EAPI Eina_Bool eina_module_free(Eina_Module *m) EINA_ARG_NONNULL(1); + +/** + * @brief Load a module. + * + * @param m The module to load. + * @return 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 initialize it. It the shared file object can not + * be loaded, the error #EINA_ERROR_WRONG_MODULE is set and + * #EINA_FALSE is returned. If it is a internal Eina module and the + * module can not be initialized, the error + * #EINA_ERROR_MODULE_INIT_FAILED is set and #EINA_FALSE is + * returned. If the module has already been loaded, it's refeence + * counter is increased by one and #EINA_TRUE is returned. If @p m is + * @c NULL, the function returns immediately #EINA_FALSE. + * + * When the symbols of the shared file objetcts are not needed + * anymore, call eina_module_unload() to unload the module. + */ EAPI Eina_Bool eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1); + +/** + * @brief Unload a module. + * + * @param m The module to load. + * @return EINA_TRUE on success, EINA_FALSE otherwise. + * + * This function unload the module @p m that has been previously + * loaded by eina_module_load(). If the reference counter of @p m is + * strictly greater than @c 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 @p m + * is @c NULL, the function returns immediately #EINA_FALSE. + */ EAPI Eina_Bool eina_module_unload(Eina_Module *m) EINA_ARG_NONNULL(1); + +/** + * @brief Retrive the data associated to a symbol. + * + * @param m The module. + * @param symbol The symbol. + * @return The data associated to the symbol, or @c NULL on failure. + * + * This function returns the data associated to @p symbol of @p m. @p + * m must have been loaded before with eina_module_load(). If @p m + * is @c NULL, or if it has not been correctly loaded before, the + * function returns immediately @c NULL. + */ EAPI void * eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Return the file name associated to the module. + * + * @param m The module. + * @return The file name. + * + * This function returns the file name passed in eina_module_new(). If + * @p m is @c NULL, the function returns immediately @c NULL. The + * returned value must no be freed. + */ EAPI const char * eina_module_file_get(const Eina_Module *m) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Return the path built from the location of a library and a + * given sub directory. + * + * @param symbol The symbol to search for. + * @param sub_dir The subdirectory to append. + * @return The built path on success, @c NULL otherwise. + * + * This function returns the path built by concatenating the path of + * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir + * can be @c 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 @c NULL. + */ EAPI char * eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); + +/** + * @brief Return the path built from the value of an environment varialbe and a + * given sub directory. + * + * @param env The environment variable to expand. + * @param sub_dir The subdirectory to append. + * @return The built path on success, @c NULL otherwise. + * + * This function returns the path built by concatenating the value of + * the environment variable named @p env and @p sub_dir. @p sub_dir + * can be @c NULL. The returned path must be freed when not used + * anymore. If the symbol is not found, or @p env does not exist, or + * allocation fails, this function returns @c NULL. + */ EAPI char * eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); + +/** + * @brief Get an array of modules found on the directory path matching an arch type. + * + * @param array The array that stores the list of the modules. + * @param path The directory's path to search for modules. + * @param arch The architecture string. + * + * This function adds to @p array the module names found in @p path + * which match the cpu architecture @p arch. If @p path or @p arch is + * @c NULL, the function returns immediately @p array. @p array can be + * @c NULL. In that case, it is created with 4 elements. + */ EAPI Eina_Array * eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch); + +/** + * @brief Get a list of modules found on the directory path. + * + * @param array The array that stores the list of the modules. + * @param path The directory's path to search for modules. + * @param recursive Iterate recursively on the path. + * @param cb Callback function to call on each module. + * @param data Data passed to the callback function. + * + * This function adds to @p array the list of modules found in + * @p path. If @p recursive is #EINA_TRUE, then recursive search is + * done. The callback @p cb is called on each module found, and @p data + * is passed to @p cb. If @p path is @c NULL, the function returns + * immediately @p array. If the returned value of @p cb is 0, the + * module will not be added to the list, otherwise it will be added. + * @p array can be @c NULL. In that case, it is created with 4 + * elements. @p cb can be @c NULL. + */ EAPI Eina_Array * 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; + +/** + * @brief Load every module on the list of modules. + * + * @param array The array of modules to load. + * + * This function calls eina_module_load() on each element found in + * @p array. If @p array is @c NULL, this function does nothing. + */ EAPI void eina_module_list_load(Eina_Array *list) EINA_ARG_NONNULL(1); + +/** + * @brief Unload every module on the list of modules. + * + * @param array The array of modules to unload. + * + * This function calls eina_module_unload() on each element found in + * @p array. If @p array is @c NULL, this function does nothing. + */ EAPI void eina_module_list_unload(Eina_Array *list) EINA_ARG_NONNULL(1); + +/** + * @p Free every module on the list of modules. + * + * @param array The array of modules to free. + * + * This function calls eina_module_free() on each element found in + * @p array. If @p array is @c NULL, this function does nothing. + */ EAPI void eina_module_list_free(Eina_Array *list) EINA_ARG_NONNULL(1); + +/** + * @brief Find an module in array. + * + * @param array The array to find the module. + * @param module The name of module to be searched. + * + * This function finds an @p module in @p array. + * If the element is found the function returns the module, else + * @c NULL is returned. + */ EAPI Eina_Module * eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2); @@ -147,4 +342,12 @@ EAPI Eina_Module * * @} */ +/** + * @} + */ + +/** + * @} + */ + #endif /*EINA_MODULE_H_*/ diff --git a/legacy/eina/src/lib/eina_module.c b/legacy/eina/src/lib/eina_module.c index 5c46b7a2da..541534a791 100644 --- a/legacy/eina/src/lib/eina_module.c +++ b/legacy/eina/src/lib/eina_module.c @@ -262,29 +262,6 @@ eina_module_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Module_Group Module - * - * @brief These functions provide module management. - * - * @{ - */ - -/** - * @brief Return a new module. - * - * @param file The name of the file module to load. - * - * This function returns a new module. If @p file is @c NULL, the - * function returns @c NULL, otherwise, it allocates an Eina_Module, - * stores a duplicate string of @p file, sets its reference to @c 0 - * and its handle to @c NULL. - * - * When the new module is not needed anymore, use eina_module_free() - * to free the allocated memory. - * - * @see eina_module_load - */ EAPI Eina_Module *eina_module_new(const char *file) { Eina_Module *m; @@ -312,17 +289,6 @@ EAPI Eina_Module *eina_module_new(const char *file) return m; } -/** - * @brief Delete a module. - * - * @param m The module to delete. - * @return EINA_TRUE on success, EINA_FALSE otherwise. - * - * This function calls eina_module_unload() if @p m has been previously - * loaded and frees the allocated memory. On success this function - * returns EINA_TRUE and EINA_FALSE otherwise. If @p m is @c NULL, the - * function returns immediately. - */ EAPI Eina_Bool eina_module_free(Eina_Module *m) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, EINA_FALSE); @@ -337,26 +303,6 @@ EAPI Eina_Bool eina_module_free(Eina_Module *m) return EINA_TRUE; } -/** - * @brief Load a module. - * - * @param m The module to load. - * @return 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 initialize it. It the shared file object can not - * be loaded, the error #EINA_ERROR_WRONG_MODULE is set and - * #EINA_FALSE is returned. If it is a internal Eina module and the - * module can not be initialized, the error - * #EINA_ERROR_MODULE_INIT_FAILED is set and #EINA_FALSE is - * returned. If the module has already been loaded, it's refeence - * counter is increased by one and #EINA_TRUE is returned. If @p m is - * @c NULL, the function returns immediately #EINA_FALSE. - * - * When the symbols of the shared file objetcts are not needed - * anymore, call eina_module_unload() to unload the module. - */ EAPI Eina_Bool eina_module_load(Eina_Module *m) { void *dl_handle; @@ -400,20 +346,6 @@ loaded: return EINA_TRUE; } -/** - * @brief Unload a module. - * - * @param m The module to load. - * @return EINA_TRUE on success, EINA_FALSE otherwise. - * - * This function unload the module @p m that has been previously - * loaded by eina_module_load(). If the reference counter of @p m is - * strictly greater than @c 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 @p m - * is @c NULL, the function returns immediately #EINA_FALSE. - */ EAPI Eina_Bool eina_module_unload(Eina_Module *m) { Eina_Module_Shutdown *shut; @@ -437,18 +369,6 @@ EAPI Eina_Bool eina_module_unload(Eina_Module *m) return EINA_FALSE; } -/** - * @brief Retrive the data associated to a symbol. - * - * @param m The module. - * @param symbol The symbol. - * @return The data associated to the symbol, or @c NULL on failure. - * - * This function returns the data associated to @p symbol of @p m. @p - * m must have been loaded before with eina_module_load(). If @p m - * is @c NULL, or if it has not been correctly loaded before, the - * function returns immediately @c NULL. - */ EAPI void *eina_module_symbol_get(const Eina_Module *m, const char *symbol) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL); @@ -456,36 +376,12 @@ EAPI void *eina_module_symbol_get(const Eina_Module *m, const char *symbol) return dlsym(m->handle, symbol); } -/** - * @brief Return the file name associated to the module. - * - * @param m The module. - * @return The file name. - * - * This function returns the file name passed in eina_module_new(). If - * @p m is @c NULL, the function returns immediately @c NULL. The - * returned value must no be freed. - */ EAPI const char *eina_module_file_get(const Eina_Module *m) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL); return m->file; } -/** - * @brief Return the path built from the location of a library and a - * given sub directory. - * - * @param symbol The symbol to search for. - * @param sub_dir The subdirectory to append. - * @return The built path on success, @c NULL otherwise. - * - * This function returns the path built by concatenating the path of - * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir - * can be @c 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 @c NULL. - */ EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir) { #ifdef HAVE_DLADDR @@ -526,20 +422,6 @@ EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir) return NULL; } -/** - * @brief Return the path built from the value of an environment varialbe and a - * given sub directory. - * - * @param env The environment variable to expand. - * @param sub_dir The subdirectory to append. - * @return The built path on success, @c NULL otherwise. - * - * This function returns the path built by concatenating the value of - * the environment variable named @p env and @p sub_dir. @p sub_dir - * can be @c NULL. The returned path must be freed when not used - * anymore. If the symbol is not found, or @p env does not exist, or - * allocation fails, this function returns @c NULL. - */ EAPI char *eina_module_environment_path_get(const char *env, const char *sub_dir) { @@ -574,18 +456,6 @@ EAPI char *eina_module_environment_path_get(const char *env, return NULL; } -/** - * @brief Get an array of modules found on the directory path matching an arch type. - * - * @param array The array that stores the list of the modules. - * @param path The directory's path to search for modules. - * @param arch The architecture string. - * - * This function adds to @p array the module names found in @p path - * which match the cpu architecture @p arch. If @p path or @p arch is - * @c NULL, the function returns immediately @p array. @p array can be - * @c NULL. In that case, it is created with 4 elements. - */ EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch) @@ -604,24 +474,6 @@ EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array, return list_get_cb_data.array; } -/** - * @brief Get a list of modules found on the directory path. - * - * @param array The array that stores the list of the modules. - * @param path The directory's path to search for modules. - * @param recursive Iterate recursively on the path. - * @param cb Callback function to call on each module. - * @param data Data passed to the callback function. - * - * This function adds to @p array the list of modules found in - * @p path. If @p recursive is #EINA_TRUE, then recursive search is - * done. The callback @p cb is called on each module found, and @p data - * is passed to @p cb. If @p path is @c NULL, the function returns - * immediately @p array. If the returned value of @p cb is 0, the - * module will not be added to the list, otherwise it will be added. - * @p array can be @c NULL. In that case, it is created with 4 - * elements. @p cb can be @c NULL. - */ EAPI Eina_Array *eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, @@ -646,16 +498,6 @@ EAPI Eina_Array *eina_module_list_get(Eina_Array *array, return list_get_cb_data.array; } -/** - * @brief Find an module in array. - * - * @param array The array to find the module. - * @param module The name of module to be searched. - * - * This function finds an @p module in @p array. - * If the element is found the function returns the module, else - * @c NULL is returned. - */ EAPI Eina_Module * eina_module_find(const Eina_Array *array, const char *module) { @@ -687,14 +529,6 @@ eina_module_find(const Eina_Array *array, const char *module) return NULL; } -/** - * @brief Load every module on the list of modules. - * - * @param array The array of modules to load. - * - * This function calls eina_module_load() on each element found in - * @p array. If @p array is @c NULL, this function does nothing. - */ EAPI void eina_module_list_load(Eina_Array *array) { Eina_Array_Iterator iterator; @@ -707,14 +541,6 @@ EAPI void eina_module_list_load(Eina_Array *array) eina_module_load(m); } -/** - * @brief Unload every module on the list of modules. - * - * @param array The array of modules to unload. - * - * This function calls eina_module_unload() on each element found in - * @p array. If @p array is @c NULL, this function does nothing. - */ EAPI void eina_module_list_unload(Eina_Array *array) { Eina_Array_Iterator iterator; @@ -727,14 +553,6 @@ EAPI void eina_module_list_unload(Eina_Array *array) eina_module_unload(m); } -/** - * @p Free every module on the list of modules. - * - * @param array The array of modules to free. - * - * This function calls eina_module_free() on each element found in - * @p array. If @p array is @c NULL, this function does nothing. - */ EAPI void eina_module_list_free(Eina_Array *array) { Eina_Array_Iterator iterator;