From 7a3b2110bff934d74e63e800da02976b316bb0d4 Mon Sep 17 00:00:00 2001 From: Vincent Torri Date: Sun, 28 Jun 2009 06:29:11 +0000 Subject: [PATCH] * more doc * check the returned value of eina_error_init() in eina_module_init() SVN revision: 41218 --- legacy/eina/configure.ac | 2 +- legacy/eina/src/include/eina_magic.h | 68 +++++++++ legacy/eina/src/include/eina_mempool.h | 9 ++ legacy/eina/src/include/eina_module.h | 4 +- legacy/eina/src/lib/eina_benchmark.c | 3 + legacy/eina/src/lib/eina_counter.c | 5 +- legacy/eina/src/lib/eina_main.c | 26 +++- legacy/eina/src/lib/eina_module.c | 185 ++++++++++++++++++++----- legacy/eina/src/lib/eina_rectangle.c | 136 +++++++++--------- 9 files changed, 333 insertions(+), 105 deletions(-) diff --git a/legacy/eina/configure.ac b/legacy/eina/configure.ac index e157891f4e..0b38062334 100644 --- a/legacy/eina/configure.ac +++ b/legacy/eina/configure.ac @@ -300,7 +300,7 @@ case "$host_os" in AC_DEFINE(HAVE_DLADDR) ;; mingw*) -dnl nothing on mingw platform +# nothing on mingw platform ;; *) AC_CHECK_FUNCS([dlopen], [res="yes"], [res="no"]) diff --git a/legacy/eina/src/include/eina_magic.h b/legacy/eina/src/include/eina_magic.h index e9370a586d..f58f16bbfc 100644 --- a/legacy/eina/src/include/eina_magic.h +++ b/legacy/eina/src/include/eina_magic.h @@ -42,14 +42,74 @@ EAPI int eina_magic_string_shutdown(void); #ifdef EINA_MAGIC_DEBUG +/** + * @def EINA_MAGIC_NONE + * Random value for specifying that a structure using the magic + * feature has already been freed. It is used by eina_agic_fail(). + * + * If the magic feature of Eina is disabled, #EINA_MAGIC_NONE is just + * @c 0. + */ #define EINA_MAGIC_NONE 0x1234fedc +/** + * @def EINA_MAGIC + * Declaration of a variable of type #Eina_Magic. To put in a structure + * when one wants to use the magic feature of Eina with the functions + * of that structure, like that: + * + * @code + * struct Foo + * { + * int i; + * + * EINA_MAGIC + * }; + * @endcode + * + * If the magic feature of Eina is disabled, #EINA_MAGIC does nothing. + */ #define EINA_MAGIC Eina_Magic __magic; +/** + * @def EINA_MAGIC_SET(d, m) + * Set the magic number of @p d to @p m. @p d must be a valid pointer + * to a structure holding an Eina magic number declaration. Use + * #EINA_MAGIC to add such declaration. + * + * If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just + * the value @c 0. + */ #define EINA_MAGIC_SET(d, m) (d)->__magic = (m) + +/** + * @def EINA_MAGIC_CHECK(d, m) + * Test if @p d is @c NULL or not, and if not @c NULL, if + * @p d->__eina_magic is equal to @p m. @p d must be a structure that + * holds an Eina magic number declaration. Use #EINA_MAGIC to add such + * declaration. + * + * If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just + * the value @c 1. + */ #define EINA_MAGIC_CHECK(d, m) ((d) && ((d)->__magic == (m))) + +/** + * @def EINA_MAGIC_FAIL(d, m) + * Call eina_magic_fail() with the parameters @p d, @p d->__magic, @p + * m, __FILE__, __FUNCTION__ and __LINE__. @p d must be a structure that + * holds an Eina magic number declaration. Use #EINA_MAGIC to add such + * declaration. + * + * If the magic feature of Eina is disabled, #EINA_MAGIC_FAIL does + * nothing. + */ #define EINA_MAGIC_FAIL(d, m) eina_magic_fail((void*)(d), (d) ? (d)->__magic : 0, (m), __FILE__, __FUNCTION__, __LINE__); +/** + * @typedef Eina_Magic + * An abstract type for a magic number. + */ typedef unsigned int Eina_Magic; EAPI const char* eina_magic_string_get(Eina_Magic magic) EINA_PURE EINA_WARN_UNUSED_RESULT; @@ -59,6 +119,10 @@ EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, #else +/** + * @cond LOCAL + */ + #define EINA_MAGIC_NONE ((void) 0) #define EINA_MAGIC #define EINA_MAGIC_SET(d, m) ((void) 0) @@ -69,6 +133,10 @@ EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, #define eina_magic_string_set(Magic, Magic_Name) ((void) 0) #define eina_magic_fail(d, m, req_m, file, fnx, line) ((void) 0) +/** + * @endcond + */ + #endif /** diff --git a/legacy/eina/src/include/eina_mempool.h b/legacy/eina/src/include/eina_mempool.h index 70aeb3ff24..22d390f2cf 100644 --- a/legacy/eina/src/include/eina_mempool.h +++ b/legacy/eina/src/include/eina_mempool.h @@ -35,7 +35,16 @@ * @{ */ +/** + * @typedef Eina_Mempool + * Mempool type. + */ typedef struct _Eina_Mempool Eina_Mempool; + +/** + * @typedef Eina_Mempool_Backend + * Mempool backend type. + */ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend; EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE; diff --git a/legacy/eina/src/include/eina_module.h b/legacy/eina/src/include/eina_module.h index 1e82d77ee6..8156caa1df 100644 --- a/legacy/eina/src/include/eina_module.h +++ b/legacy/eina/src/include/eina_module.h @@ -65,6 +65,8 @@ EAPI void eina_module_list_load(Eina_Array *list) EINA_ARG_NONNULL(1); EAPI void eina_module_list_unload(Eina_Array *list) EINA_ARG_NONNULL(1); EAPI void eina_module_list_delete(Eina_Array *list) EINA_ARG_NONNULL(1); -/** @} */ +/** + * @} + */ #endif /*EINA_MODULE_H_*/ diff --git a/legacy/eina/src/lib/eina_benchmark.c b/legacy/eina/src/lib/eina_benchmark.c index 82c5b20887..f08066caa3 100644 --- a/legacy/eina/src/lib/eina_benchmark.c +++ b/legacy/eina/src/lib/eina_benchmark.c @@ -219,6 +219,9 @@ eina_benchmark_shutdown(void) * This function return a valid benchmark on success, or @c NULL if * memory allocation fails. In that case, the error is set to * #EINA_ERROR_OUT_OF_MEMORY. + * + * When the new module is not needed anymore, use + * eina_benchmark_free() to free the allocated memory. */ EAPI Eina_Benchmark * eina_benchmark_new(const char *name, const char *run) diff --git a/legacy/eina/src/lib/eina_counter.c b/legacy/eina/src/lib/eina_counter.c index 578d4913ea..ecb06dd5e5 100644 --- a/legacy/eina/src/lib/eina_counter.c +++ b/legacy/eina/src/lib/eina_counter.c @@ -304,6 +304,9 @@ eina_counter_shutdown(void) * name. If @p name is @c NULL, the function returns @c NULL * immediatly. If memory allocation fails, @c NULL is returned and the * error is set to #EINA_ERROR_OUT_OF_MEMORY. + * + * Whe the new counter is not needed anymore, use eina_counter_free() to + * free the allocated memory. */ EAPI Eina_Counter * eina_counter_new(const char *name) @@ -336,7 +339,7 @@ eina_counter_new(const char *name) * * This function remove the clock of @p counter from the used clocks * (see eina_counter_start()) and frees the memory allocated for - * @p counter. If @p counter is @c NULL, the functions returns + * @p counter. If @p counter is @c NULL, the function returns * immediatly. */ EAPI void diff --git a/legacy/eina/src/lib/eina_main.c b/legacy/eina/src/lib/eina_main.c index 756f43977a..bb586f9ef1 100644 --- a/legacy/eina/src/lib/eina_main.c +++ b/legacy/eina/src/lib/eina_main.c @@ -73,7 +73,18 @@ static int _eina_main_count = 0; * This function sets up all the eina modules. It returns 0 on * failure (that is, when one of the module fails to initialize), * otherwise it returns the number of times it has already been - * called. + * called. The list of initialisation functions that are called are + * (in that order): + * + * @li eina_error_init() + * @li eina_hash_init() + * @li eina_stringshare_init() + * @li eina_list_init() + * @li eina_array_init() + * @li eina_counter_init() + * @li eina_benchmark_init() + * @li eina_magic_string_init() + * @li eina_rectangle_init() * * When Eina is not used anymore, call eina_shutdown() to shut down * the Eina library. @@ -159,7 +170,18 @@ eina_init(void) * * This function shuts down the Eina library. It returns 0 when it has * been called the same number of times than eina_init(). In that case - * it shut down all the Eina modules. + * it shut down all the Eina modules. The list of shut down functions + * that are called are (in that order): + * + * @li eina_rectangle_init() + * @li eina_magic_string_init() + * @li eina_benchmark_init() + * @li eina_counter_init() + * @li eina_array_init() + * @li eina_list_init() + * @li eina_stringshare_init() + * @li eina_hash_init() + * @li eina_error_init() * * Once this function succeeds (that is, @c 0 is returned), you must * not call any of the Eina function anymore. You must call diff --git a/legacy/eina/src/lib/eina_module.c b/legacy/eina/src/lib/eina_module.c index 8a3a02a2a3..bbab43405e 100644 --- a/legacy/eina/src/lib/eina_module.c +++ b/legacy/eina/src/lib/eina_module.c @@ -149,6 +149,7 @@ static int _eina_module_count = 0; * @endcond */ + /*============================================================================* * Global * *============================================================================*/ @@ -165,6 +166,26 @@ static int _eina_module_count = 0; * @{ */ +/** + * @brief Initialize the eina module internal structure. + * + * @return 1 or greater on success, 0 on error. + * + * This function sets up the module module of Eina. It also registers + * the errors #EINA_ERROR_WRONG_MODULE and + * #EINA_ERROR_MODULE_INIT_FAILED. It is also called by + * eina_init(). It returns 0 on failure, otherwise it returns the + * number of times it has already been called. See eina_error_init() + * for the documentation of the initialisation of the dependency + * modules. + * + * Once the module module is not used anymore, then + * eina_module_shutdown() must be called to shut down the module + * module. + * + * @see eina_error_init() + * @see eina_init() + */ EAPI int eina_module_init(void) { @@ -173,7 +194,11 @@ eina_module_init(void) if (_eina_module_count != 1) goto end_init; - eina_error_init(); + if (!eina_error_init()) + { + fprintf(stderr, "Could not initialize eina error module.\n"); + return 0; + } EINA_ERROR_WRONG_MODULE = eina_error_msg_register("Wrong file format or no file module found"); EINA_ERROR_MODULE_INIT_FAILED = eina_error_msg_register("Module initialisation function failed"); @@ -182,6 +207,20 @@ end_init: return _eina_module_count; } +/** + * @brief Shut down the eina module internal structures + * + * @return 0 when the module module is completely shut down, 1 or + * greater otherwise. + * + * This function shuts down the module module set up by + * eina_module_init(). It is called by eina_shutdown(). It + * returns 0 when it is called the same number of times than + * eina_module_init(). + * + * @see eina_error_shutdown() + * @see eina_shutdown() + */ EAPI int eina_module_shutdown(void) { @@ -199,6 +238,82 @@ end_shutdown: return _eina_module_count; } +/** + * @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; + + EINA_SAFETY_ON_NULL_RETURN_VAL(file, NULL); + /* TODO check that the file exists. Update doc too */ + + m = malloc(sizeof(Eina_Module)); + /* TODO add the magic */ + m->file = strdup(file); + m->ref = 0; + m->handle = NULL; + + 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 immediatly. + */ +EAPI Eina_Bool eina_module_free(Eina_Module *m) +{ + EINA_SAFETY_ON_NULL_RETURN_VAL(m, EINA_FALSE); + + if (m->handle) + { + if (eina_module_unload(m) == EINA_FALSE) + return EINA_FALSE; + } + free(m->file); + free(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 immediatly #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; @@ -235,6 +350,20 @@ 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 immediatly #EINA_FALSE. + */ EAPI Eina_Bool eina_module_unload(Eina_Module *m) { Eina_Module_Shutdown *shut; @@ -253,36 +382,18 @@ EAPI Eina_Bool eina_module_unload(Eina_Module *m) return EINA_FALSE; } -EAPI Eina_Module * eina_module_new(const char *file) -{ - Eina_Module *m; - - EINA_SAFETY_ON_NULL_RETURN_VAL(file, NULL); - /* TODO check that the file exists */ - - m = malloc(sizeof(Eina_Module)); - /* TODO add the magic */ - m->file = strdup(file); - m->ref = 0; - m->handle = NULL; - - return m; -} - -EAPI Eina_Bool eina_module_free(Eina_Module *m) -{ - EINA_SAFETY_ON_NULL_RETURN_VAL(m, EINA_FALSE); - - if (m->handle) - { - if (eina_module_unload(m) == EINA_FALSE) - return EINA_FALSE; - } - free(m->file); - free(m); - return EINA_TRUE; -} - +/** + * @brief Retrive the data associated to a symbol. + * + * @param 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 immediatly @c NULL. + */ EAPI void * eina_module_symbol_get(Eina_Module *m, const char *symbol) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL); @@ -290,6 +401,16 @@ EAPI void * eina_module_symbol_get(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. + * + * Return the file name passed in eina_module_new(). If @p m is + * @c NULL, the function returns immediatly @c NULL. The returned + * value must no be freed. + */ EAPI const char * eina_module_file_get(Eina_Module *m) { EINA_SAFETY_ON_NULL_RETURN_VAL(m, NULL); @@ -365,7 +486,7 @@ EAPI char *eina_module_environment_path_get(const char *env, const char *sub_dir } /** - * Gets a list of modules found on the directory path + * Get a list of modules found on the directory path * * @param path The directory's path to search for modules * @param recursive Iterate recursively on the path diff --git a/legacy/eina/src/lib/eina_rectangle.c b/legacy/eina/src/lib/eina_rectangle.c index 9a898f36a9..31bc8ec6e5 100644 --- a/legacy/eina/src/lib/eina_rectangle.c +++ b/legacy/eina/src/lib/eina_rectangle.c @@ -214,6 +214,74 @@ _eina_rectangle_empty_space_find(Eina_List *empty, int w, int h, int *x, int *y) * API * *============================================================================*/ +EAPI int +eina_rectangle_init(void) +{ + const char *choice; + + _eina_rectangle_init_count++; + + if (_eina_rectangle_init_count > 1) return _eina_rectangle_init_count; + + if (!eina_error_init()) + { + EINA_ERROR_PERR("Could not initialize eina error module.\n"); + return 0; + } + if (!eina_mempool_init()) + { + EINA_ERROR_PERR("Could not initialize eina mempool module.\n"); + goto mempool_init_error; + } + +#ifdef EINA_DEFAULT_MEMPOOL + choice = "pass_through"; +#else + if (!(choice = getenv("EINA_MEMPOOL"))) + choice = "chained_mempool"; +#endif + + _eina_rectangle_alloc_mp = eina_mempool_add(choice, "rectangle-alloc", NULL, + sizeof (Eina_Rectangle_Alloc) + sizeof (Eina_Rectangle), 42); + if (!_eina_rectangle_alloc_mp) + { + EINA_ERROR_PERR("ERROR: Mempool for rectangle cannot be allocated in list init.\n"); + goto init_error; + } + + _eina_rectangle_mp = eina_mempool_add(choice, "rectangle", NULL, sizeof (Eina_Rectangle), 256); + if (!_eina_rectangle_mp) + { + EINA_ERROR_PERR("ERROR: Mempool for rectangle cannot be allocated in list init.\n"); + goto init_error; + } + + return _eina_rectangle_init_count; + + init_error: + eina_mempool_shutdown(); + mempool_init_error: + eina_error_shutdown(); + + return 0; +} + +EAPI int +eina_rectangle_shutdown(void) +{ + --_eina_rectangle_init_count; + + if (_eina_rectangle_init_count) return _eina_rectangle_init_count; + + eina_mempool_del(_eina_rectangle_alloc_mp); + eina_mempool_del(_eina_rectangle_mp); + + eina_mempool_shutdown(); + eina_error_shutdown(); + + return 0; +} + EAPI Eina_Rectangle * eina_rectangle_new(int x, int y, int w, int h) { @@ -390,71 +458,3 @@ eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) return EINA_TRUE; } -EAPI int -eina_rectangle_init(void) -{ - const char *choice; - - _eina_rectangle_init_count++; - - if (_eina_rectangle_init_count > 1) return _eina_rectangle_init_count; - - if (!eina_error_init()) - { - EINA_ERROR_PERR("Could not initialize eina error module.\n"); - return 0; - } - if (!eina_mempool_init()) - { - EINA_ERROR_PERR("Could not initialize eina mempool module.\n"); - goto mempool_init_error; - } - -#ifdef EINA_DEFAULT_MEMPOOL - choice = "pass_through"; -#else - if (!(choice = getenv("EINA_MEMPOOL"))) - choice = "chained_mempool"; -#endif - - _eina_rectangle_alloc_mp = eina_mempool_add(choice, "rectangle-alloc", NULL, - sizeof (Eina_Rectangle_Alloc) + sizeof (Eina_Rectangle), 42); - if (!_eina_rectangle_alloc_mp) - { - EINA_ERROR_PERR("ERROR: Mempool for rectangle cannot be allocated in list init.\n"); - goto init_error; - } - - _eina_rectangle_mp = eina_mempool_add(choice, "rectangle", NULL, sizeof (Eina_Rectangle), 256); - if (!_eina_rectangle_mp) - { - EINA_ERROR_PERR("ERROR: Mempool for rectangle cannot be allocated in list init.\n"); - goto init_error; - } - - return _eina_rectangle_init_count; - - init_error: - eina_mempool_shutdown(); - mempool_init_error: - eina_error_shutdown(); - - return 0; -} - -EAPI int -eina_rectangle_shutdown(void) -{ - --_eina_rectangle_init_count; - - if (_eina_rectangle_init_count) return _eina_rectangle_init_count; - - eina_mempool_del(_eina_rectangle_alloc_mp); - eina_mempool_del(_eina_rectangle_mp); - - eina_mempool_shutdown(); - eina_error_shutdown(); - - return 0; -} -