eina: enhance doxygen in eina_mempool.h
Summary: Arrange grouping Add @brief for brief description Add @details for detailed description Add @note for noted description Add [in] & [out] for parameters Add @see more Add links for EINA_TRUE, EINA_FALSE, etc. Fix indentation & Fix typeof Use @p instead of @a for the consistency Reviewers: raster, cedric Subscribers: cedric Differential Revision: https://phab.enlightenment.org/D1612 Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
Tae-Hwan Kim
Cedric BAIL
parent
62fd3c0a9b
commit
4c9995f4ee
|
|
@ -25,46 +25,36 @@
|
|||
|
||||
|
||||
/**
|
||||
* @addtogroup Eina_Memory_Pool_Group Memory Pool
|
||||
* @defgroup Eina_Memory_Pool_Group Memory Pool
|
||||
* @ingroup Eina_Tools_Group
|
||||
* @brief This group discusses the functions that provide memory pool management.
|
||||
*
|
||||
* @brief These functions provide memory pool management.
|
||||
*
|
||||
* Several mempool are available:
|
||||
* Several mempools are available:
|
||||
*
|
||||
* @li @c chained_pool: It is the default one. It allocates a big
|
||||
* chunk of memory with malloc() and split the result in chunks of the
|
||||
* chunk of memory with malloc() and splits the result into chunks of the
|
||||
* requested size that are pushed inside a stack. When requested, it
|
||||
* takes this pointer from the stack to give them to whoever wants
|
||||
* them.
|
||||
* @li @c pass_through: it just call malloc() and free(). It may be
|
||||
* faster on some computers than using our own allocators (like having
|
||||
* a huge L2 cache, over 4MB).
|
||||
* @li @c one_big: It calls just one time malloc for the requested number
|
||||
* of items. Useful when you know in advance how many objects of some
|
||||
* type will live during the life of the mempool.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @addtogroup Eina_Tools_Group Tools
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup Eina_Memory_Pool_Group Memory Pool
|
||||
* @li @c one_big: It calls malloc() just one time for the requested number
|
||||
* of items. This is useful when you know in advance how many objects of some
|
||||
* type live during the life of the mempool.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef Eina_Mempool
|
||||
* Mempool type.
|
||||
* @brief The opaque type for the mempool structure.
|
||||
*/
|
||||
typedef struct _Eina_Mempool Eina_Mempool;
|
||||
|
||||
/**
|
||||
* @typedef Eina_Mempool_Backend
|
||||
* Mempool backend type.
|
||||
* @brief The opaque type for the mempool backend type.
|
||||
*/
|
||||
typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend;
|
||||
|
||||
|
|
@ -72,161 +62,156 @@ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend;
|
|||
/**
|
||||
* @typedef Eina_Mempool_Repack_Cb
|
||||
*
|
||||
* Type for a callback which is called when the mempool "repacks" its data,
|
||||
* i.e. moves it around to optimize the way it is stored in memory. This is
|
||||
* useful to improve data locality and to free internal pools back to the OS.
|
||||
* @brief The callback type which is called when the mempool "repacks" its data.
|
||||
*
|
||||
* The callback needs to update users of the data to stop accessing the object
|
||||
* from the old location and access it using the new location instead. The copy
|
||||
* of memory is taken care of by the mempool.
|
||||
* @details I.e. moves it around to optimize the way it is stored in memory. This is
|
||||
* useful to improve data locality and to free internal pools back to the OS.
|
||||
*
|
||||
* @note The callback needs to update users of the data to stop accessing the object
|
||||
* from the old location and access it using the new location instead. The copy
|
||||
* of memory is taken care of by the mempool.
|
||||
*/
|
||||
typedef void (*Eina_Mempool_Repack_Cb)(void *dst, void *src, void *data);
|
||||
|
||||
EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE;
|
||||
|
||||
/**
|
||||
* @brief Creates a new mempool of the given type
|
||||
*
|
||||
* @brief Create a new mempool of the given type
|
||||
*
|
||||
* @param name Name of the mempool kind to use.
|
||||
* @param context Identifier of the mempool created (for debug purposes).
|
||||
* @param options Unused. Use the variable arguments list instead to pass options to the mempool.
|
||||
* @param ... Additional options to pass to the allocator; depends entirely on the type of mempool ("int pool size" for chained and "int item_size" for one_big.
|
||||
* @param[in] name Name of the mempool kind to use.
|
||||
* @param[in] context Identifier of the mempool created (for debug purposes).
|
||||
* @param[in] options Unused. Use the variable arguments list instead to pass options to the mempool.
|
||||
* @param[in] ... Additional options to pass to the allocator; depends entirely on the type of mempool ("int pool size" for chained and "int item_size" for one_big.
|
||||
* @return Newly allocated mempool instance, NULL otherwise.
|
||||
*
|
||||
*/
|
||||
EAPI Eina_Mempool *eina_mempool_add(const char *name, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @brief Deletes the given mempool.
|
||||
*
|
||||
* @brief Delete the given mempool.
|
||||
*
|
||||
* @param mp The mempool to delete
|
||||
*
|
||||
* @param[in] mp The mempool to delete
|
||||
*/
|
||||
EAPI void eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @brief Re-allocate an amount memory by the given mempool.
|
||||
* @brief Re-allocates an amount memory by the given mempool.
|
||||
*
|
||||
* @param mp The mempool.
|
||||
* @param element The element to re-allocate.
|
||||
* @param size The size in bytes to re-allocate.
|
||||
* @return The newly re-allocated data.
|
||||
* @param[in] mp The mempool
|
||||
* @param[in] element The element to re-allocate
|
||||
* @param[in] size The size in bytes to re-allocate
|
||||
* @return The newly re-allocated data
|
||||
*
|
||||
* This function re-allocates and returns @p element with @p size bytes using the
|
||||
* mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free().
|
||||
* @note This function re-allocates and returns @p element with @p size bytes using the
|
||||
* mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free().
|
||||
* @warning No checks are done for @p mp.
|
||||
*
|
||||
* @see eina_mempool_free()
|
||||
*/
|
||||
static inline void *eina_mempool_realloc(Eina_Mempool *mp, void *element, unsigned int size) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Allocate memory using the given mempool.
|
||||
* @brief Allocates memory using the given mempool.
|
||||
*
|
||||
* @param mp The mempool.
|
||||
* @param size The size in bytes to allocate.
|
||||
* @return The newly allocated data.
|
||||
* @param[in] mp The mempool
|
||||
* @param[in] size The size in bytes to allocate
|
||||
* @return The newly allocated data
|
||||
*
|
||||
* This function allocates and returns @p size bytes using the mempool @p mp.
|
||||
* If not used anymore, the data must be freed with eina_mempool_free().
|
||||
* @note This function allocates and returns @p size bytes using the mempool @p mp.
|
||||
* If not used anymore, the data must be freed with eina_mempool_free().
|
||||
* @warning No checks are done for @p mp.
|
||||
*
|
||||
* @see eina_mempool_free()
|
||||
*/
|
||||
static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Allocate and zero memory using the given mempool.
|
||||
*
|
||||
* @param mp The mempool.
|
||||
* @param size The size in bytes to allocate.
|
||||
* @return The newly allocated data.
|
||||
* @param[in] mp The mempool
|
||||
* @param[in] size The size in bytes to allocate
|
||||
* @return The newly allocated data
|
||||
*
|
||||
* This function allocates, zeroes, and returns @p size bytes using the mempool @p mp.
|
||||
* If not used anymore, the data must be freed with eina_mempool_free().
|
||||
* @details This function allocates, zeroes, and returns @p size bytes using the mempool @p mp.
|
||||
* If not used anymore, the data must be freed with eina_mempool_free().
|
||||
* @warning No checks are done for @p mp.
|
||||
*
|
||||
* @since 1.2
|
||||
*
|
||||
* @see eina_mempool_free()
|
||||
*/
|
||||
static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Free resources previously allocated by the given mempool.
|
||||
*
|
||||
* @param mp The mempool.
|
||||
* @param element The data to free.
|
||||
* @param[in] mp The mempool
|
||||
* @param[in] element The data to free
|
||||
*
|
||||
* @details This function frees @p element allocated by @p mp. @p element must
|
||||
* have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or
|
||||
* eina_mempool_realloc().
|
||||
*
|
||||
* This function frees @p element allocated by @p mp. @p element must
|
||||
* have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or
|
||||
* eina_mempool_realloc().
|
||||
* @warning No checks are done for @p mp.
|
||||
*
|
||||
* @see eina_mempool_malloc()
|
||||
* @see eina_mempool_calloc()
|
||||
* @see eina_mempool_realloc()
|
||||
*/
|
||||
static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @brief Repack the objects in the mempool.
|
||||
* @brief Repacks the objects in the mempool.
|
||||
*
|
||||
* @param mp The mempool
|
||||
* @param cb A callback to update the pointers the objects with their new location.
|
||||
* @param data Data to pass as third argument to @p cb.
|
||||
* @param[in] mp The mempool
|
||||
* @param[in] cb A callback to update the pointers the objects with their new location
|
||||
* @param[in] data Data to pass as third argument to @p cb
|
||||
*
|
||||
* @see Eina_Mempool_Repack_Cb
|
||||
* @see _Eina_Mempool_Backend
|
||||
*
|
||||
*/
|
||||
EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
*
|
||||
* @brief Run a garbage collection cycle.
|
||||
*
|
||||
* @param mp The mempool
|
||||
*
|
||||
* @param[in] mp The mempool
|
||||
*/
|
||||
EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
*
|
||||
* @brief Have the backend update its internal statistics.
|
||||
*
|
||||
* @param mp The mempool
|
||||
* @param[in] mp The mempool
|
||||
*
|
||||
*/
|
||||
EAPI void eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @brief Registers the given memory pool backend.
|
||||
*
|
||||
* @brief Register the given memory pool backend.
|
||||
*
|
||||
* @param be The backend
|
||||
* @param[in] be The backend
|
||||
* @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE
|
||||
* otherwise.
|
||||
*
|
||||
* otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @brief Unregisters the given memory pool backend.
|
||||
*
|
||||
* @brief Unregister the given memory pool backend.
|
||||
*
|
||||
* @param be The backend
|
||||
*
|
||||
* @param[in] be The backend
|
||||
*/
|
||||
EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @brief Computers the alignment that would be used when allocating a object of size @p size.
|
||||
*
|
||||
* @brief Computer the alignment that would be used when allocating a object of size @p size.
|
||||
*
|
||||
* @param size
|
||||
* @param[in] size
|
||||
* @return The alignment for an allocation of size @p size.
|
||||
*
|
||||
*/
|
||||
static inline unsigned int eina_mempool_alignof(unsigned int size);
|
||||
|
||||
#include "eina_inline_mempool.x"
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue