154 /** |
154 /** |
155 * Deallocates a memory pool and frees the managed memory. |
155 * Deallocates a memory pool and frees the managed memory. |
156 * |
156 * |
157 * @param pool the memory pool to free |
157 * @param pool the memory pool to free |
158 */ |
158 */ |
159 cx_attr_export |
159 CX_EXPORT void cxMempoolFree(CxMempool *pool); |
160 void cxMempoolFree(CxMempool *pool); |
|
161 |
160 |
162 /** |
161 /** |
163 * Creates an array-based memory pool. |
162 * Creates an array-based memory pool. |
164 * |
163 * |
165 * The type determines how much additional memory is allocated per block |
164 * The type determines how much additional memory is allocated per block |
167 * |
166 * |
168 * @param capacity the initial capacity of the pool (an implementation default if zero) |
167 * @param capacity the initial capacity of the pool (an implementation default if zero) |
169 * @param type the type of memory pool |
168 * @param type the type of memory pool |
170 * @return the created memory pool or @c NULL if allocation failed |
169 * @return the created memory pool or @c NULL if allocation failed |
171 */ |
170 */ |
172 cx_attr_nodiscard |
171 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxMempoolFree, 1) |
173 cx_attr_malloc |
172 CX_EXPORT CxMempool *cxMempoolCreate(size_t capacity, enum cx_mempool_type type); |
174 cx_attr_dealloc(cxMempoolFree, 1) |
|
175 cx_attr_export |
|
176 CxMempool *cxMempoolCreate(size_t capacity, enum cx_mempool_type type); |
|
177 |
173 |
178 /** |
174 /** |
179 * Creates a basic array-based memory pool. |
175 * Creates a basic array-based memory pool. |
180 * |
176 * |
181 * Convenience macro to create a memory pool of type #CX_MEMPOOL_TYPE_SIMPLE. |
177 * Convenience macro to create a memory pool of type #CX_MEMPOOL_TYPE_SIMPLE. |
210 * |
206 * |
211 * @param pool the memory pool |
207 * @param pool the memory pool |
212 * @param fnc the destructor that shall be applied to all memory blocks |
208 * @param fnc the destructor that shall be applied to all memory blocks |
213 */ |
209 */ |
214 cx_attr_nonnull_arg(1) |
210 cx_attr_nonnull_arg(1) |
215 cx_attr_export |
211 CX_EXPORT void cxMempoolGlobalDestructor(CxMempool *pool, cx_destructor_func fnc); |
216 void cxMempoolGlobalDestructor(CxMempool *pool, cx_destructor_func fnc); |
|
217 |
212 |
218 /** |
213 /** |
219 * Sets the global destructor for all memory blocks within the specified pool. |
214 * Sets the global destructor for all memory blocks within the specified pool. |
220 * |
215 * |
221 * @param pool the memory pool |
216 * @param pool the memory pool |
222 * @param fnc the destructor that shall be applied to all memory blocks |
217 * @param fnc the destructor that shall be applied to all memory blocks |
223 * @param data additional data for the destructor function |
218 * @param data additional data for the destructor function |
224 */ |
219 */ |
225 cx_attr_nonnull_arg(1) |
220 cx_attr_nonnull_arg(1) |
226 cx_attr_export |
221 CX_EXPORT void cxMempoolGlobalDestructor2(CxMempool *pool, cx_destructor_func2 fnc, void *data); |
227 void cxMempoolGlobalDestructor2(CxMempool *pool, cx_destructor_func2 fnc, void *data); |
|
228 |
222 |
229 /** |
223 /** |
230 * Sets the destructor function for a specific allocated memory object. |
224 * Sets the destructor function for a specific allocated memory object. |
231 * |
225 * |
232 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. |
226 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. |
235 * |
229 * |
236 * @param memory the object allocated in the pool |
230 * @param memory the object allocated in the pool |
237 * @param fnc the destructor function |
231 * @param fnc the destructor function |
238 */ |
232 */ |
239 cx_attr_nonnull |
233 cx_attr_nonnull |
240 cx_attr_export |
234 CX_EXPORT void cxMempoolSetDestructor(void *memory, cx_destructor_func fnc); |
241 void cxMempoolSetDestructor( |
|
242 void *memory, |
|
243 cx_destructor_func fnc |
|
244 ); |
|
245 |
235 |
246 /** |
236 /** |
247 * Sets the destructor function for a specific allocated memory object. |
237 * Sets the destructor function for a specific allocated memory object. |
248 * |
238 * |
249 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. |
239 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. |
253 * @param memory the object allocated in the pool |
243 * @param memory the object allocated in the pool |
254 * @param fnc the destructor function |
244 * @param fnc the destructor function |
255 * @param data additional data for the destructor function |
245 * @param data additional data for the destructor function |
256 */ |
246 */ |
257 cx_attr_nonnull |
247 cx_attr_nonnull |
258 cx_attr_export |
248 CX_EXPORT void cxMempoolSetDestructor2(void *memory, cx_destructor_func2 fnc, void *data); |
259 void cxMempoolSetDestructor2( |
|
260 void *memory, |
|
261 cx_destructor_func2 fnc, |
|
262 void *data |
|
263 ); |
|
264 |
249 |
265 /** |
250 /** |
266 * Removes the destructor function for a specific allocated memory object. |
251 * Removes the destructor function for a specific allocated memory object. |
267 * |
252 * |
268 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. |
253 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. |
269 * If the memory is not managed by a UCX memory pool, the behavior is undefined. |
254 * If the memory is not managed by a UCX memory pool, the behavior is undefined. |
270 * |
255 * |
271 * @param memory the object allocated in the pool |
256 * @param memory the object allocated in the pool |
272 */ |
257 */ |
273 cx_attr_nonnull |
258 cx_attr_nonnull |
274 cx_attr_export |
259 CX_EXPORT void cxMempoolRemoveDestructor(void *memory); |
275 void cxMempoolRemoveDestructor(void *memory); |
|
276 |
260 |
277 /** |
261 /** |
278 * Removes the destructor function for a specific allocated memory object. |
262 * Removes the destructor function for a specific allocated memory object. |
279 * |
263 * |
280 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. |
264 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. |
281 * If the memory is not managed by a UCX memory pool, the behavior is undefined. |
265 * If the memory is not managed by a UCX memory pool, the behavior is undefined. |
282 * |
266 * |
283 * @param memory the object allocated in the pool |
267 * @param memory the object allocated in the pool |
284 */ |
268 */ |
285 cx_attr_nonnull |
269 cx_attr_nonnull |
286 cx_attr_export |
270 CX_EXPORT void cxMempoolRemoveDestructor2(void *memory); |
287 void cxMempoolRemoveDestructor2(void *memory); |
|
288 |
271 |
289 /** |
272 /** |
290 * Registers foreign memory with this pool. |
273 * Registers foreign memory with this pool. |
291 * |
274 * |
292 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. |
275 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. |
300 * @param destr the destructor function |
283 * @param destr the destructor function |
301 * @retval zero success |
284 * @retval zero success |
302 * @retval non-zero failure |
285 * @retval non-zero failure |
303 */ |
286 */ |
304 cx_attr_nonnull |
287 cx_attr_nonnull |
305 cx_attr_export |
288 CX_EXPORT int cxMempoolRegister(CxMempool *pool, void *memory, cx_destructor_func destr); |
306 int cxMempoolRegister( |
|
307 CxMempool *pool, |
|
308 void *memory, |
|
309 cx_destructor_func destr |
|
310 ); |
|
311 |
289 |
312 |
290 |
313 /** |
291 /** |
314 * Registers foreign memory with this pool. |
292 * Registers foreign memory with this pool. |
315 * |
293 * |
328 * @param data additional data for the destructor function |
306 * @param data additional data for the destructor function |
329 * @retval zero success |
307 * @retval zero success |
330 * @retval non-zero failure |
308 * @retval non-zero failure |
331 */ |
309 */ |
332 cx_attr_nonnull |
310 cx_attr_nonnull |
333 cx_attr_export |
311 CX_EXPORT int cxMempoolRegister2(CxMempool *pool, void *memory, cx_destructor_func2 destr, void *data); |
334 int cxMempoolRegister2( |
|
335 CxMempool *pool, |
|
336 void *memory, |
|
337 cx_destructor_func2 destr, |
|
338 void *data |
|
339 ); |
|
340 |
312 |
341 /** |
313 /** |
342 * Transfers all the memory managed by one pool to another. |
314 * Transfers all the memory managed by one pool to another. |
343 * |
315 * |
344 * The allocator of the source pool will also be transferred and registered with the destination pool |
316 * The allocator of the source pool will also be transferred and registered with the destination pool |
352 * @param dest the pool where to transfer the memory to |
324 * @param dest the pool where to transfer the memory to |
353 * @retval zero success |
325 * @retval zero success |
354 * @retval non-zero allocation failure or incompatible pools |
326 * @retval non-zero allocation failure or incompatible pools |
355 */ |
327 */ |
356 cx_attr_nonnull |
328 cx_attr_nonnull |
357 cx_attr_export |
329 CX_EXPORT int cxMempoolTransfer(CxMempool *source, CxMempool *dest); |
358 int cxMempoolTransfer( |
|
359 CxMempool *source, |
|
360 CxMempool *dest |
|
361 ); |
|
362 |
330 |
363 /** |
331 /** |
364 * Transfers an object from one pool to another. |
332 * Transfers an object from one pool to another. |
365 * |
333 * |
366 * This function fails when the destination pool has a different type than the source pool. |
334 * This function fails when the destination pool has a different type than the source pool. |
373 * @param obj pointer to the object that shall be transferred |
341 * @param obj pointer to the object that shall be transferred |
374 * @retval zero success |
342 * @retval zero success |
375 * @retval non-zero failure, or the object was not found in the source pool, or the pools are incompatible |
343 * @retval non-zero failure, or the object was not found in the source pool, or the pools are incompatible |
376 */ |
344 */ |
377 cx_attr_nonnull |
345 cx_attr_nonnull |
378 cx_attr_export |
346 CX_EXPORT int cxMempoolTransferObject(CxMempool *source, CxMempool *dest, const void *obj); |
379 int cxMempoolTransferObject( |
|
380 CxMempool *source, |
|
381 CxMempool *dest, |
|
382 const void *obj |
|
383 ); |
|
384 |
347 |
385 #ifdef __cplusplus |
348 #ifdef __cplusplus |
386 } // extern "C" |
349 } // extern "C" |
387 #endif |
350 #endif |
388 |
351 |