forked from enlightenment/efl
efl/eina: General cleanup of Eina documentation
Summary: I've combed through the Eina source files and made enhancements to the documentation, including: - Document the undocumented - Fixed some errors in Doxygen markup - Moved some function documentation from implementation (.c or .x) to definition (.h) - Edited some of the entries to improve clarity Test Plan: Reviewers Reviewers: cedric Reviewed By: cedric CC: cedric Differential Revision: https://phab.enlightenment.org/D639
This commit is contained in:
parent
b87cbf8fe4
commit
cf5192025f
|
@ -157,6 +157,7 @@ typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it);
|
||||||
* Type to provide random access to data structures.
|
* Type to provide random access to data structures.
|
||||||
*
|
*
|
||||||
* If creating an accessor remember to set the type using @ref EINA_MAGIC_SET.
|
* If creating an accessor remember to set the type using @ref EINA_MAGIC_SET.
|
||||||
|
*
|
||||||
*/
|
*/
|
||||||
struct _Eina_Accessor
|
struct _Eina_Accessor
|
||||||
{
|
{
|
||||||
|
|
|
@ -39,6 +39,10 @@
|
||||||
# ifdef __cplusplus
|
# ifdef __cplusplus
|
||||||
extern "C"
|
extern "C"
|
||||||
# endif
|
# endif
|
||||||
|
/**
|
||||||
|
* Allocates memory in the stack frame of the caller, so it's automatically
|
||||||
|
* freed when the caller returns. See alloca(3) for detials.
|
||||||
|
*/
|
||||||
void *alloca (long);
|
void *alloca (long);
|
||||||
# endif
|
# endif
|
||||||
#endif
|
#endif
|
||||||
|
|
|
@ -49,13 +49,13 @@
|
||||||
* Before we can start using any array function we need to initialize eina:
|
* Before we can start using any array function we need to initialize eina:
|
||||||
* @until eina_init
|
* @until eina_init
|
||||||
*
|
*
|
||||||
* So now to actually creating our array. The only interesting thing here is the
|
* So now to actually create our array. The only interesting thing here is the
|
||||||
* argument given to the eina_array_new() function, this argument sets how fast
|
* argument given to the eina_array_new() function. This argument sets how fast
|
||||||
* the array grows.
|
* the array grows.
|
||||||
* @until array_new
|
* @until array_new
|
||||||
*
|
*
|
||||||
* If you know before hand how big the array will need to be you should set the
|
* If you know before hand how big the array will need to be you should set the
|
||||||
* step to that. In our case we can set it to the number of string we have and
|
* step to that. In our case we can set it to the number of strings we have and
|
||||||
* since we didn't do that in the eina_array_new() we can do it now:
|
* since we didn't do that in the eina_array_new() we can do it now:
|
||||||
* @until array_step_set
|
* @until array_step_set
|
||||||
*
|
*
|
||||||
|
@ -82,8 +82,8 @@
|
||||||
* And finally shutdown eina and exit:
|
* And finally shutdown eina and exit:
|
||||||
* @until }
|
* @until }
|
||||||
*
|
*
|
||||||
* The full source code can be found on the examples folder
|
* The full source code can be found in the examples folder
|
||||||
* on the @ref eina_array_01_c "eina_array_01.c" file.
|
* in the @ref eina_array_01_c "eina_array_01.c" file.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -102,7 +102,7 @@
|
||||||
* @until Eina.h
|
* @until Eina.h
|
||||||
*
|
*
|
||||||
* This the callback we are going to use to decide which strings stay on the
|
* This the callback we are going to use to decide which strings stay on the
|
||||||
* array and which will be removed, we use something simple, but this can be as
|
* array and which will be removed. We use something simple, but this can be as
|
||||||
* complex as you like:
|
* complex as you like:
|
||||||
* @until }
|
* @until }
|
||||||
*
|
*
|
||||||
|
@ -127,8 +127,8 @@
|
||||||
* Since this time we didn't use strdup we don't need to free each string:
|
* Since this time we didn't use strdup we don't need to free each string:
|
||||||
* @until }
|
* @until }
|
||||||
*
|
*
|
||||||
* The full source code can be found on the examples folder
|
* The full source code can be found in the examples folder
|
||||||
* on the @ref eina_array_02_c "eina_array_02.c" file.
|
* in the @ref eina_array_02_c "eina_array_02.c" file.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -146,7 +146,7 @@
|
||||||
* The Array data type in Eina is designed to have very fast access to
|
* The Array data type in Eina is designed to have very fast access to
|
||||||
* its data (compared to the Eina @ref Eina_List_Group). On the other hand,
|
* 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 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
|
* data at any position, the Eina @ref Eina_List_Group is the correct container
|
||||||
* to use.
|
* to use.
|
||||||
*
|
*
|
||||||
* To use the array data type, eina_init() must be called before any
|
* To use the array data type, eina_init() must be called before any
|
||||||
|
@ -155,11 +155,11 @@
|
||||||
*
|
*
|
||||||
* An array must be created with eina_array_new(). It allocates all
|
* An array must be created with eina_array_new(). It allocates all
|
||||||
* the necessary data for an array. When not needed anymore, an array
|
* the necessary data for an array. When not needed anymore, an array
|
||||||
* is freed with eina_array_free(). This function does not free any
|
* is freed with eina_array_free(). This frees the memory used by the Eina_Array
|
||||||
* allocated memory used to store the data of each element. For that,
|
* itself, but does not free any memory used to store the data of each element.
|
||||||
* just iterate over the array to free them. A convenient way to do
|
* To free that memory you must iterate over the array and free each data element
|
||||||
* that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given
|
* individually. A convenient way to do that is by using #EINA_ARRAY_ITER_NEXT.
|
||||||
* in the description of this macro.
|
* An example of that pattern is given in the description of @ref EINA_ARRAY_ITER_NEXT.
|
||||||
*
|
*
|
||||||
* @warning Functions do not check if the used array is valid or not. It's up to
|
* @warning 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
|
* the user to be sure of that. It is designed like that for performance
|
||||||
|
@ -176,16 +176,15 @@
|
||||||
* element to a full array it grows and that when you remove an element from an
|
* element to a full array it grows and that when you remove an element from an
|
||||||
* array it @b may shrink.
|
* array it @b may shrink.
|
||||||
*
|
*
|
||||||
* When the array needs to grow it allocates memory not just for the element
|
* Allocating memory is expensive, so when the array needs to grow it allocates
|
||||||
* currently being added since that would mean allocating memory(which is
|
* enough memory to hold @p step additonal elements, not just the element
|
||||||
* computationally expensive) often, instead it grows to be able to hold @p step
|
* currently being added. Similarly if you remove elements, it won't free space
|
||||||
* more elements. Similarly if you remove elements in such a way that that the
|
* until you have removed @p step elements.
|
||||||
* array is left holding its capacity - @p step elements it will shrink.
|
|
||||||
*
|
*
|
||||||
* The following image illustrates how an Eina_Array grows:
|
* The following image illustrates how an Eina_Array grows:
|
||||||
*
|
*
|
||||||
* @image html eina_array-growth.png
|
* @image html eina_array-growth.png
|
||||||
* @image latex eina_array-growth.eps width=\textwidth
|
* @image latex eina_array-growth.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* Eina_Array only stores pointers but it can store data of any type in the form
|
* Eina_Array only stores pointers but it can store data of any type in the form
|
||||||
* of void pointers.
|
* of void pointers.
|
||||||
|
@ -234,10 +233,10 @@ struct _Eina_Array
|
||||||
#define EINA_ARRAY_VERSION 1
|
#define EINA_ARRAY_VERSION 1
|
||||||
int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */
|
int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */
|
||||||
|
|
||||||
void **data; /**< Pointer to a vector of pointer to payload */
|
void **data; /**< Pointer to a vector of pointer to payload */
|
||||||
unsigned int total; /**< Total number of slots in the vector */
|
unsigned int total; /**< Number of allocated slots in the vector */
|
||||||
unsigned int count; /**< Number of active slots in the vector */
|
unsigned int count; /**< Number of slots in the vector that actually point to data */
|
||||||
unsigned int step; /**< How much must we grow the vector when it is full */
|
unsigned int step; /**< Number of slots to grow or shrink the vector */
|
||||||
EINA_MAGIC
|
EINA_MAGIC
|
||||||
};
|
};
|
||||||
|
|
||||||
|
@ -264,8 +263,8 @@ EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_
|
||||||
*
|
*
|
||||||
* This function frees @p array. It calls first eina_array_flush() then
|
* This function frees @p array. It calls first eina_array_flush() then
|
||||||
* free the memory of the pointer. It does not free the memory
|
* free the memory of the pointer. It does not free the memory
|
||||||
* allocated for the elements of @p array. To free them,
|
* allocated for the elements of @p array. To free them, walk the array with
|
||||||
* use #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check
|
* #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check
|
||||||
* of @p array.
|
* of @p array.
|
||||||
*/
|
*/
|
||||||
EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1);
|
EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1);
|
||||||
|
@ -329,9 +328,48 @@ EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1);
|
||||||
EAPI Eina_Bool eina_array_remove(Eina_Array * array,
|
EAPI Eina_Bool eina_array_remove(Eina_Array * array,
|
||||||
Eina_Bool (*keep)(void *data, void *gdata),
|
Eina_Bool (*keep)(void *data, void *gdata),
|
||||||
void *gdata) EINA_ARG_NONNULL(1, 2);
|
void *gdata) EINA_ARG_NONNULL(1, 2);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Append a data to an array.
|
||||||
|
*
|
||||||
|
* @param array The array.
|
||||||
|
* @param data The data to add.
|
||||||
|
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
|
||||||
|
*
|
||||||
|
* This function appends @p data to @p array. For performance
|
||||||
|
* reasons, there is no check of @p array. If it is @c NULL or
|
||||||
|
* invalid, the program may crash. If @p data is @c NULL, or if an
|
||||||
|
* allocation is necessary and fails, #EINA_FALSE is returned
|
||||||
|
* Otherwise, #EINA_TRUE is returned.
|
||||||
|
*/
|
||||||
static inline Eina_Bool eina_array_push(Eina_Array *array,
|
static inline Eina_Bool eina_array_push(Eina_Array *array,
|
||||||
const void *data) EINA_ARG_NONNULL(1, 2);
|
const void *data) EINA_ARG_NONNULL(1, 2);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Remove the last data of an array.
|
||||||
|
*
|
||||||
|
* @param array The array.
|
||||||
|
* @return The retrieved data.
|
||||||
|
*
|
||||||
|
* This function removes the last data of @p array, decreases the count
|
||||||
|
* of @p array and returns the data. For performance reasons, there
|
||||||
|
* is no check of @p array. If it is @c NULL or invalid, the program
|
||||||
|
* may crash. If the count member is less or equal than 0, @c NULL is
|
||||||
|
* returned.
|
||||||
|
*/
|
||||||
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
|
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Return the data at a given position in an array.
|
||||||
|
*
|
||||||
|
* @param array The array.
|
||||||
|
* @param idx The potition of the data to retrieve.
|
||||||
|
* @return The retrieved data.
|
||||||
|
*
|
||||||
|
* This function returns the data at the position @p idx in @p
|
||||||
|
* array. For performance reasons, there is no check of @p array or @p
|
||||||
|
* idx. If it is @c NULL or invalid, the program may crash.
|
||||||
|
*/
|
||||||
static inline void *eina_array_data_get(const Eina_Array *array,
|
static inline void *eina_array_data_get(const Eina_Array *array,
|
||||||
unsigned int idx) EINA_ARG_NONNULL(1);
|
unsigned int idx) EINA_ARG_NONNULL(1);
|
||||||
/**
|
/**
|
||||||
|
@ -350,11 +388,34 @@ static inline void *eina_array_data_get(const Eina_Array *array,
|
||||||
static inline void eina_array_data_set(const Eina_Array *array,
|
static inline void eina_array_data_set(const Eina_Array *array,
|
||||||
unsigned int idx,
|
unsigned int idx,
|
||||||
const void *data) EINA_ARG_NONNULL(1);
|
const void *data) EINA_ARG_NONNULL(1);
|
||||||
|
/**
|
||||||
|
* @brief Return the number of elements in an array.
|
||||||
|
*
|
||||||
|
* @param array The array.
|
||||||
|
* @return The number of elements.
|
||||||
|
*
|
||||||
|
* This function returns the number of elements in @p array (array->count). For
|
||||||
|
* performance reasons, there is no check of @p array. If it is
|
||||||
|
* @c NULL or invalid, the program may crash.
|
||||||
|
*
|
||||||
|
* @deprecated use eina_array_count()
|
||||||
|
*/
|
||||||
static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Return the number of elements in an array.
|
||||||
|
*
|
||||||
|
* @param array The array.
|
||||||
|
* @return The number of elements.
|
||||||
|
*
|
||||||
|
* This function returns the number of elements in @p array (array->count). For
|
||||||
|
* performance reasons, there is no check of @p array. If it is
|
||||||
|
* @c NULL or invalid, the program may crash.
|
||||||
|
*/
|
||||||
static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Returned a new iterator associated to an array.
|
* @brief Get a new iterator associated to an array.
|
||||||
*
|
*
|
||||||
* @param array The array.
|
* @param array The array.
|
||||||
* @return A new iterator.
|
* @return A new iterator.
|
||||||
|
@ -362,12 +423,12 @@ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NO
|
||||||
* This function returns a newly allocated iterator associated to
|
* This function returns a newly allocated iterator associated to
|
||||||
* @p array. If @p array is @c NULL or the count member of @p array is
|
* @p array. If @p array is @c NULL or the count member of @p array is
|
||||||
* less or equal than 0, this function returns @c NULL. If the memory can
|
* less or equal than 0, this function returns @c NULL. If the memory can
|
||||||
* not be allocated, NULL is returned. Otherwise, a valid iterator is returned.
|
* not be allocated, @c NULL is returned. Otherwise, a valid iterator is returned.
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Returned a new accessor associated to an array.
|
* @brief Get a new accessor associated to an array.
|
||||||
*
|
*
|
||||||
* @param array The array.
|
* @param array The array.
|
||||||
* @return A new accessor.
|
* @return A new accessor.
|
||||||
|
@ -375,7 +436,7 @@ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA
|
||||||
* This function returns a newly allocated accessor associated to
|
* This function returns a newly allocated accessor associated to
|
||||||
* @p array. If @p array is @c NULL or the count member of @p array is
|
* @p array. If @p array is @c NULL or the count member of @p array is
|
||||||
* less or equal than 0, this function returns @c NULL. If the memory can
|
* less or equal than 0, this function returns @c NULL. If the memory can
|
||||||
* not be allocated, @c NULL is returned Otherwise, a valid accessor is
|
* not be allocated, @c NULL is returned. Otherwise, a valid accessor is
|
||||||
* returned.
|
* returned.
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||||
|
@ -387,9 +448,10 @@ EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA
|
||||||
* @param fdata The user data to pass to the callback.
|
* @param fdata The user data to pass to the callback.
|
||||||
* @return #EINA_TRUE if it successfully iterate all items of the array.
|
* @return #EINA_TRUE if it successfully iterate all items of the array.
|
||||||
*
|
*
|
||||||
* This function provide a safe way to iterate over an array. @p cb should
|
* This function provides a safe way to iterate over an array. @p cb should
|
||||||
* return #EINA_TRUE as long as you want the function to continue iterating,
|
* return #EINA_TRUE as long as you want the function to continue iterating.
|
||||||
* by returning #EINA_FALSE it will stop and return #EINA_FALSE as a result.
|
* If @p cb returns #EINA_FALSE, iterations will stop and the function will also
|
||||||
|
* return #EINA_FALSE.
|
||||||
*/
|
*/
|
||||||
static inline Eina_Bool eina_array_foreach(Eina_Array *array,
|
static inline Eina_Bool eina_array_foreach(Eina_Array *array,
|
||||||
Eina_Each_Cb cb,
|
Eina_Each_Cb cb,
|
||||||
|
|
|
@ -133,7 +133,7 @@ EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *
|
||||||
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
|
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
|
||||||
*
|
*
|
||||||
* This function appends @p data to @p buf. @p data must be allocated and
|
* This function appends @p data to @p buf. @p data must be allocated and
|
||||||
* different from @NULL. It is slightly faster than eina_binbuf_append() as
|
* different from @c NULL. It is slightly faster than eina_binbuf_append() as
|
||||||
* it does not compute the size of @p str. If @p buf can't append it,
|
* it does not compute the size of @p str. If @p buf can't append it,
|
||||||
* #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
|
* #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
|
||||||
*
|
*
|
||||||
|
|
|
@ -111,13 +111,14 @@ typedef struct _Eina_Clist Eina_Clist;
|
||||||
/**
|
/**
|
||||||
* @struct _Eina_Clist
|
* @struct _Eina_Clist
|
||||||
* Compact list type
|
* Compact list type
|
||||||
|
*
|
||||||
* @note This structure is used as both the list head and the list entry.
|
* @note This structure is used as both the list head and the list entry.
|
||||||
* @since 1.1.0
|
* @since 1.1.0
|
||||||
*/
|
*/
|
||||||
struct _Eina_Clist
|
struct _Eina_Clist
|
||||||
{
|
{
|
||||||
Eina_Clist *next;
|
Eina_Clist *next; /**< The next entry in the list */
|
||||||
Eina_Clist *prev;
|
Eina_Clist *prev; /**< The previous entry in the list */
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -191,7 +192,7 @@ static inline void eina_clist_element_init(Eina_Clist *elem);
|
||||||
* Check if an element is in a list or not.
|
* Check if an element is in a list or not.
|
||||||
*
|
*
|
||||||
* @param elem An element
|
* @param elem An element
|
||||||
*
|
* @return TRUE if the element is in a list, else FALSE.
|
||||||
* @pre Either eina_clist_element_init() has been called on @a elem,
|
* @pre Either eina_clist_element_init() has been called on @a elem,
|
||||||
* it has been added to a list or remove from a list.
|
* it has been added to a list or remove from a list.
|
||||||
* @since 1.1.0
|
* @since 1.1.0
|
||||||
|
|
|
@ -158,9 +158,9 @@
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND;
|
EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/
|
||||||
EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND;
|
EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/
|
||||||
EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH;
|
EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Convert an integer number to a string in decimal base.
|
* @brief Convert an integer number to a string in decimal base.
|
||||||
|
|
|
@ -73,6 +73,7 @@ EAPI void eina_cow_del(Eina_Cow *cow);
|
||||||
/**
|
/**
|
||||||
* @brief Return an initialized pointer from the pool.
|
* @brief Return an initialized pointer from the pool.
|
||||||
* @param cow The pool to take things from.
|
* @param cow The pool to take things from.
|
||||||
|
* @return A pointer to the new pool instance
|
||||||
*/
|
*/
|
||||||
EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
|
EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
|
@ -100,6 +101,7 @@ EAPI void *eina_cow_write(Eina_Cow *cow,
|
||||||
* @param cow The pool the pointer come from.
|
* @param cow The pool the pointer come from.
|
||||||
* @param dst The read only version of the pointer.
|
* @param dst The read only version of the pointer.
|
||||||
* @param data The pointer to which data was written to.
|
* @param data The pointer to which data was written to.
|
||||||
|
* @param needed_gc Does this pool need to be garbage collected?
|
||||||
*
|
*
|
||||||
* NOTE: this function is not thread safe, be careful.
|
* NOTE: this function is not thread safe, be careful.
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -99,8 +99,8 @@ typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info;
|
||||||
typedef struct _Eina_Stat Eina_Stat;
|
typedef struct _Eina_Stat Eina_Stat;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @typedef Eina_File_Lines
|
* @typedef Eina_File_Line
|
||||||
* A typedef to #_Eina_File_Lines.
|
* A typedef to #_Eina_File_Line.
|
||||||
*/
|
*/
|
||||||
typedef struct _Eina_File_Line Eina_File_Line;
|
typedef struct _Eina_File_Line Eina_File_Line;
|
||||||
|
|
||||||
|
@ -108,7 +108,7 @@ typedef struct _Eina_File_Line Eina_File_Line;
|
||||||
* @typedef Eina_File_Dir_List_Cb
|
* @typedef Eina_File_Dir_List_Cb
|
||||||
* Type for a callback to be called when iterating over the files of a
|
* Type for a callback to be called when iterating over the files of a
|
||||||
* directory.
|
* directory.
|
||||||
* @param The file name EXCLUDING the path
|
* @param name The file name EXCLUDING the path
|
||||||
* @param path The path passed to eina_file_dir_list()
|
* @param path The path passed to eina_file_dir_list()
|
||||||
* @param data The data passed to eina_file_dir_list()
|
* @param data The data passed to eina_file_dir_list()
|
||||||
*/
|
*/
|
||||||
|
@ -130,7 +130,12 @@ typedef enum {
|
||||||
EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */
|
EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */
|
||||||
} Eina_File_Type;
|
} Eina_File_Type;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_File
|
||||||
|
* A file handle.
|
||||||
|
*/
|
||||||
typedef struct _Eina_File Eina_File;
|
typedef struct _Eina_File Eina_File;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @typedef Eina_File_Populate
|
* @typedef Eina_File_Populate
|
||||||
* File access type used in Eina_File_Direct_info.
|
* File access type used in Eina_File_Direct_info.
|
||||||
|
@ -145,12 +150,12 @@ typedef enum {
|
||||||
} Eina_File_Populate;
|
} Eina_File_Populate;
|
||||||
|
|
||||||
/* Why do this? Well PATH_MAX may vary from when eina itself is compiled
|
/* Why do this? Well PATH_MAX may vary from when eina itself is compiled
|
||||||
* to when the app using eina is compiled. exposing the path buffer below
|
* to when the app using eina is compiled. Exposing the path buffer below
|
||||||
* can't safely and portably vary based on how/when you compile. it should
|
* can't safely and portably vary based on how/when you compile. It should
|
||||||
* always be the same for both eina inside AND for apps outside that use eina
|
* always be the same for both eina inside AND for apps outside that use eina
|
||||||
* so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with
|
* so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with
|
||||||
* windows i think being 260), so 8192 should cover almost all cases. there
|
* windows i think being 260), so 8192 should cover almost all cases. There
|
||||||
* is a possibility that PATH_MAX could be more than 8192. if anyone spots
|
* is a possibility that PATH_MAX could be more than 8192. If anyone spots
|
||||||
* a path_max that is bigger - let us know, but, for now we will assume
|
* a path_max that is bigger - let us know, but, for now we will assume
|
||||||
* it never happens */
|
* it never happens */
|
||||||
/**
|
/**
|
||||||
|
@ -164,36 +169,36 @@ typedef enum {
|
||||||
*/
|
*/
|
||||||
struct _Eina_File_Direct_Info
|
struct _Eina_File_Direct_Info
|
||||||
{
|
{
|
||||||
size_t path_length; /**< size of the whole path */
|
size_t path_length; /**< size of the whole path */
|
||||||
size_t name_length; /**< size of the filename/basename component */
|
size_t name_length; /**< size of the filename/basename component */
|
||||||
size_t name_start; /**< where the filename/basename component starts */
|
size_t name_start; /**< where the filename/basename component starts */
|
||||||
Eina_File_Type type; /**< file type */
|
Eina_File_Type type; /**< file type */
|
||||||
char path[EINA_PATH_MAX]; /**< the path */
|
char path[EINA_PATH_MAX]; /**< the path */
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @struct _Eina_Stat
|
* @struct _Eina_Stat
|
||||||
* A structure to store informations of a path.
|
* A structure to store some file statistics.
|
||||||
* @since 1.2
|
* @since 1.2
|
||||||
*/
|
*/
|
||||||
struct _Eina_Stat
|
struct _Eina_Stat
|
||||||
{
|
{
|
||||||
unsigned long int dev;
|
unsigned long int dev; /**< The device where this file is located */
|
||||||
unsigned long int ino;
|
unsigned long int ino; /**< The inode */
|
||||||
unsigned int mode;
|
unsigned int mode; /**< The mode */
|
||||||
unsigned int nlink;
|
unsigned int nlink; /**< The link number */
|
||||||
unsigned int uid;
|
unsigned int uid; /**< The owner user id */
|
||||||
unsigned int gid;
|
unsigned int gid; /**< The owner group id */
|
||||||
unsigned long int rdev;
|
unsigned long int rdev; /**< The remote device */
|
||||||
unsigned long int size;
|
unsigned long int size; /**< The file size in bytes */
|
||||||
unsigned long int blksize;
|
unsigned long int blksize; /**< The block size in bytes */
|
||||||
unsigned long int blocks;
|
unsigned long int blocks; /**< The number of blocks allocated */
|
||||||
unsigned long int atime;
|
unsigned long int atime; /**< The timestamp when the file was last accessed */
|
||||||
unsigned long int atimensec;
|
unsigned long int atimensec; /**< The nano version of the timestamp when the file was last accessed */
|
||||||
unsigned long int mtime;
|
unsigned long int mtime; /**< The timestamp when the file was last modified */
|
||||||
unsigned long int mtimensec;
|
unsigned long int mtimensec; /**< The nano version of the timestamp when the file was modified */
|
||||||
unsigned long int ctime;
|
unsigned long int ctime; /**< The timestamp when the file was created */
|
||||||
unsigned long int ctimensec;
|
unsigned long int ctimensec; /**< The nano version of the timestamp when the file was created */
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -203,10 +208,10 @@ struct _Eina_Stat
|
||||||
*/
|
*/
|
||||||
struct _Eina_File_Line
|
struct _Eina_File_Line
|
||||||
{
|
{
|
||||||
const char *start;
|
const char *start; /**< The start of the line */
|
||||||
const char *end;
|
const char *end; /**< The end of the line */
|
||||||
unsigned int index;
|
unsigned int index; /**< The line number */
|
||||||
unsigned long long length;
|
unsigned long long length; /**< The number of characters in the line */
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -462,7 +467,7 @@ EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNU
|
||||||
/**
|
/**
|
||||||
* @brief Create a virtual file from a memory pointer.
|
* @brief Create a virtual file from a memory pointer.
|
||||||
*
|
*
|
||||||
* @param virtual_name A virtual name for Eina_File, if #NULL, a generated one will be given
|
* @param virtual_name A virtual name for Eina_File, if @c NULL, a generated one will be given
|
||||||
* @param data The memory pointer to take data from
|
* @param data The memory pointer to take data from
|
||||||
* @param length The length of the data in memory
|
* @param length The length of the data in memory
|
||||||
* @param copy #EINA_TRUE if the data must be copied
|
* @param copy #EINA_TRUE if the data must be copied
|
||||||
|
@ -618,6 +623,7 @@ EAPI void eina_file_map_free(Eina_File *file, void *map);
|
||||||
* @brief Ask the OS to populate or otherwise pages of memory in file mapping
|
* @brief Ask the OS to populate or otherwise pages of memory in file mapping
|
||||||
*
|
*
|
||||||
* @param file The file handle from which the map comes
|
* @param file The file handle from which the map comes
|
||||||
|
* @param rule The rule to apply to the mapped memory
|
||||||
* @param map Memory that was mapped inside of which the memory range is
|
* @param map Memory that was mapped inside of which the memory range is
|
||||||
* @param offset The offset in bytes from the start of the map address
|
* @param offset The offset in bytes from the start of the map address
|
||||||
* @param length The length in bytes of the memory region to populate
|
* @param length The length in bytes of the memory region to populate
|
||||||
|
@ -635,7 +641,7 @@ eina_file_map_populate(Eina_File *file, Eina_File_Populate rule, const void *map
|
||||||
/**
|
/**
|
||||||
* @brief Map line by line in memory efficiently with an Eina_Iterator
|
* @brief Map line by line in memory efficiently with an Eina_Iterator
|
||||||
* @param file The file to run over
|
* @param file The file to run over
|
||||||
* @return an Eina_Iterator that will produce @typedef Eina_File_Lines.
|
* @return an Eina_Iterator that will produce @ref Eina_File_Line.
|
||||||
*
|
*
|
||||||
* This function return an iterator that will act like fgets without the
|
* This function return an iterator that will act like fgets without the
|
||||||
* useless memcpy. Be aware that once eina_iterator_next has been called,
|
* useless memcpy. Be aware that once eina_iterator_next has been called,
|
||||||
|
|
|
@ -26,125 +26,323 @@
|
||||||
|
|
||||||
#define EINA_FILE_MAGIC 0xFEEDBEEF
|
#define EINA_FILE_MAGIC 0xFEEDBEEF
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @addtogroup Eina_Tools_Group Tools
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
/**
|
||||||
|
* @addtogroup Eina_File_Group File
|
||||||
|
*
|
||||||
|
* @brief Functions to handle files and directories.
|
||||||
|
*
|
||||||
|
* This module performs internal housekeeping and utility tasks for Eina_File.
|
||||||
|
* It also provides the underlying data types for things like file handles, file
|
||||||
|
* maps and file iterators.
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_File_Map
|
||||||
|
*
|
||||||
|
* Type definition for an Eina File Map.
|
||||||
|
*
|
||||||
|
*/
|
||||||
typedef struct _Eina_File_Map Eina_File_Map;
|
typedef struct _Eina_File_Map Eina_File_Map;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Lines_Iterator
|
||||||
|
*
|
||||||
|
* Type definition for an Eina Lines Iterator.
|
||||||
|
*
|
||||||
|
*/
|
||||||
typedef struct _Eina_Lines_Iterator Eina_Lines_Iterator;
|
typedef struct _Eina_Lines_Iterator Eina_Lines_Iterator;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @struct _Eina_File
|
||||||
|
*
|
||||||
|
* This is the underlying data structure that represents a file in Eina.
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct _Eina_File
|
struct _Eina_File
|
||||||
{
|
{
|
||||||
EINA_MAGIC;
|
EINA_MAGIC; /**< Indicates whether Eina Magic should be used. */
|
||||||
const char *filename;
|
const char *filename; /**< The absolute path of the file. Note that the path given when calling @ref eina_file_open will be run through @ref eina_file_path_sanitize before it is stored here. */
|
||||||
|
Eina_Hash *map; /**< Tracks portions of a file that have been mapped with mmap(2). The key is a tuple offset/length and the data is a pointer to the mapped region. */
|
||||||
Eina_Hash *map;
|
Eina_Hash *rmap; /**< Similar function to #map, but used to look up mapped areas by pointer rather than offset/length. */
|
||||||
Eina_Hash *rmap;
|
void *global_map; /**< A pointer to the entire contents of the file that have been mapped with mmap(2). This is the common case, and EFL and is optimized for it. */
|
||||||
void *global_map;
|
Eina_Lock lock; /**< A file locking mechanism. */
|
||||||
|
|
||||||
Eina_Lock lock;
|
|
||||||
|
|
||||||
#ifndef _WIN32
|
#ifndef _WIN32
|
||||||
unsigned long long length;
|
unsigned long long length; /**< The length of the file in bytes. */
|
||||||
time_t mtime;
|
time_t mtime; /**< The last modified time. */
|
||||||
ino_t inode;
|
ino_t inode; /**< The inode. */
|
||||||
#ifdef _STAT_VER_LINUX
|
#ifdef _STAT_VER_LINUX
|
||||||
unsigned long int mtime_nsec;
|
unsigned long int mtime_nsec; /**< The nano version of the last modified time. */
|
||||||
#endif
|
#endif
|
||||||
#else
|
#else
|
||||||
ULONGLONG length;
|
ULONGLONG length; /**< The length of the file in bytes. */
|
||||||
ULONGLONG mtime;
|
ULONGLONG mtime; /**< The last modified time. */
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
int refcount;
|
int refcount; /**< Keeps track of references to #map. */
|
||||||
int global_refcount;
|
int global_refcount; /**< Keeps track of references to #global_map. */
|
||||||
|
|
||||||
#ifndef _WIN32
|
#ifndef _WIN32
|
||||||
int fd;
|
int fd; /**< The file descriptor. */
|
||||||
#else
|
#else
|
||||||
HANDLE handle;
|
HANDLE handle; /**< A Win32 file handle for this file. */
|
||||||
HANDLE fm;
|
HANDLE fm; /**< A Win32 file handle to a file mapping object for this file. */
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
Eina_List *dead_map;
|
Eina_List *dead_map; /**< Tracks regions that get a failure from mmap(2). */
|
||||||
|
|
||||||
Eina_Bool shared : 1;
|
Eina_Bool shared : 1; /**< Indicates whether this file can be shared */
|
||||||
Eina_Bool delete_me : 1;
|
Eina_Bool delete_me : 1; /**< Indicates that this file should be deleted */
|
||||||
Eina_Bool global_faulty : 1;
|
Eina_Bool global_faulty : 1; /**< Indicates whether #global_map is bad */
|
||||||
Eina_Bool virtual : 1;
|
Eina_Bool virtual : 1; /**< Indicates that this is a virtual file */
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @struct _Eina_File_Map
|
||||||
|
*
|
||||||
|
* This represents a memory mapped region of a file.
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct _Eina_File_Map
|
struct _Eina_File_Map
|
||||||
{
|
{
|
||||||
void *map;
|
void *map; /**< A pointer to the mapped region */
|
||||||
|
|
||||||
unsigned long int offset;
|
unsigned long int offset; /**< The offset in the file */
|
||||||
unsigned long int length;
|
unsigned long int length; /**< The length of the region */
|
||||||
|
|
||||||
int refcount;
|
int refcount; /**< Tracks references to this region */
|
||||||
|
|
||||||
Eina_Bool hugetlb : 1;
|
Eina_Bool hugetlb : 1; /**< Indicates if we are using HugeTLB */
|
||||||
Eina_Bool faulty : 1;
|
Eina_Bool faulty : 1; /**< Indicates if this region was not mapped correctly (i.e. the call to mmap(2) failed). */
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @struct _Eina_Lines_Iterator
|
||||||
|
*
|
||||||
|
* This represents a line iterator a file.
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct _Eina_Lines_Iterator
|
struct _Eina_Lines_Iterator
|
||||||
{
|
{
|
||||||
Eina_Iterator iterator;
|
Eina_Iterator iterator; /**< The iterator itself */
|
||||||
|
|
||||||
Eina_File *fp;
|
Eina_File *fp; /**< The file this iterator is associated with */
|
||||||
const char *map;
|
const char *map; /**< A pointer to the head of the file that has been mapped with mmap(2). */
|
||||||
const char *end;
|
const char *end; /**< A pointer to the end of the file that has been mapped with mmap(2). */
|
||||||
|
|
||||||
int boundary;
|
int boundary; /**< Curretnly hard coded to 4096. */
|
||||||
|
|
||||||
Eina_File_Line current;
|
Eina_File_Line current; /**< The current line */
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
#ifndef EINA_LOG_COLOR_DEFAULT
|
#ifndef EINA_LOG_COLOR_DEFAULT
|
||||||
|
/** Set the color for Eina log entries */
|
||||||
#define EINA_LOG_COLOR_DEFAULT EINA_COLOR_CYAN
|
#define EINA_LOG_COLOR_DEFAULT EINA_COLOR_CYAN
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
#ifdef ERR
|
#ifdef ERR
|
||||||
#undef ERR
|
#undef ERR
|
||||||
#endif
|
#endif
|
||||||
|
/** Macro for logging Eina errors */
|
||||||
#define ERR(...) EINA_LOG_DOM_ERR(_eina_file_log_dom, __VA_ARGS__)
|
#define ERR(...) EINA_LOG_DOM_ERR(_eina_file_log_dom, __VA_ARGS__)
|
||||||
|
|
||||||
#ifdef WRN
|
#ifdef WRN
|
||||||
#undef WRN
|
#undef WRN
|
||||||
#endif
|
#endif
|
||||||
|
/** Macro for logging Eina warnings */
|
||||||
#define WRN(...) EINA_LOG_DOM_WARN(_eina_file_log_dom, __VA_ARGS__)
|
#define WRN(...) EINA_LOG_DOM_WARN(_eina_file_log_dom, __VA_ARGS__)
|
||||||
|
|
||||||
#ifdef INF
|
#ifdef INF
|
||||||
#undef INF
|
#undef INF
|
||||||
#endif
|
#endif
|
||||||
|
/** Macro for logging Eina info messages */
|
||||||
#define INF(...) EINA_LOG_DOM_INFO(_eina_file_log_dom, __VA_ARGS__)
|
#define INF(...) EINA_LOG_DOM_INFO(_eina_file_log_dom, __VA_ARGS__)
|
||||||
|
|
||||||
#ifdef DBG
|
#ifdef DBG
|
||||||
#undef DBG
|
#undef DBG
|
||||||
#endif
|
#endif
|
||||||
|
/** Macro for logging Eina debug messages */
|
||||||
#define DBG(...) EINA_LOG_DOM_DBG(_eina_file_log_dom, __VA_ARGS__)
|
#define DBG(...) EINA_LOG_DOM_DBG(_eina_file_log_dom, __VA_ARGS__)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Determines if a path is relative or absolute.
|
||||||
|
* The implementation simply chekcs if the fist char in the path is '/'. If it
|
||||||
|
* is not, the path is considered relative.
|
||||||
|
*
|
||||||
|
* @param path The path to check.
|
||||||
|
|
||||||
|
* @return EINA_TRUE if the path is relative, EINA_FALSE otherwise.
|
||||||
|
*
|
||||||
|
*/
|
||||||
Eina_Bool eina_file_path_relative(const char *path);
|
Eina_Bool eina_file_path_relative(const char *path);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Gets the current directory and optionally appends a path to it.
|
||||||
|
* If a string was passed in via the @p path parameter, it will
|
||||||
|
* be appended to the current working directory. Presumably, this will be a
|
||||||
|
* relative path.
|
||||||
|
*
|
||||||
|
* @param path The path to append to the current directory.
|
||||||
|
* @param len The length of @p path.
|
||||||
|
*
|
||||||
|
* @return A pointer to a string that contains the absolute path to the current
|
||||||
|
* working directory plus any path you send in.
|
||||||
|
*
|
||||||
|
*/
|
||||||
Eina_Tmpstr *eina_file_current_directory_get(const char *path, size_t len);
|
Eina_Tmpstr *eina_file_current_directory_get(const char *path, size_t len);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Cleans up Eina after a file is no longer needed.
|
||||||
|
*
|
||||||
|
* @param path The path of the file.
|
||||||
|
*
|
||||||
|
* @return On success, it will return the @p path string. If @p path is @c NULL,
|
||||||
|
* it will return and empty string.
|
||||||
|
*
|
||||||
|
*/
|
||||||
char *eina_file_cleanup(Eina_Tmpstr *path);
|
char *eina_file_cleanup(Eina_Tmpstr *path);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Closes and cleans up after an Eina file.
|
||||||
|
*
|
||||||
|
* @param file The path of the file.
|
||||||
|
*
|
||||||
|
*
|
||||||
|
*/
|
||||||
void eina_file_clean_close(Eina_File *file);
|
void eina_file_clean_close(Eina_File *file);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Closes a file from the OS perspective.
|
||||||
|
*
|
||||||
|
* @param file The path of the file.
|
||||||
|
*
|
||||||
|
*
|
||||||
|
*/
|
||||||
void eina_file_real_close(Eina_File *file);
|
void eina_file_real_close(Eina_File *file);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Resets the internal housekeeping structures after a file has changed.
|
||||||
|
* Despite the name, this routine does not write anything to disk. It invalidates
|
||||||
|
* the memory maps for the file. If the file has shrunk, it also adds any mapped
|
||||||
|
* regions past the end of the file to the dead_map.
|
||||||
|
*
|
||||||
|
* @param file The file.
|
||||||
|
* @param length The current length of the file after the change.
|
||||||
|
*
|
||||||
|
*
|
||||||
|
*/
|
||||||
void eina_file_flush(Eina_File *file, unsigned long int length);
|
void eina_file_flush(Eina_File *file, unsigned long int length);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Removes a mapped region from the file and frees the resources.
|
||||||
|
* This routine will remove a previously mapped region from the internal Eina File
|
||||||
|
* housekeeping and free the resources associated with it. In the case where
|
||||||
|
* the map is part of the dead_map, @p free_func will be called to handle the actual
|
||||||
|
* deallocation.
|
||||||
|
*
|
||||||
|
* @param file The file.
|
||||||
|
* @param map The memory mapped region that is to be freed.
|
||||||
|
* @param free_func A pointer to a function that will be called to free up the
|
||||||
|
* resources used by the map.
|
||||||
|
*
|
||||||
|
*
|
||||||
|
*/
|
||||||
void eina_file_common_map_free(Eina_File *file, void *map,
|
void eina_file_common_map_free(Eina_File *file, void *map,
|
||||||
void (*free_func)(Eina_File_Map *map));
|
void (*free_func)(Eina_File_Map *map));
|
||||||
|
|
||||||
|
/** A pointer to the global Eina file cache. */
|
||||||
extern Eina_Hash *_eina_file_cache;
|
extern Eina_Hash *_eina_file_cache;
|
||||||
|
|
||||||
|
/** The global file lock cache */
|
||||||
extern Eina_Lock _eina_file_lock_cache;
|
extern Eina_Lock _eina_file_lock_cache;
|
||||||
|
|
||||||
|
/** The global Eina log file domain. */
|
||||||
extern int _eina_file_log_dom;
|
extern int _eina_file_log_dom;
|
||||||
|
|
||||||
// Common function to handle virtual file
|
// Common function to handle virtual file
|
||||||
|
/**
|
||||||
|
* @brief Map the entire contents fo a virtual file to a buffer.
|
||||||
|
*
|
||||||
|
* @param file The virtual file to map in memory
|
||||||
|
*
|
||||||
|
*/
|
||||||
void *eina_file_virtual_map_all(Eina_File *file);
|
void *eina_file_virtual_map_all(Eina_File *file);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Map a part of a virtual file to a buffer.
|
||||||
|
*
|
||||||
|
* @param file The virtual file to map in memory
|
||||||
|
* @param offset The offset inside the file to start mapping
|
||||||
|
* @param length The length of the region to map
|
||||||
|
*
|
||||||
|
*/
|
||||||
void *eina_file_virtual_map_new(Eina_File *file,
|
void *eina_file_virtual_map_new(Eina_File *file,
|
||||||
unsigned long int offset, unsigned long int length);
|
unsigned long int offset, unsigned long int length);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Unref and unmap memory if possible.
|
||||||
|
*
|
||||||
|
* @param file The file handler to unmap memory from.
|
||||||
|
* @param map Memory map to unref and unmap.
|
||||||
|
*
|
||||||
|
*/
|
||||||
void eina_file_virtual_map_free(Eina_File *file, void *map);
|
void eina_file_virtual_map_free(Eina_File *file, void *map);
|
||||||
|
|
||||||
// Common hash function
|
// Common hash function
|
||||||
|
/**
|
||||||
|
* @brief Get the length of a map key.
|
||||||
|
* @warning This function is not yet implemented. At present it ony returns
|
||||||
|
* @code sizeof (unsigned long int) * 2 @endcode
|
||||||
|
*
|
||||||
|
* @param key The key for which length will be calcualted.
|
||||||
|
*
|
||||||
|
* @return The length of the key.
|
||||||
|
*
|
||||||
|
*/
|
||||||
unsigned int eina_file_map_key_length(const void *key);
|
unsigned int eina_file_map_key_length(const void *key);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Compares two map keys.
|
||||||
|
* The implementation assumes that @p key1 and @p key2 are both pointers to an
|
||||||
|
* array with 2 elements, as is the case with the Eina file map keys.
|
||||||
|
*
|
||||||
|
* @param key1 The first key.
|
||||||
|
* @param key1_length The length of the first key.
|
||||||
|
* @param key2 The second key.
|
||||||
|
* @param key2_length The length of the second key.
|
||||||
|
*
|
||||||
|
* @return Positive number if Key1 > Key2, else a negative number. Will return
|
||||||
|
* zero if both elements of the key are exactly the same.
|
||||||
|
*
|
||||||
|
*/
|
||||||
int eina_file_map_key_cmp(const unsigned long long int *key1, int key1_length,
|
int eina_file_map_key_cmp(const unsigned long long int *key1, int key1_length,
|
||||||
const unsigned long long int *key2, int key2_length);
|
const unsigned long long int *key2, int key2_length);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Creates a hash from a map key.
|
||||||
|
*
|
||||||
|
* @param key A pointer to the key.
|
||||||
|
* @param key_length The length of the key.
|
||||||
|
*
|
||||||
|
* @return A key hash.
|
||||||
|
*
|
||||||
|
*/
|
||||||
int eina_file_map_key_hash(const unsigned long long int *key, int key_length);
|
int eina_file_map_key_hash(const unsigned long long int *key, int key_length);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
||||||
#endif /* EINA_FILE_COMMON_H_ */
|
#endif /* EINA_FILE_COMMON_H_ */
|
||||||
|
|
|
@ -287,8 +287,16 @@
|
||||||
*/
|
*/
|
||||||
typedef struct _Eina_Hash Eina_Hash;
|
typedef struct _Eina_Hash Eina_Hash;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Hash_Tuple
|
||||||
|
* Type for a hash table of key/value pairs.
|
||||||
|
*/
|
||||||
typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
|
typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @struct _Eina_Hash_Tuple
|
||||||
|
* Data for a hash table of key/value pairs.
|
||||||
|
*/
|
||||||
struct _Eina_Hash_Tuple
|
struct _Eina_Hash_Tuple
|
||||||
{
|
{
|
||||||
const void *key; /**< The key */
|
const void *key; /**< The key */
|
||||||
|
@ -296,24 +304,44 @@ struct _Eina_Hash_Tuple
|
||||||
unsigned int key_length; /**< The length of the key */
|
unsigned int key_length; /**< The length of the key */
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Key_Length
|
||||||
|
* Type for a function to determine the length of a hash key.
|
||||||
|
*/
|
||||||
typedef unsigned int (*Eina_Key_Length)(const void *key);
|
typedef unsigned int (*Eina_Key_Length)(const void *key);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @def EINA_KEY_LENGTH
|
* @def EINA_KEY_LENGTH
|
||||||
* @param Function The function used to calculate length of hash key.
|
* @param Function The function used to calculate length of hash key.
|
||||||
*/
|
*/
|
||||||
#define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
|
#define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Key_Cmp
|
||||||
|
* Type for a function to compare two hash keys.
|
||||||
|
*/
|
||||||
typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
|
typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
|
||||||
/**
|
/**
|
||||||
* @def EINA_KEY_CMP
|
* @def EINA_KEY_CMP
|
||||||
* @param Function The function used to compare hash key.
|
* @param Function The function used to compare hash key.
|
||||||
*/
|
*/
|
||||||
#define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
|
#define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Key_Hash
|
||||||
|
* Type for a function to create a hash key.
|
||||||
|
*/
|
||||||
typedef int (*Eina_Key_Hash)(const void *key, int key_length);
|
typedef int (*Eina_Key_Hash)(const void *key, int key_length);
|
||||||
/**
|
/**
|
||||||
* @def EINA_KEY_HASH
|
* @def EINA_KEY_HASH
|
||||||
* @param Function The function used to hash key.
|
* @param Function The function used to hash key.
|
||||||
*/
|
*/
|
||||||
#define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
|
#define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Hash_Foreach
|
||||||
|
* Type for a function to iterate over a hash table.
|
||||||
|
*/
|
||||||
typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
|
typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
|
||||||
|
|
||||||
|
|
||||||
|
@ -1015,22 +1043,72 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL
|
||||||
EAPI void eina_hash_foreach(const Eina_Hash *hash,
|
EAPI void eina_hash_foreach(const Eina_Hash *hash,
|
||||||
Eina_Hash_Foreach func,
|
Eina_Hash_Foreach func,
|
||||||
const void *fdata) EINA_ARG_NONNULL(1, 2);
|
const void *fdata) EINA_ARG_NONNULL(1, 2);
|
||||||
/* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief
|
||||||
|
* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/)
|
||||||
|
*
|
||||||
|
* @param key The key to hash
|
||||||
|
* @param len The length of the key
|
||||||
|
* @return The hash value
|
||||||
|
*/
|
||||||
EAPI int eina_hash_superfast(const char *key,
|
EAPI int eina_hash_superfast(const char *key,
|
||||||
int len) EINA_ARG_NONNULL(1);
|
int len) EINA_ARG_NONNULL(1);
|
||||||
/* Hash function first reported by dan bernstein many years ago in comp.lang.c */
|
|
||||||
|
/**
|
||||||
|
* @brief
|
||||||
|
* Hash function first reported by Dan Bernstein many years ago in comp.lang.c
|
||||||
|
*
|
||||||
|
* @param key The key to hash
|
||||||
|
* @param len The length of the key
|
||||||
|
* @return The hash value
|
||||||
|
*/
|
||||||
static inline int eina_hash_djb2(const char *key,
|
static inline int eina_hash_djb2(const char *key,
|
||||||
int len) EINA_ARG_NONNULL(1);
|
int len) EINA_ARG_NONNULL(1);
|
||||||
|
/**
|
||||||
|
* @brief
|
||||||
|
* Hash function first reported by Dan Bernstein many years ago in comp.lang.c
|
||||||
|
*
|
||||||
|
* @param key The key to hash
|
||||||
|
* @param plen The length of the key
|
||||||
|
* @return The hash value
|
||||||
|
*/
|
||||||
static inline int eina_hash_djb2_len(const char *key,
|
static inline int eina_hash_djb2_len(const char *key,
|
||||||
int *plen) EINA_ARG_NONNULL(1, 2);
|
int *plen) EINA_ARG_NONNULL(1, 2);
|
||||||
/* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
|
|
||||||
|
/**
|
||||||
|
* @brief
|
||||||
|
* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm
|
||||||
|
*
|
||||||
|
* @param pkey The key to hash
|
||||||
|
* @param len The length of the key
|
||||||
|
* @return The hash value
|
||||||
|
*/
|
||||||
static inline int eina_hash_int32(const unsigned int *pkey,
|
static inline int eina_hash_int32(const unsigned int *pkey,
|
||||||
int len) EINA_ARG_NONNULL(1);
|
int len) EINA_ARG_NONNULL(1);
|
||||||
|
/**
|
||||||
|
* @brief
|
||||||
|
* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm
|
||||||
|
*
|
||||||
|
* @param pkey The key to hash
|
||||||
|
* @param len The length of the key
|
||||||
|
* @return The hash value
|
||||||
|
*/
|
||||||
static inline int eina_hash_int64(const unsigned long long int *pkey,
|
static inline int eina_hash_int64(const unsigned long long int *pkey,
|
||||||
int len) EINA_ARG_NONNULL(1);
|
int len) EINA_ARG_NONNULL(1);
|
||||||
/* http://sites.google.com/site/murmurhash/ */
|
|
||||||
|
/**
|
||||||
|
* @brief
|
||||||
|
* Hash function from http://sites.google.com/site/murmurhash/
|
||||||
|
*
|
||||||
|
* @param key The key to hash
|
||||||
|
* @param len The length of the key
|
||||||
|
* @return The hash value
|
||||||
|
*/
|
||||||
static inline int eina_hash_murmur3(const char *key,
|
static inline int eina_hash_murmur3(const char *key,
|
||||||
int len) EINA_ARG_NONNULL(1);
|
int len) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
#include "eina_inline_hash.x"
|
#include "eina_inline_hash.x"
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
|
@ -247,6 +247,7 @@ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
|
||||||
/**
|
/**
|
||||||
* @brief Initialize inline array.
|
* @brief Initialize inline array.
|
||||||
* @param array array object to initialize.
|
* @param array array object to initialize.
|
||||||
|
* @param sizeof_eina_inarray the initial size of the array.
|
||||||
* @param member_size size of each member in the array.
|
* @param member_size size of each member in the array.
|
||||||
* @param step when resizing the array, do this using the following
|
* @param step when resizing the array, do this using the following
|
||||||
* extra amount.
|
* extra amount.
|
||||||
|
|
|
@ -41,20 +41,6 @@ EAPI Eina_Bool eina_array_grow(Eina_Array *array);
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
|
||||||
* @brief Append a data to an array.
|
|
||||||
*
|
|
||||||
* @param array The array.
|
|
||||||
* @param data The data to add.
|
|
||||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
|
|
||||||
*
|
|
||||||
* This function appends @p data to @p array. For performance
|
|
||||||
* reasons, there is no check of @p array. If it is @c NULL or
|
|
||||||
* invalid, the program may crash. If @p data is @c NULL, or if an
|
|
||||||
* allocation is necessary and fails, #EINA_FALSE is returned
|
|
||||||
* Otherwise, #EINA_TRUE is returned.
|
|
||||||
*/
|
|
||||||
|
|
||||||
static inline Eina_Bool
|
static inline Eina_Bool
|
||||||
eina_array_push(Eina_Array *array, const void *data)
|
eina_array_push(Eina_Array *array, const void *data)
|
||||||
{
|
{
|
||||||
|
@ -69,18 +55,6 @@ eina_array_push(Eina_Array *array, const void *data)
|
||||||
return EINA_TRUE;
|
return EINA_TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* @brief Remove the last data of an array.
|
|
||||||
*
|
|
||||||
* @param array The array.
|
|
||||||
* @return The retrieved data.
|
|
||||||
*
|
|
||||||
* This function removes the last data of @p array, decreases the count
|
|
||||||
* of @p array and returns the data. For performance reasons, there
|
|
||||||
* is no check of @p array. If it is @c NULL or invalid, the program
|
|
||||||
* may crash. If the count member is less or equal than 0, @c NULL is
|
|
||||||
* returned.
|
|
||||||
*/
|
|
||||||
static inline void *
|
static inline void *
|
||||||
eina_array_pop(Eina_Array *array)
|
eina_array_pop(Eina_Array *array)
|
||||||
{
|
{
|
||||||
|
@ -95,17 +69,6 @@ eina_array_pop(Eina_Array *array)
|
||||||
return ret;
|
return ret;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* @brief Return the data at a given position in an array.
|
|
||||||
*
|
|
||||||
* @param array The array.
|
|
||||||
* @param idx The potition of the data to retrieve.
|
|
||||||
* @return The retrieved data.
|
|
||||||
*
|
|
||||||
* This function returns the data at the position @p idx in @p
|
|
||||||
* array. For performance reasons, there is no check of @p array or @p
|
|
||||||
* idx. If it is @c NULL or invalid, the program may crash.
|
|
||||||
*/
|
|
||||||
static inline void *
|
static inline void *
|
||||||
eina_array_data_get(const Eina_Array *array, unsigned int idx)
|
eina_array_data_get(const Eina_Array *array, unsigned int idx)
|
||||||
{
|
{
|
||||||
|
@ -118,34 +81,14 @@ eina_array_data_set(const Eina_Array *array, unsigned int idx, const void *data)
|
||||||
array->data[idx] = (void*) data;
|
array->data[idx] = (void*) data;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* @brief Return the number of elements in an array.
|
|
||||||
*
|
|
||||||
* @param array The array.
|
|
||||||
* @return The number of elements.
|
|
||||||
*
|
|
||||||
* This function returns the number of elements in @p array. For
|
|
||||||
* performance reasons, there is no check of @p array. If it is
|
|
||||||
* @c NULL or invalid, the program may crash.
|
|
||||||
*
|
|
||||||
* @deprecated use eina_array_count()
|
|
||||||
*/
|
|
||||||
static inline unsigned int
|
static inline unsigned int
|
||||||
eina_array_count_get(const Eina_Array *array)
|
eina_array_count_get(const Eina_Array *array)
|
||||||
{
|
{
|
||||||
return array->count;
|
return array->count;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* @brief Return the number of elements in an array.
|
|
||||||
*
|
|
||||||
* @param array The array.
|
|
||||||
* @return The number of elements.
|
|
||||||
*
|
|
||||||
* This function returns the number of elements in @p array. For
|
|
||||||
* performance reasons, there is no check of @p array. If it is
|
|
||||||
* @c NULL or invalid, the program may crash.
|
|
||||||
*/
|
|
||||||
static inline unsigned int
|
static inline unsigned int
|
||||||
eina_array_count(const Eina_Array *array)
|
eina_array_count(const Eina_Array *array)
|
||||||
{
|
{
|
||||||
|
|
|
@ -70,7 +70,7 @@
|
||||||
*
|
*
|
||||||
* @image html eina_inlist-node_eg1-inlist.png
|
* @image html eina_inlist-node_eg1-inlist.png
|
||||||
* @image rtf eina_inlist-node_eg1-inlist.png
|
* @image rtf eina_inlist-node_eg1-inlist.png
|
||||||
* @image latex eina_inlist-node_eg1-inlist.eps width=\textwidth
|
* @image latex eina_inlist-node_eg1-inlist.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list:
|
* The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list:
|
||||||
*
|
*
|
||||||
|
@ -157,7 +157,7 @@
|
||||||
* <img src="eina_inlist-node_eg2-list-inlist.png" style="max-width: 100%;"/>
|
* <img src="eina_inlist-node_eg2-list-inlist.png" style="max-width: 100%;"/>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image rtf eina_inlist-node_eg2-list-inlist.png
|
* @image rtf eina_inlist-node_eg2-list-inlist.png
|
||||||
* @image latex eina_inlist-node_eg2-list-inlist.eps width=\textwidth
|
* @image latex eina_inlist-node_eg2-list-inlist.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* Accessing both lists is done normally, as if they didn't have any elements in
|
* Accessing both lists is done normally, as if they didn't have any elements in
|
||||||
* common:
|
* common:
|
||||||
|
@ -233,7 +233,7 @@
|
||||||
* <img src="eina_inlist-node_eg3-two-inlists.png" style="max-width: 100%;"/>
|
* <img src="eina_inlist-node_eg3-two-inlists.png" style="max-width: 100%;"/>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image rtf eina_inlist-node_eg3-two-inlists.png
|
* @image rtf eina_inlist-node_eg3-two-inlists.png
|
||||||
* @image latex eina_inlist-node_eg3-two-inlists.eps width=\textwidth
|
* @image latex eina_inlist-node_eg3-two-inlists.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* For the first list, we can use the macro @ref EINA_INLIST_FOREACH to iterate
|
* For the first list, we can use the macro @ref EINA_INLIST_FOREACH to iterate
|
||||||
* over its elements:
|
* over its elements:
|
||||||
|
|
|
@ -33,12 +33,23 @@
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Lalloc_Alloc
|
||||||
|
* Type definition for the callback used to allocate new items in a lazy allocator.
|
||||||
|
*
|
||||||
|
*/
|
||||||
typedef Eina_Bool (*Eina_Lalloc_Alloc)(void *user_data, int num);
|
typedef Eina_Bool (*Eina_Lalloc_Alloc)(void *user_data, int num);
|
||||||
/**
|
/**
|
||||||
* @def EINA_LALLOC_ALLOC
|
* @def EINA_LALLOC_ALLOC
|
||||||
* @param function The function to allocate.
|
* @param function The function to allocate.
|
||||||
*/
|
*/
|
||||||
#define EINA_LALLOC_ALLOC(function) ((Eina_Lalloc_Alloc)function)
|
#define EINA_LALLOC_ALLOC(function) ((Eina_Lalloc_Alloc)function)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Lalloc_Free
|
||||||
|
* Type definition for the callback used to allocate new items in a lazy allocator.
|
||||||
|
*
|
||||||
|
*/
|
||||||
typedef void (*Eina_Lalloc_Free)(void *user_data);
|
typedef void (*Eina_Lalloc_Free)(void *user_data);
|
||||||
/**
|
/**
|
||||||
* @def EINA_LALLOC_FREE
|
* @def EINA_LALLOC_FREE
|
||||||
|
@ -46,15 +57,57 @@ typedef void (*Eina_Lalloc_Free)(void *user_data);
|
||||||
*/
|
*/
|
||||||
#define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function)
|
#define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Lalloc
|
||||||
|
* Public type definition for a lazy allocator.
|
||||||
|
*
|
||||||
|
*/
|
||||||
typedef struct _Eina_Lalloc Eina_Lalloc;
|
typedef struct _Eina_Lalloc Eina_Lalloc;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Create a new lazy allocator.
|
||||||
|
*
|
||||||
|
* @param data The data for which memory will be allocated.
|
||||||
|
* @param alloc_cb The callback to allocate memory for @p data items.
|
||||||
|
* @param free_cb The callback to free memory for @p data items.
|
||||||
|
* @param num_init The number of @p data items to initally allocate space for.
|
||||||
|
*
|
||||||
|
* @return A new lazy allocator.
|
||||||
|
*
|
||||||
|
*/
|
||||||
EAPI Eina_Lalloc *eina_lalloc_new(void *data,
|
EAPI Eina_Lalloc *eina_lalloc_new(void *data,
|
||||||
Eina_Lalloc_Alloc alloc_cb,
|
Eina_Lalloc_Alloc alloc_cb,
|
||||||
Eina_Lalloc_Free free_cb,
|
Eina_Lalloc_Free free_cb,
|
||||||
int num_init) EINA_ARG_NONNULL(2, 3);
|
int num_init) EINA_ARG_NONNULL(2, 3);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Free the resources for a lazy allocator.
|
||||||
|
*
|
||||||
|
* @param a The lazy allocator to free.
|
||||||
|
*
|
||||||
|
*/
|
||||||
EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
|
EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Add several elements to a lazy allocator.
|
||||||
|
*
|
||||||
|
* @param a The lazy allocater to add items to.
|
||||||
|
* @param num The number of elements to add.
|
||||||
|
*
|
||||||
|
* @return EINA_TRUE on success, else EINA_FALSE.
|
||||||
|
*
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a,
|
EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a,
|
||||||
int num) EINA_ARG_NONNULL(1);
|
int num) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Allocate one more of whatever the lazy allocator is allocating.
|
||||||
|
*
|
||||||
|
* @param a The lazy allocator to add an item to.
|
||||||
|
*
|
||||||
|
* @return EINA_TRUE on success, else EINA_FALSE.
|
||||||
|
*
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
|
EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
|
@ -48,7 +48,7 @@
|
||||||
* <a href="eina_list_example_01_a.png">Full-size</a>
|
* <a href="eina_list_example_01_a.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image rtf eina_list_example_01_a.png
|
* @image rtf eina_list_example_01_a.png
|
||||||
* @image latex eina_list_example_01_a.eps width=\textwidth
|
* @image latex eina_list_example_01_a.eps "" width=\textwidth
|
||||||
* @until roslin
|
* @until roslin
|
||||||
* There are a couple of interesting things happening here, first is that we are
|
* There are a couple of interesting things happening here, first is that we are
|
||||||
* passing a NULL pointer to the first @ref eina_list_append() call, when this
|
* passing a NULL pointer to the first @ref eina_list_append() call, when this
|
||||||
|
@ -81,7 +81,7 @@
|
||||||
* <a href="eina_list_example_01_b.png">Full-size</a>
|
* <a href="eina_list_example_01_b.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image rtf eina_list_example_01_b.png
|
* @image rtf eina_list_example_01_b.png
|
||||||
* @image latex eina_list_example_01_b.eps width=\textwidth
|
* @image latex eina_list_example_01_b.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* Once done using the list it needs to be freed, and since we are done with
|
* Once done using the list it needs to be freed, and since we are done with
|
||||||
* eina that also need to be shutdown:
|
* eina that also need to be shutdown:
|
||||||
|
@ -1352,7 +1352,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
||||||
* <img src="eina-list-foreach.png" style="max-width: 100%;" />
|
* <img src="eina-list-foreach.png" style="max-width: 100%;" />
|
||||||
* <a href="eina-list-foreach.png">Full-size</a>
|
* <a href="eina-list-foreach.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image latex eina-list-foreach.eps width=\textwidth
|
* @image latex eina-list-foreach.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* It can be used to free list data, as in the following example:
|
* It can be used to free list data, as in the following example:
|
||||||
*
|
*
|
||||||
|
@ -1410,7 +1410,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
||||||
* <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" />
|
* <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" />
|
||||||
* <a href="eina-list-reverse-foreach.png">Full-size</a>
|
* <a href="eina-list-reverse-foreach.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image latex eina-list-reverse-foreach.eps width=\textwidth
|
* @image latex eina-list-reverse-foreach.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* It can be used to free list data, as in the following example:
|
* It can be used to free list data, as in the following example:
|
||||||
*
|
*
|
||||||
|
@ -1471,7 +1471,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
||||||
* <img src="eina-list-foreach-safe.png" style="max-width: 100%;" />
|
* <img src="eina-list-foreach-safe.png" style="max-width: 100%;" />
|
||||||
* <a href="eina-list-foreach-safe.png">Full-size</a>
|
* <a href="eina-list-foreach-safe.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image latex eina-list-foreach-safe.eps width=\textwidth
|
* @image latex eina-list-foreach-safe.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* This macro can be used to free list nodes, as in the following example:
|
* This macro can be used to free list nodes, as in the following example:
|
||||||
*
|
*
|
||||||
|
@ -1528,7 +1528,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
||||||
* <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" />
|
* <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" />
|
||||||
* <a href="eina-list-reverse-foreach-safe.png">Full-size</a>
|
* <a href="eina-list-reverse-foreach-safe.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image latex eina-list-reverse-foreach-safe.eps width=\textwidth
|
* @image latex eina-list-reverse-foreach-safe.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* This macro can be used to free list nodes, as in the following example:
|
* This macro can be used to free list nodes, as in the following example:
|
||||||
*
|
*
|
||||||
|
@ -1577,7 +1577,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
|
||||||
* <img src="eina-list-free.png" style="max-width: 100%;" />
|
* <img src="eina-list-free.png" style="max-width: 100%;" />
|
||||||
* <a href="eina-list-free.png">Full-size</a>
|
* <a href="eina-list-free.png">Full-size</a>
|
||||||
* @endhtmlonly
|
* @endhtmlonly
|
||||||
* @image latex eina-list-free.eps width=\textwidth
|
* @image latex eina-list-free.eps "" width=\textwidth
|
||||||
*
|
*
|
||||||
* If you do not need to release node data, it is easier to call #eina_list_free().
|
* If you do not need to release node data, it is easier to call #eina_list_free().
|
||||||
*
|
*
|
||||||
|
|
|
@ -443,6 +443,11 @@ struct _Eina_Log_Domain
|
||||||
*/
|
*/
|
||||||
EAPI void eina_log_threads_enable(void);
|
EAPI void eina_log_threads_enable(void);
|
||||||
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Log_Level
|
||||||
|
* List of available logging levels.
|
||||||
|
*/
|
||||||
/**
|
/**
|
||||||
* @enum _Eina_Log_Level
|
* @enum _Eina_Log_Level
|
||||||
* List of available logging levels.
|
* List of available logging levels.
|
||||||
|
@ -467,6 +472,14 @@ typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d,
|
||||||
const char *file, const char *fnc, int line,
|
const char *file, const char *fnc, int line,
|
||||||
const char *fmt, void *data, va_list args);
|
const char *fmt, void *data, va_list args);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Log_State
|
||||||
|
* List of available log states.
|
||||||
|
*/
|
||||||
|
/**
|
||||||
|
* @enum _Eina_Log_State
|
||||||
|
* List of available log states.
|
||||||
|
*/
|
||||||
typedef enum _Eina_Log_State
|
typedef enum _Eina_Log_State
|
||||||
{
|
{
|
||||||
EINA_LOG_STATE_START,
|
EINA_LOG_STATE_START,
|
||||||
|
@ -517,27 +530,34 @@ EAPI void eina_log_level_set(int level);
|
||||||
*/
|
*/
|
||||||
EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
|
EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Determine if a given @p level should be logged.
|
||||||
|
*
|
||||||
|
* @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE.
|
||||||
|
*
|
||||||
|
* @see eina_log_level_set()
|
||||||
|
*/
|
||||||
static inline Eina_Bool eina_log_level_check(int level);
|
static inline Eina_Bool eina_log_level_check(int level);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Checks if current thread is the main thread.
|
* @brief Checks if current thread is the main thread.
|
||||||
*
|
*
|
||||||
* @return #EINA_TRUE if threads were enabled and the current thread
|
* If there is no thread support (compiled with --disable-pthreads) or
|
||||||
* is the one that called eina_log_threads_init(). If there is
|
* threads were not enabled, then #EINA_TRUE is returned. The only case where
|
||||||
* no thread support (compiled with --disable-pthreads) or
|
* #EINA_FALSE is returned is when threads were successfully enabled but the
|
||||||
* they were not enabled, then #EINA_TRUE is also
|
* current thread is not the one that called eina_log_threads_init() (the
|
||||||
* returned. The only case where #EINA_FALSE is returned is
|
* manin thread).
|
||||||
* when threads were successfully enabled but the current
|
*
|
||||||
* thread is not the main (one that called
|
* @return #EINA_TRUE if the current thread is the one that called
|
||||||
* eina_log_threads_init()).
|
* eina_log_threads_init(), otherwise #EINA_FALSE.
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT;
|
EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Set if color logging should be disabled.
|
* @brief Enable or disable colored text in the logs.
|
||||||
*
|
*
|
||||||
* @param disabled if #EINA_TRUE, color logging should be disabled.
|
* @param disabled If #EINA_TRUE, color logging should be disabled.
|
||||||
*
|
*
|
||||||
* @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().
|
* @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().
|
||||||
*
|
*
|
||||||
|
@ -546,9 +566,9 @@ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UN
|
||||||
EAPI void eina_log_color_disable_set(Eina_Bool disabled);
|
EAPI void eina_log_color_disable_set(Eina_Bool disabled);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Get if color logging should be disabled.
|
* @brief Determine if color logging is enabled or disabled.
|
||||||
*
|
*
|
||||||
* @return if #EINA_TRUE, color logging should be disabled.
|
* @return If #EINA_TRUE, color logging is disabled.
|
||||||
*
|
*
|
||||||
* @see eina_log_color_disable_set()
|
* @see eina_log_color_disable_set()
|
||||||
*/
|
*/
|
||||||
|
@ -758,6 +778,7 @@ EAPI void eina_log_domain_unregister(int domain);
|
||||||
* @param line originating line in @a file.
|
* @param line originating line in @a file.
|
||||||
* @param fmt printf-like format to use. Should not provide trailing
|
* @param fmt printf-like format to use. Should not provide trailing
|
||||||
* '\n' as it is automatically included.
|
* '\n' as it is automatically included.
|
||||||
|
* @param ... variadic args.
|
||||||
*
|
*
|
||||||
* @note MT: this function may be called from different threads if
|
* @note MT: this function may be called from different threads if
|
||||||
* eina_log_threads_enable() was called before.
|
* eina_log_threads_enable() was called before.
|
||||||
|
@ -945,7 +966,7 @@ EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d,
|
||||||
* Configure console color of given file.
|
* Configure console color of given file.
|
||||||
*
|
*
|
||||||
* @param fp file to configure console color (usually stderr or stdout).
|
* @param fp file to configure console color (usually stderr or stdout).
|
||||||
* @param color a VT color code such as #EINA_COLOR_RED or #EINA_COLOR_RESET.
|
* @param color a VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET.
|
||||||
*
|
*
|
||||||
* @note if color is disabled, nothing is done. See
|
* @note if color is disabled, nothing is done. See
|
||||||
* eina_log_color_disable_get()
|
* eina_log_color_disable_get()
|
||||||
|
@ -956,10 +977,17 @@ EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d,
|
||||||
EAPI void eina_log_console_color_set(FILE *fp,
|
EAPI void eina_log_console_color_set(FILE *fp,
|
||||||
const char *color) EINA_ARG_NONNULL(1, 2);
|
const char *color) EINA_ARG_NONNULL(1, 2);
|
||||||
|
|
||||||
|
/** String that indicates the log system is initializing */
|
||||||
extern EAPI const char *_eina_log_state_init;
|
extern EAPI const char *_eina_log_state_init;
|
||||||
|
/** String that indicates the log system is shutting down */
|
||||||
extern EAPI const char *_eina_log_state_shutdown;
|
extern EAPI const char *_eina_log_state_shutdown;
|
||||||
|
/** @def EINA_LOG_STATE_INIT
|
||||||
|
*String that indicates the log system is initializing
|
||||||
|
*/
|
||||||
#define EINA_LOG_STATE_INIT _eina_log_state_init
|
#define EINA_LOG_STATE_INIT _eina_log_state_init
|
||||||
|
/** @def EINA_LOG_STATE_SHUTDOWN
|
||||||
|
*String that indicates the log system is shutting down
|
||||||
|
*/
|
||||||
#define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown
|
#define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
|
@ -226,6 +226,11 @@
|
||||||
/**
|
/**
|
||||||
* @def EINA_ARG_NONNULL
|
* @def EINA_ARG_NONNULL
|
||||||
* Used to warn when the specified arguments of the function are @c NULL.
|
* Used to warn when the specified arguments of the function are @c NULL.
|
||||||
|
*
|
||||||
|
* @param ... Oridnals of the parameters to check for nullity (1..n)
|
||||||
|
*
|
||||||
|
* @returns Nothing, but Doxygen will complain if it's not documented :-P
|
||||||
|
*
|
||||||
*/
|
*/
|
||||||
# define EINA_ARG_NONNULL(...)
|
# define EINA_ARG_NONNULL(...)
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue