68 |
68 |
69 |
69 |
70 /** |
70 /** |
71 * Creates a memory pool with the specified initial size. |
71 * Creates a memory pool with the specified initial size. |
72 * |
72 * |
73 * As the created memory pool automatically grows in size by 16 elements, when |
73 * As the created memory pool automatically grows in size by factor two when |
74 * trying to allocate memory on a full pool, it is recommended that you use |
74 * trying to allocate memory on a full pool, it is recommended that you use |
75 * a multiple of 16 for the initial size. |
75 * a power of two for the initial size. |
76 * |
76 * |
77 * @param n initial pool size (should be a multiple of 16) |
77 * @param n initial pool size (should be a power of two, e.g. 16) |
78 * @return a pointer to the new memory pool |
78 * @return a pointer to the new memory pool |
|
79 * @see ucx_mempool_new_default() |
79 */ |
80 */ |
80 UcxMempool *ucx_mempool_new(size_t n); |
81 UcxMempool *ucx_mempool_new(size_t n); |
81 |
82 |
82 /** |
83 /** |
83 * Resizes a memory pool. |
84 * Resizes a memory pool. |
|
85 * |
|
86 * This function will fail if the new capacity is not sufficient for the |
|
87 * present data. |
84 * |
88 * |
85 * @param pool the pool to resize |
89 * @param pool the pool to resize |
86 * @param newcap the new capacity |
90 * @param newcap the new capacity |
87 * @return <code>EXIT_SUCCESS</code> on success or |
91 * @return zero on success or non-zero on failure |
88 * <code>EXIT_FAILURE</code> on failure |
|
89 */ |
92 */ |
90 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap); |
93 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap); |
91 |
|
92 /** |
|
93 * Changes the pool size to the next smallest multiple of 16. |
|
94 * |
|
95 * You may use this macro, to reduce the pool size after freeing |
|
96 * many pooled memory items. |
|
97 * |
|
98 * @param pool the pool to clamp |
|
99 * @return <code>EXIT_SUCCESS</code> on success or |
|
100 * <code>EXIT_FAILURE</code> on failure |
|
101 */ |
|
102 #define ucx_mempool_clamp(pool) ucx_mempool_chcap(pool, \ |
|
103 (pool->ndata & ~0xF)+0x10) |
|
104 |
94 |
105 /** |
95 /** |
106 * Allocates pooled memory. |
96 * Allocates pooled memory. |
107 * |
97 * |
108 * @param pool the memory pool |
98 * @param pool the memory pool |
143 * |
133 * |
144 * Before freeing the memory, the specified destructor function (if any) |
134 * Before freeing the memory, the specified destructor function (if any) |
145 * is called. |
135 * is called. |
146 * |
136 * |
147 * If you specify memory, that is not pooled by the specified memory pool, the |
137 * If you specify memory, that is not pooled by the specified memory pool, the |
148 * behavior is undefined. |
138 * program will terminate with a call to <code>abort()</code>. |
149 * |
139 * |
150 * @param pool the memory pool |
140 * @param pool the memory pool |
151 * @param ptr a pointer to the memory that shall be freed |
141 * @param ptr a pointer to the memory that shall be freed |
152 * @see ucx_mempool_set_destr() |
142 * @see ucx_mempool_set_destr() |
153 */ |
143 */ |