1.1 --- a/ucx/mempool.h Fri Aug 09 11:32:10 2013 +0200 1.2 +++ b/ucx/mempool.h Fri Aug 09 14:36:54 2013 +0200 1.3 @@ -26,6 +26,15 @@ 1.4 * POSSIBILITY OF SUCH DAMAGE. 1.5 */ 1.6 1.7 +/** 1.8 + * @file mempool.h 1.9 + * 1.10 + * Memory pool implementation. 1.11 + * 1.12 + * @author Mike Becker 1.13 + * @author Olaf Wintermann 1.14 + */ 1.15 + 1.16 #ifndef UCX_MEMPOOL_H 1.17 #define UCX_MEMPOOL_H 1.18 1.19 @@ -37,29 +46,154 @@ 1.20 extern "C" { 1.21 #endif 1.22 1.23 +/** 1.24 + * A function pointer to a destructor function. 1.25 + * @see ucx_mempool_setdestr() 1.26 + * @see ucx_mempool_regdestr() 1.27 + */ 1.28 typedef void(*ucx_destructor)(void*); 1.29 1.30 +/** 1.31 + * UCX mempool structure. 1.32 + */ 1.33 typedef struct { 1.34 + /** List of pointers to pooled memory. */ 1.35 void **data; 1.36 + /** Count of pooled memory items. */ 1.37 size_t ndata; 1.38 + /** Memory pool size. */ 1.39 size_t size; 1.40 } UcxMempool; 1.41 1.42 +/** Shorthand for a new default memory pool with a capacity of 16 elements. */ 1.43 +#define ucx_mempool_new_default() ucx_mempool_new(16) 1.44 1.45 -#define ucx_mempool_new_default() ucx_mempool_new(16) 1.46 + 1.47 +/** 1.48 + * Creates a memory pool with the specified initial size. 1.49 + * 1.50 + * As the created memory pool automatically grows in size by 16 elements, when 1.51 + * trying to allocate memory on a full pool, it is recommended that you use 1.52 + * a multiple of 16 for the initial size. 1.53 + * 1.54 + * @param n initial pool size (should be a multiple of 16) 1.55 + * @return a pointer to the new memory pool 1.56 + */ 1.57 UcxMempool *ucx_mempool_new(size_t n); 1.58 + 1.59 +/** 1.60 + * Resizes a memory pool. 1.61 + * 1.62 + * @param pool the pool to resize 1.63 + * @param newcap the new capacity 1.64 + * @return <code>EXIT_SUCCESS</code> on success or 1.65 + * <code>EXIT_FAILURE</code> on failure 1.66 + */ 1.67 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap); 1.68 1.69 +/** 1.70 + * Allocates pooled memory. 1.71 + * 1.72 + * @param pool the memory pool 1.73 + * @param n amount of memory to allocate 1.74 + * @return a pointer to the allocated memory 1.75 + * @see ucx_allocator_malloc() 1.76 + */ 1.77 void *ucx_mempool_malloc(UcxMempool *pool, size_t n); 1.78 +/** 1.79 + * Allocates a pooled memory array. 1.80 + * 1.81 + * The contents of the allocated memory is set to zero. 1.82 + * 1.83 + * @param pool the memory pool 1.84 + * @param nelem amount of elements to allocate 1.85 + * @param elsize amount of memory per element 1.86 + * @return a pointer to the allocated memory 1.87 + * @see ucx_allocator_calloc() 1.88 + */ 1.89 void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize); 1.90 +/** 1.91 + * Reallocates pooled memory. 1.92 + * 1.93 + * @param pool the memory pool 1.94 + * @param ptr a pointer to the memory that shall be reallocated 1.95 + * @param n the new size of the memory 1.96 + * @return a pointer to the the location of the memory 1.97 + * @see ucx_allocator_realloc() 1.98 + */ 1.99 void *ucx_mempool_realloc(UcxMempool *pool, void *ptr, size_t n); 1.100 +/** 1.101 + * Frees pooled memory. 1.102 + * 1.103 + * Before freeing the memory, the specified destructor function (if any) 1.104 + * is called. 1.105 + * 1.106 + * If you specify memory, that is not pooled by the specified memory pool, this 1.107 + * is considered as a severe error and an error message is written to 1.108 + * <code>stderr</code> and the application is shut down with code 1.109 + * <code>EXIT_FAILURE</code>. 1.110 + * 1.111 + * @param pool the memory pool 1.112 + * @param ptr a pointer to the memory that shall be freed 1.113 + * @see ucx_mempool_set_destr() 1.114 + */ 1.115 void ucx_mempool_free(UcxMempool *pool, void *ptr); 1.116 1.117 +/** 1.118 + * Destroys a memory pool. 1.119 + * 1.120 + * For each element the destructor function (if any) is called and the element 1.121 + * is freed. 1.122 + * 1.123 + * Each of the registered destructor function that has no corresponding element 1.124 + * within the pool (namely those registered by ucx_mempool_reg_destr) is 1.125 + * called interleaving with the element destruction, but with guarantee to the 1.126 + * order in which they were registered (FIFO order). 1.127 + * 1.128 + * 1.129 + * @param pool the mempool to destroy 1.130 + */ 1.131 void ucx_mempool_destroy(UcxMempool *pool); 1.132 1.133 +/** 1.134 + * Sets a destructor function for the specified memory. 1.135 + * 1.136 + * The destructor is automatically called when the memory is freed or the 1.137 + * pool is destroyed. 1.138 + * 1.139 + * The only requirement for the specified memory is, that it <b>MUST</b> be 1.140 + * pooled memory by an UcxMempool or an element-compatible mempool. The pointer 1.141 + * to the destructor function is saved in a reserved area before the actual 1.142 + * memory. 1.143 + * 1.144 + * @param ptr pooled memory 1.145 + * @param func a pointer to the destructor function 1.146 + * @see ucx_mempool_free() 1.147 + * @see ucx_mempool_destroy() 1.148 + */ 1.149 void ucx_mempool_set_destr(void *ptr, ucx_destructor func); 1.150 + 1.151 +/** 1.152 + * Registers a destructor function for the specified (non-pooled) memory. 1.153 + * 1.154 + * This is useful, if you have memory that has not been allocated by a mempool, 1.155 + * but shall be managed by a mempool. 1.156 + * 1.157 + * This function creates an entry in the specified mempool and the memory will 1.158 + * therefore (logically) convert to pooled memory. 1.159 + * 1.160 + * @param pool the memory pool 1.161 + * @param ptr data the destructor is registered for 1.162 + * @param destr a pointer to the destructor function 1.163 + */ 1.164 void ucx_mempool_reg_destr(UcxMempool *pool, void *ptr, ucx_destructor destr); 1.165 1.166 +/** 1.167 + * Creates an UcxAllocator based on an UcxMempool. 1.168 + * 1.169 + * @param pool the mempool to create the UcxAllocator for 1.170 + * @return a new UcxAllocator based on the specified pool 1.171 + */ 1.172 UcxAllocator* ucx_mempool_allocator(UcxMempool *pool); 1.173 1.174 #ifdef __cplusplus