From 020bd415058497a48fc4afa0ae814f2ebe5fa583 Mon Sep 17 00:00:00 2001 From: Adrien Nader Date: Mon, 20 Oct 2014 14:51:37 +0200 Subject: [PATCH] eina document eina mempools' API. Except for the weird _Eina_Mempool_Backend_ABI1/ABI2 work-around which is completely internal and probably is of interest to noone (the only person on Earth who will be interested in it in a decade will hate me for skipping it). --- src/lib/eina/eina_inline_mempool.x | 16 ++++++++++ src/lib/eina/eina_mempool.h | 48 +++++++++++++++++------------- 2 files changed, 44 insertions(+), 20 deletions(-) diff --git a/src/lib/eina/eina_inline_mempool.x b/src/lib/eina/eina_inline_mempool.x index c33af06971..59bf523e1e 100644 --- a/src/lib/eina/eina_inline_mempool.x +++ b/src/lib/eina/eina_inline_mempool.x @@ -27,14 +27,30 @@ typedef struct _Eina_Mempool_Backend_ABI2 Eina_Mempool_Backend_ABI2; struct _Eina_Mempool_Backend { + /** Name of the mempool backend */ const char *name; + /** Function to initialize the backend. */ void *(*init)(const char *context, const char *options, va_list args); + /** Function to free memory back to the mempool. */ void (*free)(void *data, void *element); + /** Function to allocate memory from the mempool. */ void *(*alloc)(void *data, unsigned int size); + /** Function to change the size of a block of memory that is currently + * allocated. */ void *(*realloc)(void *data, void *element, unsigned int size); + /** Function to trigger a garbage collection; can be NULL if the feature + * isn't available in the backend. */ void (*garbage_collect)(void *data); + /** Report statistics on the content of the mempool; can be NULL if the + * feature isn't available in the backend. */ void (*statistics)(void *data); + /** Function to destroy the backend, freeing memory back to the operating + * system. */ void (*shutdown)(void *data); + /** Function to optimize the placement of objects in the mempool (it's + * different from garbage_collect); can be NULL if the feature isn't + * available in the backend. + * @see Eina_Mempool_Repack_Cb */ void (*repack)(void *data, Eina_Mempool_Repack_Cb cb, void *cb_data); }; diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h index 9e1d97fcc1..7aaffc2652 100644 --- a/src/lib/eina/eina_mempool.h +++ b/src/lib/eina/eina_mempool.h @@ -71,8 +71,14 @@ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend; /** * @typedef Eina_Mempool_Repack_Cb - * Type for a callback who need to unreference an old object from a mempool - * and reference the new one instead. Memcpy is taken care by the mempool. + * + * 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. + * + * 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); @@ -80,21 +86,22 @@ EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE; /** * - * @brief TODO + * @brief Create a new mempool of the given type * - * @param module - * @param context - * @param options + * @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. * @return Newly allocated mempool instance, NULL otherwise. * */ -EAPI Eina_Mempool *eina_mempool_add(const char *module, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); +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 TODO + * @brief Delete the given mempool. * - * @param mp The mempools + * @param mp The mempool to delete * */ EAPI void eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1); @@ -154,19 +161,21 @@ static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EIN static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1); /** - * - * @brief TODO + * @brief Repack the objects in the mempool. * * @param mp The mempool - * @param cb The after repack callback - * @param data The data + * @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. + * + * @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 TODO (garbage collect) + * @brief Run a garbage collection cycle. * * @param mp The mempool * @@ -175,7 +184,7 @@ EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1); /** * - * @brief TODO + * @brief Have the backend update its internal statistics. * * @param mp The mempool * @@ -184,7 +193,7 @@ EAPI void eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1 /** * - * @brief TODO + * @brief Register the given memory pool backend. * * @param be The backend * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE @@ -195,7 +204,7 @@ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NON /** * - * @brief TODO + * @brief Unregister the given memory pool backend. * * @param be The backend * @@ -204,11 +213,10 @@ EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_N /** * - * @brief TODO + * @brief Computer the alignment that would be used when allocating a object of size @p size. * * @param size - * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE - * otherwise. + * @return The alignment for an allocation of size @p size. * */ static inline unsigned int eina_mempool_alignof(unsigned int size);