forked from enlightenment/efl
eina: add some documentation for Eina_Cow.
This commit is contained in:
parent
a9c543c73f
commit
7dfa9af0f4
|
@ -19,27 +19,122 @@
|
||||||
#ifndef EINA_COW_H_
|
#ifndef EINA_COW_H_
|
||||||
#define EINA_COW_H_
|
#define EINA_COW_H_
|
||||||
|
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @addtogroup Eina_Tools_Group Tools
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @defgroup Eina_Cow_Group Lock
|
||||||
|
*
|
||||||
|
* @brief These functions provide some helper for a pseudo Copy On Write mechanism.
|
||||||
|
*
|
||||||
|
* Eina_Cow will return const memory pointer to some default value that you will
|
||||||
|
* be able to change only by requesting a writable pointer. Later on a garbage collector
|
||||||
|
* can come online and try to merge back some of those pointer.
|
||||||
|
*
|
||||||
|
* @since 1.8.0
|
||||||
|
*
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Cow
|
||||||
|
* Type for Eina_Cow pool
|
||||||
|
*/
|
||||||
typedef struct _Eina_Cow Eina_Cow;
|
typedef struct _Eina_Cow Eina_Cow;
|
||||||
|
/**
|
||||||
|
* @typedef Eina_Cow_Data
|
||||||
|
* Type of the returned pointer to simplify some reading.
|
||||||
|
*/
|
||||||
typedef void Eina_Cow_Data;
|
typedef void Eina_Cow_Data;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Instantiate a new Eina_Cow pool.
|
||||||
|
*
|
||||||
|
* @param name The name of this pool, used for debug.
|
||||||
|
* @param struct_size The size of the object from this pool.
|
||||||
|
* @param step How many object to allocate when the pool get empty.
|
||||||
|
* @param default_value The default value returned by this pool.
|
||||||
|
* @return a valid new Eina_Cow or @c NULL on error.
|
||||||
|
*/
|
||||||
EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value) EINA_WARN_UNUSED_RESULT;
|
EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Destroy an Eina_Cow pool and all the allocated memory
|
||||||
|
*
|
||||||
|
* @param cow The pool to destroy
|
||||||
|
*/
|
||||||
EAPI void eina_cow_del(Eina_Cow *cow);
|
EAPI void eina_cow_del(Eina_Cow *cow);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Return a initialized pointer to the pool.
|
||||||
|
* @param cow The pool to take things from.
|
||||||
|
*/
|
||||||
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;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Free a pointer from the pool.
|
||||||
|
* @param cow The pool to gave back memory to.
|
||||||
|
*/
|
||||||
EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data *data);
|
EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data *data);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Get a writable pointer from a const pointer.
|
||||||
|
* @param cow The pool the pointer come from.
|
||||||
|
* @param src The pointer you want to write to.
|
||||||
|
*
|
||||||
|
* NOTE: this function is not thread safe, be careful.
|
||||||
|
*/
|
||||||
EAPI void *eina_cow_write(Eina_Cow *cow,
|
EAPI void *eina_cow_write(Eina_Cow *cow,
|
||||||
const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
|
const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
|
||||||
|
/**
|
||||||
|
* @brief Set back a pointer into read only.
|
||||||
|
* @param cow The pool the pointer come from.
|
||||||
|
* @param src The read only version of the pointer.
|
||||||
|
* @param data The pointer to which data where written to.
|
||||||
|
*
|
||||||
|
* NOTE: this function is not thread safe, be careful.
|
||||||
|
*/
|
||||||
EAPI void eina_cow_done(Eina_Cow *cow,
|
EAPI void eina_cow_done(Eina_Cow *cow,
|
||||||
const Eina_Cow_Data * const *dst,
|
const Eina_Cow_Data * const *dst,
|
||||||
const void *data,
|
const void *data,
|
||||||
Eina_Bool needed_gc);
|
Eina_Bool needed_gc);
|
||||||
|
/**
|
||||||
|
* @brief Make the destination contain the same thing as the source pointer.
|
||||||
|
* @param cow The pool the pointers come from.
|
||||||
|
* @param dst The destination to update.
|
||||||
|
* @param src The source of information to copy.
|
||||||
|
*/
|
||||||
EAPI void eina_cow_memcpy(Eina_Cow *cow,
|
EAPI void eina_cow_memcpy(Eina_Cow *cow,
|
||||||
const Eina_Cow_Data * const *dst,
|
const Eina_Cow_Data * const *dst,
|
||||||
const Eina_Cow_Data *src);
|
const Eina_Cow_Data *src);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Try to find entry that do have the same content and update them.
|
||||||
|
* @param cow The cow to try to compact.
|
||||||
|
* @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was.
|
||||||
|
*
|
||||||
|
* There is no guaranty in the time it will require, but should remain low.
|
||||||
|
* It does run a hash function on all possible common structure trying to
|
||||||
|
* find the one that match and merge then into one pointer.
|
||||||
|
*/
|
||||||
EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
|
EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @def EINA_COW_WRITE_BEGIN
|
||||||
|
* @brief This macro setup a writable pointer from a const one.
|
||||||
|
* @param Cow The Eina_Cow where the const pointer come from.
|
||||||
|
* @param Read The const pointer to get a writable handler from.
|
||||||
|
* @param Write_Type The type of the pointer you want to write to.
|
||||||
|
* @param Write The name of the variable where to put the writeable pointer to.
|
||||||
|
* @since 1.8.0
|
||||||
|
*
|
||||||
|
* Be careful this macro open a C scope that it expect to be closed by
|
||||||
|
* EINA_COW_WRITE_END().
|
||||||
|
*/
|
||||||
#define EINA_COW_WRITE_BEGIN(Cow, Read, Write_Type, Write) \
|
#define EINA_COW_WRITE_BEGIN(Cow, Read, Write_Type, Write) \
|
||||||
do \
|
do \
|
||||||
{ \
|
{ \
|
||||||
|
@ -47,10 +142,28 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
|
||||||
\
|
\
|
||||||
Write = eina_cow_write(Cow, ((const Eina_Cow_Data**)&(Read)));
|
Write = eina_cow_write(Cow, ((const Eina_Cow_Data**)&(Read)));
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @def EINA_COW_WRITE_END
|
||||||
|
* @brief This macro close the writable pointer.
|
||||||
|
* @param Cow The Eina_Cow where the const pointer come from.
|
||||||
|
* @param Read The const pointer to get a writable handler from.
|
||||||
|
* @param Write The name of the variable where to put the writeable pointer to.
|
||||||
|
* @since 1.8.0
|
||||||
|
*
|
||||||
|
* Be careful this macro close the scope opened by EINA_COW_WRITE_BEGIN().
|
||||||
|
*/
|
||||||
#define EINA_COW_WRITE_END(Cow, Read, Write) \
|
#define EINA_COW_WRITE_END(Cow, Read, Write) \
|
||||||
eina_cow_done(Cow, ((const Eina_Cow_Data**)&(Read)), Write, \
|
eina_cow_done(Cow, ((const Eina_Cow_Data**)&(Read)), Write, \
|
||||||
EINA_TRUE); \
|
EINA_TRUE); \
|
||||||
} \
|
} \
|
||||||
while (0);
|
while (0);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @}
|
||||||
|
*/
|
||||||
|
|
||||||
#endif
|
#endif
|
||||||
|
|
Loading…
Reference in New Issue