diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h index 7aaffc2652..32774cc0a1 100644 --- a/src/lib/eina/eina_mempool.h +++ b/src/lib/eina/eina_mempool.h @@ -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" -/** - * @} - */ - /** * @} */