* @{
*/
+/**
+ * @typedef Eina_Inlist
+ * Inlined list type.
+ */
typedef struct _Eina_Inlist Eina_Inlist;
+
+/**
+ * @struct _Eina_Inlist
+ * Inlined list type.
+ */
struct _Eina_Inlist
{
- Eina_Inlist *next;
- Eina_Inlist *prev;
- Eina_Inlist *last;
+ Eina_Inlist *next; /**< next node */
+ Eina_Inlist *prev; /**< previous node */
+ Eina_Inlist *last; /**< last node */
};
#define EINA_INLIST Eina_Inlist __in_list
* @def EINA_ITERATOR_FOREACH
* @brief Macro to iterate over all elements easily.
*
- * @param iterator The iterator to use.
+ * @param itr The iterator to use.
* @param data Where to store * data, must be a pointer support getting
* its address since * eina_iterator_next() requires a pointer
* to pointer!
void *data; /**< Pointer to list element payload */
Eina_List *next; /**< Next member in the list */
Eina_List *prev; /**< Previous member in the list */
- struct _Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */
+ Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */
EINA_MAGIC
};
#define EINA_LOG_DBG(fmt, ...) \
EINA_LOG(EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_DBG, fmt, ##__VA_ARGS__)
+/**
+ * @typedef Eina_Log_Domain
+ * The domain used for logging.
+ */
typedef struct _Eina_Log_Domain Eina_Log_Domain;
+/**
+ * @struct _Eina_Log_Domain
+ * The domain used for logging.
+ */
struct _Eina_Log_Domain
{
- int level; /**< Max level to log */
+ int level; /**< Max level to log */
const char *domain_str; /**< Formatted string with color to print */
const char *name; /**< Domain name */
/* Private */
- Eina_Bool deleted:1; /**< Flags deletion of domain, a free slot */
+ Eina_Bool deleted:1; /**< Flags deletion of domain, a free slot */
};
EAPI void eina_log_threads_enable(void);
#include "eina_iterator.h"
#include "eina_rectangle.h"
+/**
+ * @addtogroup Eina_Data_Types_Group Data Types
+ *
+ * @{
+ */
+
+/**
+ * @defgroup Eina_Tiler_Group Tiler
+ *
+ * @{
+ */
+
+/**
+ * @typedef Eina_Tiler
+ * Tiler type.
+ */
typedef struct _Eina_Tiler Eina_Tiler;
+/**
+ * @typedef Eina_Tile_Grid_Info
+ * Grid type of a tiler.
+ */
+typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info;
+
+/**
+ * @struct Eina_Tile_Grid_Info
+ * Grid type of a tiler.
+ */
struct Eina_Tile_Grid_Info
{
- unsigned long col, row;
- Eina_Rectangle rect;
- Eina_Bool full;
+ unsigned long col; /**< column of the tiler grid */
+ unsigned long row; /**< row of the tiler grid*/
+ Eina_Rectangle rect; /**< rectangle of the tiler grid*/
+ Eina_Bool full; /**< whether the grid is full or not */
};
-typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info;
typedef struct _Eina_Tile_Grid_Slicer Eina_Tile_Grid_Slicer;
EAPI Eina_Tiler *eina_tiler_new(int w, int h);
#include "eina_inline_tiler.x"
+
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
+
#endif /* EINA_TILER_H_ */
# define EINA_LIKELY(exp) exp
#else /* ! __GNUC__ && ! _WIN32 && ! __SUNPRO_C */
+
+/**
+ * @def EINA_WARN_UNUSED_RESULT
+ * Used to warn when the returned value of the function is not used.
+ */
# define EINA_WARN_UNUSED_RESULT
+
+/**
+ * @def EINA_ARG_NONNULL
+ * Used to warn when the specified arguments of the function are @c NULL.
+ */
# define EINA_ARG_NONNULL(idx, ...)
+
+/**
+ * @def EINA_DEPRECATED
+ * Used to warn when the function is considered as deprecated.
+ */
# define EINA_DEPRECATED
# define EINA_MALLOC
# define EINA_PURE
/* remove this TRUE/FALSE redifinitions */
+/**
+ * @deprecated Use #EINA_TRUE instead.
+ */
#ifndef TRUE
# define TRUE 1
#endif
+/**
+ * @deprecated Use #EINA_FALSE instead.
+ */
#ifndef FALSE
# define FALSE 0
#endif
+/**
+ * @typedef Eina_Bool
+ * Type to mimic a boolean.
+ */
typedef unsigned char Eina_Bool;
/**
#define EINA_SORT_MIN 0
#define EINA_SORT_MAX 1
+/**
+ * @typedef Eina_Compare_Cb
+ * Function used in functions using sorting. It compares @p data1 and
+ * @p data2. If @p data1 is 'less' than @p data2, -1 must be returned,
+ * if it is 'greater', 1 must be returned, and if they are equal, 0
+ * must be returned.
+ */
typedef int (*Eina_Compare_Cb) (const void *data1, const void *data2);
+
+/**
+ * @def EINA_COMPARE_CB
+ * Macro to cast to Eina_Compare_Cb.
+ */
#define EINA_COMPARE_CB(function) ((Eina_Compare_Cb)function)
typedef Eina_Bool (*Eina_Each)(const void *container,
void *data,
void *fdata);
+
+/**
+ * @def EINA_EACH
+ * Macro to cast to Eina_Each.
+ */
#define EINA_EACH(Function) ((Eina_Each)Function)
+/**
+ * @typedef Eina_Free_Cb
+ * A callback type used to free data when iterating over a container.
+ */
typedef void (*Eina_Free_Cb)(void *data);
+
+/**
+ * @def EINA_FREE_CB
+ * Macro to cast to Eina_Free_Cb.
+ */
#define EINA_FREE_CB(Function) ((Eina_Free_Cb)Function)
/**
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Accessor_Group Accessor Functions
- *
- * @brief These functions manage accessor on containers.
- *
- * These functions allow to access elements of a container in a
- * generic way, without knowing which container is used (a bit like
- * iterators in the C++ STL). Accessors allows random access (that is, any
- * element in the container). For sequential access, see
- * @ref Eina_Iterator_Group.
- *
- * An accessor is created from container data types, so no creation
- * function is available here. An accessor is deleted with
- * eina_accessor_free(). To get the data of an element at a given
- * position, use eina_accessor_data_get(). To call a function on
- * chosen elements of a container, use eina_accessor_over().
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the accessor module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Accessor_Group Accessor Functions
+ *
+ * @brief These functions manage accessor on containers.
+ *
+ * These functions allow to access elements of a container in a
+ * generic way, without knowing which container is used (a bit like
+ * iterators in the C++ STL). Accessors allows random access (that is, any
+ * element in the container). For sequential access, see
+ * @ref Eina_Iterator_Group.
+ *
+ * An accessor is created from container data types, so no creation
+ * function is available here. An accessor is deleted with
+ * eina_accessor_free(). To get the data of an element at a given
+ * position, use eina_accessor_data_get(). To call a function on
+ * chosen elements of a container, use eina_accessor_over().
+ *
+ * @{
+ */
+
/**
* @brief Free an accessor.
*
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Array_Group Array
- *
- * @brief These functions provide array management.
- *
- * The Array data type in Eina is designed to have a very fast access to
- * its data (compared to the Eina @ref Eina_List_Group). On the other hand,
- * data can be added or removed only at the end of the array. To insert
- * data at any place, the Eina @ref Eina_List_Group is the correct container
- * to use.
- *
- * To use the array data type, eina_init() must be called before any
- * other array functions. When eina is no more array function is used,
- * eina_shutdown() must be called to free all the resources.
- *
- * An array must be created with eina_array_new(). It allocated all
- * the necessary data for an array. When not needed anymore, an array
- * is freed with eina_array_free(). This function does not free any
- * allocated memory used to store the data of each element. For that,
- * just iterate over the array to free them. A convenient way to do
- * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given
- * in the description of this macro.
- *
- * @warning All the other functions do not check if the used array is
- * valid or not. It's up to the user to be sure of that. It is
- * designed like that for performance reasons.
- *
- * The usual features of an array are classic ones: to append an
- * element, use eina_array_push() and to remove the last element, use
- * eina_array_pop(). To retrieve the element at a given positin, use
- * eina_array_data_get(). The number of elements can be retrieved with
- * eina_array_count_get().
- *
- * For more information, you can look at the @ref tutorial_array_page.
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the array module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Array_Group Array
+ *
+ * @brief These functions provide array management.
+ *
+ * The Array data type in Eina is designed to have a very fast access to
+ * its data (compared to the Eina @ref Eina_List_Group). On the other hand,
+ * data can be added or removed only at the end of the array. To insert
+ * data at any place, the Eina @ref Eina_List_Group is the correct container
+ * to use.
+ *
+ * To use the array data type, eina_init() must be called before any
+ * other array functions. When eina is no more array function is used,
+ * eina_shutdown() must be called to free all the resources.
+ *
+ * An array must be created with eina_array_new(). It allocated all
+ * the necessary data for an array. When not needed anymore, an array
+ * is freed with eina_array_free(). This function does not free any
+ * allocated memory used to store the data of each element. For that,
+ * just iterate over the array to free them. A convenient way to do
+ * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given
+ * in the description of this macro.
+ *
+ * @warning All the other functions do not check if the used array is
+ * valid or not. It's up to the user to be sure of that. It is
+ * designed like that for performance reasons.
+ *
+ * The usual features of an array are classic ones: to append an
+ * element, use eina_array_push() and to remove the last element, use
+ * eina_array_pop(). To retrieve the element at a given positin, use
+ * eina_array_data_get(). The number of elements can be retrieved with
+ * eina_array_count_get().
+ *
+ * For more information, you can look at the @ref tutorial_array_page.
+ *
+ * @{
+ */
+
/**
* @brief Create a new array.
*
* @li Run the benchmark.
* @li Free the memory.
*
- * Here is a basic example which bechmark which creates two functions
+ * Here is a basic example of bechmark which creates two functions
* that will be run. These functions just print a message.
*
* @code
* last 3 values passed to eina_benchmark_register(). See the document
* of that function for the detailed behavior.
*
- * The Gnuplot file will be named bench_test_run.gnuplot. Just run:
+ * The gnuplot file will be named bench_test_run.gnuplot. Just run:
*
* @code
* gnuplot bench_test_run.gnuplot
* @section tutorial_benchmark_advanced_usage More Advanced Usage
*
* In this section, several test will be created and run. The idea is
- * exactly the same than in the previous section.
+ * exactly the same than in the previous section, but with some basic
+ * automatic way to run all the benchmarks. The following code
+ * benchmarks some Eina converts functions, and some Eina containers
+ * types:
*
- * to be done.
+ * @code
+ * #include <stdlib.h>
+ * #include <stdio.h>
+ * #include <time.h>
+ *
+ * #include <Eina.h>
+ *
+ * static void bench_convert(Eina_Benchmark *bench);
+ * static void bench_container(Eina_Benchmark *bench);
+ *
+ * typedef struct _Benchmark_Case Benchmark_Case;
+ *
+ * struct _Benchmark_Case
+ * {
+ * const char *bench_case;
+ * void (*build)(Eina_Benchmark *bench);
+ * };
+ *
+ * static const Benchmark_Case benchmarks[] = {
+ * { "Bench 1", bench_convert },
+ * { "Bench 2", bench_container },
+ * { NULL, NULL }
+ * };
+ *
+ * static
+ * void convert1(int request)
+ * {
+ * char tmp[128];
+ * int i;
+ *
+ * srand(time(NULL));
+ *
+ * for (i = 0; i < request; ++i)
+ * eina_convert_itoa(rand(), tmp);
+ * }
+ *
+ * static
+ * void convert2(int request)
+ * {
+ * char tmp[128];
+ * int i;
+ *
+ * srand(time(NULL));
+ *
+ * for (i = 0; i < request; ++i)
+ * eina_convert_xtoa(rand(), tmp);
+ * }
+ *
+ * static void
+ * bench_convert(Eina_Benchmark *bench)
+ * {
+ * eina_benchmark_register(bench, "convert-1", EINA_BENCHMARK(convert1), 200, 400, 10);
+ * eina_benchmark_register(bench, "convert-2", EINA_BENCHMARK(convert2), 200, 400, 10);
+ * }
+ *
+ * static
+ * void array(int request)
+ * {
+ * Eina_Array *array;
+ * Eina_Array_Iterator it;
+ * int *data;
+ * int i;
+ *
+ * srand(time(NULL));
+ *
+ * array = eina_array_new(64);
+ *
+ * for (i = 0; i < request; ++i)
+ * {
+ * data = (int *)malloc(sizeof(int));
+ * if (!data) continue;
+ * *data = rand();
+ * eina_array_push(array, data);
+ * }
+ *
+ * EINA_ARRAY_ITER_NEXT(array, i, data, it)
+ * free(data);
+ *
+ * eina_array_free(array);
+ * }
+ *
+ * static
+ * void list(int request)
+ * {
+ * Eina_List *l = NULL;
+ * int *data;
+ * int i;
+ *
+ * srand(time(NULL));
+ *
+ * for (i = 0; i < request; ++i)
+ * {
+ * data = (int *)malloc(sizeof(int));
+ * if (!data) continue;
+ * *data = rand();
+ * l = eina_list_prepend(l, data);
+ * }
+ *
+ * while (l)
+ * {
+ * free(eina_list_data_get(l));
+ * l = eina_list_remove_list(l, l);
+ * }
+ * }
+ *
+ * static void
+ * bench_container(Eina_Benchmark *bench)
+ * {
+ * eina_benchmark_register(bench, "array", EINA_BENCHMARK(array), 200, 300, 10);
+ * eina_benchmark_register(bench, "list", EINA_BENCHMARK(list), 200, 300, 10);
+ * }
+ *
+ * int main()
+ * {
+ * Eina_Benchmark *test;
+ * Eina_Array *ea;
+ * unsigned int i;
+ *
+ * if (!eina_init())
+ * return EXIT_FAILURE;
+ *
+ * for (i = 0; benchmarks[i].bench_case != NULL; ++i)
+ * {
+ * test = eina_benchmark_new(benchmarks[i].bench_case, "Benchmark example");
+ * if (!test)
+ * continue;
+ *
+ * benchmarks[i].build(test);
+ *
+ * ea = eina_benchmark_run(test);
+ * if(ea)
+ * {
+ * Eina_Array_Iterator it;
+ * char *tmp;
+ * unsigned int i;
+ *
+ * EINA_ARRAY_ITER_NEXT(ea, i, tmp, it)
+ * free(tmp);
+ *
+ * eina_array_free(ea);
+ * }
+ *
+ * if (test)
+ * eina_benchmark_free(test);
+ * }
+ *
+ * eina_shutdown();
+ *
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
+ *
+ * gnuplot can be used to see how are performed the convert functions
+ * together, as well as how are performed the containers. So it is now
+ * easy to see that the hexadecimal convert function is faster than
+ * the decimal one, and that arrays are faster than lists.
+ *
+ * You can improve all that by executing automatically gnuplot in your
+ * program, or integrate the Eina benchmark framework in an autotooled
+ * project. See that
+ * <a href="http://trac.enlightenment.org/e/wiki/AutotoolsIntegration#Benchmark">page</a>
+ * for more informations.
*
*/
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Benchmark_Group Benchmark
- *
- * These functions allow you to add benchmark framework in a project
- * for timing critical part and detect slow parts of code. It is used
- * in Eina to compare the time used by eina, glib, evas and ecore data
- * types.
- *
- * To use the benchmark module, Eina must be initialized with
- * eina_init() and later shut down with eina_shutdown(). A benchmark
- * is created with eina_benchmark_new() and freed with
- * eina_benchmark_free().
- *
- * eina_benchmark_register() adds a test to a benchmark. That test can
- * be run a certain amount of times. Adding more than one test to be
- * executed allows the comparison between several parts of a program,
- * or different implementations.
- *
- * eina_benchmark_run() runs all the tests registered with
- * eina_benchmark_register(). The amount of time of each test is
- * written in a gnuplot file.
- *
- * For more information, you can look at the @ref tutorial_benchmark_page.
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the benchmark module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Benchmark_Group Benchmark
+ *
+ * These functions allow you to add benchmark framework in a project
+ * for timing critical part and detect slow parts of code. It is used
+ * in Eina to compare the time used by eina, glib, evas and ecore data
+ * types.
+ *
+ * To use the benchmark module, Eina must be initialized with
+ * eina_init() and later shut down with eina_shutdown(). A benchmark
+ * is created with eina_benchmark_new() and freed with
+ * eina_benchmark_free().
+ *
+ * eina_benchmark_register() adds a test to a benchmark. That test can
+ * be run a certain amount of times. Adding more than one test to be
+ * executed allows the comparison between several parts of a program,
+ * or different implementations.
+ *
+ * eina_benchmark_run() runs all the tests registered with
+ * eina_benchmark_register(). The amount of time of each test is
+ * written in a gnuplot file.
+ *
+ * For more information, you can look at the @ref tutorial_benchmark_page.
+ *
+ * @{
+ */
+
/**
* @brief Create a new array.
*
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
/**
* @cond LOCAL
*/
*/
/**
+ * @internal
+ * @brief Initialize the convert module.
+ *
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ *
+ * This function sets up the convert module of Eina. It is called by
+ * eina_init().
+ *
+ * This function sets up the error module of Eina and registers the
+ * errors #EINA_ERROR_CONVERT_0X_NOT_FOUND,
+ * #EINA_ERROR_CONVERT_P_NOT_FOUND and
+ * #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH.
+ *
+ * @see eina_init()
+ */
+Eina_Bool
+eina_convert_init(void)
+{
+ _eina_convert_log_dom = eina_log_domain_register("eina_convert", EINA_LOG_COLOR_DEFAULT);
+ if (_eina_convert_log_dom < 0)
+ {
+ EINA_LOG_ERR("Could not register log domain: eina_convert");
+ return EINA_FALSE;
+ }
+
+#define EEMR(n) n = eina_error_msg_static_register(n##_STR)
+ EEMR(EINA_ERROR_CONVERT_0X_NOT_FOUND);
+ EEMR(EINA_ERROR_CONVERT_P_NOT_FOUND);
+ EEMR(EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH);
+#undef EEMR
+
+ return EINA_TRUE;
+}
+
+/**
+ * @internal
+ * @brief Shut down the convert module.
+ *
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ *
+ * This function shuts down the convert module set up by
+ * eina_convert_init(). It is called by eina_shutdown().
+ *
+ * @see eina_shutdown()
+ */
+Eina_Bool
+eina_convert_shutdown(void)
+{
+ eina_log_domain_unregister(_eina_convert_log_dom);
+ _eina_convert_log_dom = -1;
+ return EINA_TRUE;
+}
+
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
* @addtogroup Eina_Convert_Group Convert
*
* These functions allow you to convert integer or real numbers to
* @{
*/
-/**
- * @internal
- * @brief Initialize the convert module.
- *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This function sets up the convert module of Eina. It is called by
- * eina_init().
- *
- * This function sets up the error module of Eina and registers the
- * errors #EINA_ERROR_CONVERT_0X_NOT_FOUND,
- * #EINA_ERROR_CONVERT_P_NOT_FOUND and
- * #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH.
- *
- * @see eina_init()
- */
-Eina_Bool
-eina_convert_init(void)
-{
- _eina_convert_log_dom = eina_log_domain_register("eina_convert", EINA_LOG_COLOR_DEFAULT);
- if (_eina_convert_log_dom < 0)
- {
- EINA_LOG_ERR("Could not register log domain: eina_convert");
- return EINA_FALSE;
- }
-
-#define EEMR(n) n = eina_error_msg_static_register(n##_STR)
- EEMR(EINA_ERROR_CONVERT_0X_NOT_FOUND);
- EEMR(EINA_ERROR_CONVERT_P_NOT_FOUND);
- EEMR(EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH);
-#undef EEMR
-
- return EINA_TRUE;
-}
-
-/**
- * @internal
- * @brief Shut down the convert module.
- *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This function shuts down the convert module set up by
- * eina_convert_init(). It is called by eina_shutdown().
- *
- * @see eina_shutdown()
- */
-Eina_Bool
-eina_convert_shutdown(void)
-{
- eina_log_domain_unregister(_eina_convert_log_dom);
- _eina_convert_log_dom = -1;
- return EINA_TRUE;
-}
-
/*
* Come from the second edition of The C Programming Language ("K&R2") on page 64
*/
* @param des The destination buffer to store the converted fixed point number.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
- * This function converts the 32.32 fixed point number @fp to a
+ * This function converts the 32.32 fixed point number @p fp to a
* string. The string is stored in the buffer pointed by @p des and
* must be sufficiently large to contain the converted fixed point
* number. The returned string is terminated and has the following
* Global *
*============================================================================*/
+/**
+ * @internal
+ * @brief Initialize the eina counter internal structure.
+ *
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ *
+ * This function shuts down the counter module set up by
+ * eina_counter_init(). It is called by eina_init().
+ *
+ * This function sets up the error module of Eina and only on Windows,
+ * it initializes the high precision timer. It also registers, only on
+ * Windows, the error #EINA_ERROR_COUNTER_WINDOWS. 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_init()
+ */
+Eina_Bool
+eina_counter_init(void)
+{
+#ifdef _WIN32
+ EINA_ERROR_COUNTER_WINDOWS = eina_error_msg_static_register(EINA_ERROR_COUNTER_WINDOWS_STR);
+ if (!QueryPerformanceFrequency(&_eina_counter_frequency))
+ {
+ eina_error_set(EINA_ERROR_COUNTER_WINDOWS);
+ return EINA_FALSE;
+ }
+#endif /* _WIN2 */
+ return EINA_TRUE;
+}
+
+/**
+ * @internal
+ * @brief Shut down the counter module.
+ *
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ *
+ * This function shuts down the counter module set up by
+ * eina_counter_init(). It is called by eina_shutdown().
+ *
+ * @see eina_shutdown()
+ */
+Eina_Bool
+eina_counter_shutdown(void)
+{
+ return EINA_TRUE;
+}
+
/*============================================================================*
* API *
*============================================================================*/
*/
/**
- * @internal
- * @brief Initialize the eina counter internal structure.
- *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This function shuts down the counter module set up by
- * eina_counter_init(). It is called by eina_init().
- *
- * This function sets up the error module of Eina and only on Windows,
- * it initializes the high precision timer. It also registers, only on
- * Windows, the error #EINA_ERROR_COUNTER_WINDOWS. 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_init()
- */
-Eina_Bool
-eina_counter_init(void)
-{
-#ifdef _WIN32
- EINA_ERROR_COUNTER_WINDOWS = eina_error_msg_static_register(EINA_ERROR_COUNTER_WINDOWS_STR);
- if (!QueryPerformanceFrequency(&_eina_counter_frequency))
- {
- eina_error_set(EINA_ERROR_COUNTER_WINDOWS);
- return EINA_FALSE;
- }
-#endif /* _WIN2 */
- return EINA_TRUE;
-}
-
-/**
- * @internal
- * @brief Shut down the counter module.
- *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This function shuts down the counter module set up by
- * eina_counter_init(). It is called by eina_shutdown().
- *
- * @see eina_shutdown()
- */
-Eina_Bool
-eina_counter_shutdown(void)
-{
- return EINA_TRUE;
-}
-
-/**
* @brief Return a counter.
*
* @param name The name of the counter.
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Error_Group Error
- *
- * @brief These functions provide error management for projects.
- *
- * To use the error system Eina must be initialized with eina_init()
- * and later shut down with eina_shutdown(). Error codes are
- * registered with eina_error_msg_register() and converted from
- * identifier to original message string with eina_error_msg_get().
- *
- * Logging functions are not in eina_error anymore, see
- * eina_log_print() instead.
- *
- * @{
- */
-
-
/**
* @cond LOCAL
*/
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Error_Group Error
+ *
+ * @brief These functions provide error management for projects.
+ *
+ * To use the error system Eina must be initialized with eina_init()
+ * and later shut down with eina_shutdown(). Error codes are
+ * registered with eina_error_msg_register() and converted from
+ * identifier to original message string with eina_error_msg_get().
+ *
+ * Logging functions are not in eina_error anymore, see
+ * eina_log_print() instead.
+ *
+ * @{
+ */
+
/**
* @brief Register a new error type.
*
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Iterator_Group Iterator Functions
- *
- * @brief These functions manage iterators on containers.
- *
- * These functions allow to access elements of a container in a
- * generic way, without knowing which container is used (a bit like
- * iterators in the C++ STL). Iterators only allows sequential access
- * (that is, from an element to the next one). For random access, see
- * @ref Eina_Accessor_Group.
- *
- * An iterator is created from container data types, so no creation
- * function is available here. An iterator is deleted with
- * eina_iterator_free(). To get the data and iterate, use
- * eina_iterator_next(). To call a function on all the elements of a
- * container, use eina_iterator_foreach().
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the iterator module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Iterator_Group Iterator Functions
+ *
+ * @brief These functions manage iterators on containers.
+ *
+ * These functions allow to access elements of a container in a
+ * generic way, without knowing which container is used (a bit like
+ * iterators in the C++ STL). Iterators only allows sequential access
+ * (that is, from an element to the next one). For random access, see
+ * @ref Eina_Accessor_Group.
+ *
+ * An iterator is created from container data types, so no creation
+ * function is available here. An iterator is deleted with
+ * eina_iterator_free(). To get the data and iterate, use
+ * eina_iterator_next(). To call a function on all the elements of a
+ * container, use eina_iterator_foreach().
+ *
+ * @{
+ */
+
/**
* @brief Free an iterator.
*
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_List_Group List
- *
- * @brief These functions provide double linked list management.
- *
- * For more information, you can look at the @ref tutorial_list_page.
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the list module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_List_Group List
+ *
+ * @brief These functions provide double linked list management.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
+ */
+
/**
* @brief Append the given data to the given linked list.
*
* @brief Insert a new node into a sorted list.
*
* @param list The given linked list, @b must be sorted.
+ * @param func The function called for the sort.
* @param data The data to insert sorted.
* @return A list pointer.
*
* used in place of the one given to this function is
* returned. Otherwise, the old pointer is returned. See eina_error_get().
*
- * @note O(log2(n)) comparisons (calls to func) average/worst case
+ * @note O(log2(n)) comparisons (calls to @p func) average/worst case
* performance as it uses eina_list_search_sorted_near_list() and thus
* is bounded to that. As said in eina_list_search_sorted_near_list(),
* lists do not have O(1) access time, so walking to the correct node
}
}
-/**
- * @endcond
- */
+static inline int
+eina_log_domain_register_unlocked(const char *name, const char *color)
+{
+ Eina_Log_Domain_Level_Pending *pending = NULL;
+ int i;
+ for (i = 0; i < _log_domains_count; i++)
+ {
+ if (_log_domains[i].deleted)
+ {
+ // Found a flagged slot, free domain_str and replace slot
+ eina_log_domain_new(&_log_domains[i], name, color);
+ goto finish_register;
+ }
+ }
-/*============================================================================*
- * Global *
- *============================================================================*/
+ if (_log_domains_count >= _log_domains_allocated)
+ {
+ Eina_Log_Domain *tmp;
+ size_t size;
-/*============================================================================*
- * API *
- *============================================================================*/
+ if (!_log_domains)
+ // special case for init, eina itself will allocate a dozen of domains
+ size = 24;
+ else
+ // grow 8 buckets to minimize reallocs
+ size = _log_domains_allocated + 8;
-/**
- * @addtogroup Eina_Log_Group Log
- *
- * @brief These functions provide log management for projects.
- *
- * To use the log system Eina must be initialized with eina_init() and
- * later shut down with eina_shutdown(). The most generic way to print
- * logs is to use eina_log_print() but the helper macros
- * EINA_LOG_ERR(), EINA_LOG_INFO(), EINA_LOG_WARN() and EINA_LOG_DBG()
- * should be used instead.
- *
- * Here is a straightforward example:
- *
- * @code
- * #include <stdlib.h>
- * #include <stdio.h>
- *
- * #include <eina_log.h>
- *
- * void test_warn(void)
- * {
- * EINA_LOG_WARN("Here is a warning message");
- * }
- *
- * int main(void)
- * {
- * if (!eina_init())
- * {
- * printf("log during the initialization of Eina_Log module\n");
- * return EXIT_FAILURE;
- * }
- *
- * test_warn();
- *
- * eina_shutdown();
- *
- * return EXIT_SUCCESS;
- * }
- * @endcode
- *
- * Compile this code with the following command:
- *
- * @code
- * gcc -Wall -o test_Eina_Log test_eina.c `pkg-config --cflags --libs eina`
- * @endcode
- *
- * If Eina is compiled without debug mode, then executing the
- * resulting program displays nothing because the default log level
- * is #EINA_LOG_LEVEL_ERR and we want to display a warning
- * message, which level is strictly greater than the log level (see
- * eina_log_print() for more informations). Now execute the program
- * with:
- *
- * @code
- * EINA_LOG_LEVEL=2 ./test_eina_log
- * @endcode
- *
- * You should see a message displayed in the terminal.
- *
- * For more information, you can look at the @ref tutorial_log_page.
- *
- * @{
- */
+ tmp = realloc(_log_domains, sizeof(Eina_Log_Domain) * size);
+ if (tmp)
+ {
+ // Success!
+ _log_domains = tmp;
+ _log_domains_allocated = size;
+ }
+ else
+ return -1;
+ }
-/**
- * @cond LOCAL
- */
+ // Use an allocated slot
+ eina_log_domain_new(&_log_domains[i], name, color);
+ _log_domains_count++;
-EAPI int EINA_LOG_DOMAIN_GLOBAL = 0;
+finish_register:
+ EINA_INLIST_FOREACH(_glob_list, pending)
+ {
+ if (!fnmatch(pending->name, name, 0))
+ {
+ _log_domains[i].level = pending->level;
+ break;
+ }
+ }
+
+ EINA_INLIST_FOREACH(_pending_list, pending)
+ {
+ if (!strcmp(pending->name, name))
+ {
+ _log_domains[i].level = pending->level;
+ _pending_list = eina_inlist_remove(_pending_list, EINA_INLIST_GET(pending));
+ free(pending);
+ break;
+ }
+ }
+
+ // Check if level is still UNKNOWN, set it to global
+ if (_log_domains[i].level == EINA_LOG_LEVEL_UNKNOWN)
+ _log_domains[i].level = _log_level;
+
+ return i;
+}
/**
* @endcond
*/
+
+/*============================================================================*
+ * Global *
+ *============================================================================*/
+
/**
* @internal
* @brief Initialize the log module.
return EINA_TRUE;
}
-
#ifdef EFL_HAVE_PTHREAD
/**
#endif
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Log_Group Log
+ *
+ * @brief These functions provide log management for projects.
+ *
+ * To use the log system Eina must be initialized with eina_init() and
+ * later shut down with eina_shutdown(). The most generic way to print
+ * logs is to use eina_log_print() but the helper macros
+ * EINA_LOG_ERR(), EINA_LOG_INFO(), EINA_LOG_WARN() and EINA_LOG_DBG()
+ * should be used instead.
+ *
+ * Here is a straightforward example:
+ *
+ * @code
+ * #include <stdlib.h>
+ * #include <stdio.h>
+ *
+ * #include <eina_log.h>
+ *
+ * void test_warn(void)
+ * {
+ * EINA_LOG_WARN("Here is a warning message");
+ * }
+ *
+ * int main(void)
+ * {
+ * if (!eina_init())
+ * {
+ * printf("log during the initialization of Eina_Log module\n");
+ * return EXIT_FAILURE;
+ * }
+ *
+ * test_warn();
+ *
+ * eina_shutdown();
+ *
+ * return EXIT_SUCCESS;
+ * }
+ * @endcode
+ *
+ * Compile this code with the following command:
+ *
+ * @code
+ * gcc -Wall -o test_Eina_Log test_eina.c `pkg-config --cflags --libs eina`
+ * @endcode
+ *
+ * If Eina is compiled without debug mode, then executing the
+ * resulting program displays nothing because the default log level
+ * is #EINA_LOG_LEVEL_ERR and we want to display a warning
+ * message, which level is strictly greater than the log level (see
+ * eina_log_print() for more informations). Now execute the program
+ * with:
+ *
+ * @code
+ * EINA_LOG_LEVEL=2 ./test_eina_log
+ * @endcode
+ *
+ * You should see a message displayed in the terminal.
+ *
+ * For more information, you can look at the @ref tutorial_log_page.
+ *
+ * @{
+ */
+
+
+/**
+ * @cond LOCAL
+ */
+
+EAPI int EINA_LOG_DOMAIN_GLOBAL = 0;
+
+/**
+ * @endcond
+ */
+
/**
* Enable logging module to handle threads.
_log_level = level;
}
-static inline int
-eina_log_domain_register_unlocked(const char *name, const char *color)
-{
- Eina_Log_Domain_Level_Pending *pending = NULL;
- int i;
-
- for (i = 0; i < _log_domains_count; i++)
- {
- if (_log_domains[i].deleted)
- {
- // Found a flagged slot, free domain_str and replace slot
- eina_log_domain_new(&_log_domains[i], name, color);
- goto finish_register;
- }
- }
-
- if (_log_domains_count >= _log_domains_allocated)
- {
- Eina_Log_Domain *tmp;
- size_t size;
-
- if (!_log_domains)
- // special case for init, eina itself will allocate a dozen of domains
- size = 24;
- else
- // grow 8 buckets to minimize reallocs
- size = _log_domains_allocated + 8;
-
- tmp = realloc(_log_domains, sizeof(Eina_Log_Domain) * size);
-
- if (tmp)
- {
- // Success!
- _log_domains = tmp;
- _log_domains_allocated = size;
- }
- else
- return -1;
- }
-
- // Use an allocated slot
- eina_log_domain_new(&_log_domains[i], name, color);
- _log_domains_count++;
-
-finish_register:
- EINA_INLIST_FOREACH(_glob_list, pending)
- {
- if (!fnmatch(pending->name, name, 0))
- {
- _log_domains[i].level = pending->level;
- break;
- }
- }
-
- EINA_INLIST_FOREACH(_pending_list, pending)
- {
- if (!strcmp(pending->name, name))
- {
- _log_domains[i].level = pending->level;
- _pending_list = eina_inlist_remove(_pending_list, EINA_INLIST_GET(pending));
- free(pending);
- break;
- }
- }
-
- // Check if level is still UNKNOWN, set it to global
- if (_log_domains[i].level == EINA_LOG_LEVEL_UNKNOWN)
- _log_domains[i].level = _log_level;
-
- return i;
-}
-
/**
* @param name Domain name
* @param color Color of the domain name
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Magic_Group Magic
- *
- * @brief These functions provide magic checks management for projects.
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the magic string module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Magic_Group Magic
+ *
+ * @brief These functions provide magic checks management for projects.
+ *
+ * @{
+ */
+
/**
* @brief Return the string associated to the given magic identifier.
*
* @brief Set the string associated to the given magic identifier.
*
* @param magic The magic identifier.
- * @param The string associated to the identifier, must not be @c NULL.
+ * @param magic_name The string associated to the identifier, must not
+ * be @c NULL.
*
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
*
* @brief Set the string associated to the given magic identifier.
*
* @param magic The magic identifier.
- * @param The string associated to the identifier, must not be @c NULL,
- * it will not be duplcated, just referenced thus it must be live
- * during magic number usage.
+ * @param magic_name The string associated to the identifier, must not be
+ * @c NULL, it will not be duplcated, just referenced thus it must
+ * be live during magic number usage.
*
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
*
* @param m The magic identifer to check.
* @param req_m The requested magic identifier to check.
* @param file The file in which the magic check failed.
- * @param fcn The function in which the magic check failed.
+ * @param fnc The function in which the magic check failed.
* @param line The line at which the magic check failed.
*
* This function displays an error message if a magic check has
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Matrixsparse_Group Sparse Matrix
- *
- * @brief These functions provide matrix sparse management.
- *
- * For more information, you can look at the @ref tutorial_matrixsparse_page.
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the matrixsparse module.
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Matrixsparse_Group Sparse Matrix
+ *
+ * @brief These functions provide matrix sparse management.
+ *
+ * For more information, you can look at the @ref tutorial_matrixsparse_page.
+ *
+ * @{
+ */
+
/**
* @brief Create a new Sparse Matrix.
*
* Change cell value without freeing the possibly existing old value, using
* indexes.
*
- * @param cell the cell reference, must @b not be @c NULL.
+ * @param m the sparse matrix, must @b not be @c NULL.
* @param row the row number to set the value.
* @param col the column number to set the value.
* @param data new data to set.
* In contrast to eina_matrixsparse_data_idx_replace(), this function will
* call @c free_func() on existing value.
*
- * @param cell the cell reference, must @b not be @c NULL.
+ * @param m the sparse matrix, must @b not be @c NULL.
* @param row the row number to set the value.
* @param col the column number to set the value.
* @param data new data to set.
* Global *
*============================================================================*/
+/**
+ * @cond LOCAL
+ */
+
+EAPI Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE = 0;
+
+static const char EINA_ERROR_NOT_MEMPOOL_MODULE_STR[] = "Not a memory pool module.";
+
+/**
+ * @endcond
+ */
+
EAPI Eina_Bool
eina_mempool_register(Eina_Mempool_Backend *be)
{
eina_hash_del(_backends, be->name, be);
}
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Memory_Pool_Group Memory Pool
- *
- * @brief These functions provide memory pool management.
- *
- * @{
- */
-
-EAPI Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE = 0;
-
-static const char EINA_ERROR_NOT_MEMPOOL_MODULE_STR[] = "Not a memory pool module.";
-
Eina_Bool
eina_mempool_init(void)
{
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Memory_Pool_Group Memory Pool
+ *
+ * @brief These functions provide memory pool management.
+ *
+ * @{
+ */
+
EAPI Eina_Mempool *
eina_mempool_add(const char *name, const char *context, const char *options, ...)
{
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Module_Group Module
- *
- * @brief These functions provide module management.
- *
- * @{
- */
-
/**
* @cond LOCAL
*/
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Module_Group Module
+ *
+ * @brief These functions provide module management.
+ *
+ * @{
+ */
+
/**
* @brief Return a new module.
*
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
Eina_Bool
eina_rectangle_init(void)
{
return EINA_TRUE;
}
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @brief Create a new rectangle.
+ *
+ * @param x The X coordinate of the top left corner of the rectangle.
+ * @param y The Y coordinate of the top left corner of the rectangle.
+ * @param w The width of the rectangle.
+ * @param h The height of the rectangle.
+ * @return The new rectangle on success, @ NULL otherwise.
+ *
+ * This function creates a rectangle which top left corner has the
+ * coordinates (@p x, @p y), with height @p w and height @p h and adds
+ * it to the rectangles pool. No check is done on @p w and @p h. This
+ * function returns a new rectangle on success, @c NULL otherwhise.
+ */
EAPI Eina_Rectangle *
eina_rectangle_new(int x, int y, int w, int h)
{
return rect;
}
+/**
+ * @brief Free the given rectangle.
+ *
+ * @param rect The rectangle to free.
+ *
+ * This function removes @p rect from the rectangles pool.
+ */
EAPI void
eina_rectangle_free(Eina_Rectangle *rect)
{
MAGIC_FREE(pool);
}
+/**
+ * @brief Return the number of rectangles in the given pool.
+ *
+ * @param pool The pool.
+ * @return The number of rectangles in the pool.
+ *
+ * This function returns the number of rectangles in @p pool.
+ */
EAPI int
eina_rectangle_pool_count(Eina_Rectangle_Pool *pool)
{
}
}
+/**
+ * @brief Return the pool of the given rectangle.
+ *
+ * @param rect The rectangle.
+ * @return The pool of the given rectangle.
+ *
+ * This function returns the pool in which @p rect is. If @p rect is
+ * @c NULL, @c NULL is returned.
+ */
EAPI Eina_Rectangle_Pool *
eina_rectangle_pool_get(Eina_Rectangle *rect)
{
return era->pool;
}
+/**
+ * @brief Set the data to the given pool.
+ *
+ * @param pool The pool.
+ * @param data The data to set.
+ *
+ * This function sets @p data to @p pool. If @p pool is @c NULL, this
+ * function does nothing.
+ */
EAPI void
eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data)
{
pool->data = (void*) data;
}
+/**
+ * @brief Get the data from the given pool.
+ *
+ * @param pool The pool.
+ * @return The returned data.
+ *
+ * This function gets the data from @p pool set by
+ * eina_rectangle_pool_data_set(). If @p pool is @c NULL, this
+ * function returns @c NULL.
+ */
EAPI void *
eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool)
{
return pool->data;
}
+/**
+ * @brief Return the width and height of the given pool.
+ *
+ * @param pool The pool.
+ * @param w The returned width.
+ * @param h The returned height.
+ * @return #EINA_TRUE on sucess, #EINA_FALSE otherwise.
+ *
+ * This function returns the width and height of @p pool and store
+ * them in respectively @p w and @p h if they are not @c NULL. If
+ * @p pool is @c NULL, #EINA_FALSE is returned. Otherwise #EINA_TRUE is
+ * returned.
+ */
EAPI Eina_Bool
eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h)
{
* if not, see <http://www.gnu.org/licenses/>.
*/
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+
+#include "eina_error.h"
+#include "eina_private.h"
+#include "eina_safety_checks.h"
+
+/*============================================================================*
+ * Local *
+ *============================================================================*/
+
+/*============================================================================*
+ * Global *
+ *============================================================================*/
+
+/**
+ * @internal
+ * @brief Shut down the safety checks module.
+ *
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ *
+ * This function shuts down the error module set up by
+ * eina_safety_checks_init(). It is called by eina_shutdown().
+ *
+ * @see eina_shutdown()
+ */
+Eina_Bool
+eina_safety_checks_shutdown(void)
+{
+ return EINA_TRUE;
+}
+
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
/**
* @addtogroup Eina_Safety_Checks_Group Safety Checks
*
* @{
*/
-#ifdef HAVE_CONFIG_H
-# include "config.h"
-#endif
-
-#include "eina_error.h"
-#include "eina_private.h"
-#include "eina_safety_checks.h"
-
/**
* @cond LOCAL
*/
}
/**
- * @internal
- * @brief Shut down the safety checks module.
- *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This function shuts down the error module set up by
- * eina_safety_checks_init(). It is called by eina_shutdown().
- *
- * @see eina_shutdown()
- */
-Eina_Bool
-eina_safety_checks_shutdown(void)
-{
- return EINA_TRUE;
-}
-
-/**
* @}
*/
* Global *
*============================================================================*/
-/*============================================================================*
- * API *
- *============================================================================*/
-
-/**
- * @addtogroup Eina_Stringshare_Group Stringshare
- *
- * These functions allow you to store one copy of a string, and use it
- * throughout your program.
- *
- * This is a method to reduce the number of duplicated strings kept in
- * memory. It's pretty common for the same strings to be dynamically
- * allocated repeatedly between applications and libraries, especially in
- * circumstances where you could have multiple copies of a structure that
- * allocates the string. So rather than duplicating and freeing these
- * strings, you request a read-only pointer to an existing string and
- * only incur the overhead of a hash lookup.
- *
- * It sounds like micro-optimizing, but profiling has shown this can have
- * a significant impact as you scale the number of copies up. It improves
- * string creation/destruction speed, reduces memory use and decreases
- * memory fragmentation, so a win all-around.
- *
- * For more information, you can look at the @ref tutorial_stringshare_page.
- *
- * @{
- */
-
/**
* @internal
* @brief Initialize the stringshare module.
#endif
+/*============================================================================*
+ * API *
+ *============================================================================*/
+
+/**
+ * @addtogroup Eina_Stringshare_Group Stringshare
+ *
+ * These functions allow you to store one copy of a string, and use it
+ * throughout your program.
+ *
+ * This is a method to reduce the number of duplicated strings kept in
+ * memory. It's pretty common for the same strings to be dynamically
+ * allocated repeatedly between applications and libraries, especially in
+ * circumstances where you could have multiple copies of a structure that
+ * allocates the string. So rather than duplicating and freeing these
+ * strings, you request a read-only pointer to an existing string and
+ * only incur the overhead of a hash lookup.
+ *
+ * It sounds like micro-optimizing, but profiling has shown this can have
+ * a significant impact as you scale the number of copies up. It improves
+ * string creation/destruction speed, reduces memory use and decreases
+ * memory fragmentation, so a win all-around.
+ *
+ * For more information, you can look at the @ref tutorial_stringshare_page.
+ *
+ * @{
+ */
+
/**
* @brief Retrieve an instance of a string for use in a program.
*
* it is added to the strings to be searched and a duplicated string
* of @p str is returned.
*
- * The string @a str must be NULL terminated ('\0') and its full
+ * The string @p str must be NULL terminated ('@\0') and its full
* length will be used. To use part of the string or non-null
* terminated, use eina_stringshare_add_length() instead.
*
/**
* Increment references of the given shared string.
*
+ * @param str The shared string.
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
* This is similar to eina_stringshare_add(), but it's faster since it will
* avoid lookups if possible, but on the down side it requires the parameter
* to be shared before, in other words, it must be the return of a previous
/*============================================================================*
* Global *
*============================================================================*/
+
/*============================================================================*
* API *
*============================================================================*/
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
EAPI Eina_Tiler *eina_tiler_new(int w, int h)
{
Eina_Tiler *t;
_splitter_new(t);
return t;
}
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
EAPI void eina_tiler_free(Eina_Tiler *t)
{
EINA_MAGIC_CHECK_TILER(t);
_splitter_del(t);
free(t);
}
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h)
{
EINA_MAGIC_CHECK_TILER(t);
t->tile.h = h;
_splitter_tile_size_set(t, w, h);
}
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle *r)
{
Eina_Rectangle tmp;
return EINA_FALSE;
return _splitter_rect_add(t, &tmp);
}
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle *r)
{
Eina_Rectangle tmp;
return;
_splitter_rect_del(t, &tmp);
}
-/**
- * To be documented
- * FIXME: To be fixed
- */
+
EAPI void eina_tiler_clear(Eina_Tiler *t)
{
EINA_MAGIC_CHECK_TILER(t);