AC_DEFINE(HAVE_DLADDR)
;;
mingw*)
-dnl nothing on mingw platform
+# nothing on mingw platform
;;
*)
AC_CHECK_FUNCS([dlopen], [res="yes"], [res="no"])
#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;
#else
+/**
+ * @cond LOCAL
+ */
+
#define EINA_MAGIC_NONE ((void) 0)
#define EINA_MAGIC
#define EINA_MAGIC_SET(d, m) ((void) 0)
#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
/**
* @{
*/
+/**
+ * @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;
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_*/
* 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)
* 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)
*
* 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
* 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.
*
* 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
* @endcond
*/
+
/*============================================================================*
* Global *
*============================================================================*/
* @{
*/
+/**
+ * @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)
{
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");
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)
{
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;
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;
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);
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);
}
/**
- * 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
* 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)
{
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;
-}
-
projects / framework / uifw / eina.git / commitdiff