src/cx/mempool.h

changeset 1675
36c0fb2b60b2
parent 1426
3a89b31f0724
equal deleted inserted replaced
1674:8b0f162ac88e 1675:36c0fb2b60b2
36 #ifndef UCX_MEMPOOL_H 36 #ifndef UCX_MEMPOOL_H
37 #define UCX_MEMPOOL_H 37 #define UCX_MEMPOOL_H
38 38
39 #include "common.h" 39 #include "common.h"
40 #include "allocator.h" 40 #include "allocator.h"
41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 41
46 /** A memory block in a simple memory pool. */ 42 /** A memory block in a simple memory pool. */
47 struct cx_mempool_memory_s { 43 struct cx_mempool_memory_s {
48 /** The destructor. */ 44 /** The destructor. */
49 cx_destructor_func destructor; 45 cx_destructor_func destructor;
154 /** 150 /**
155 * Deallocates a memory pool and frees the managed memory. 151 * Deallocates a memory pool and frees the managed memory.
156 * 152 *
157 * @param pool the memory pool to free 153 * @param pool the memory pool to free
158 */ 154 */
159 CX_EXPORT void cxMempoolFree(CxMempool *pool); 155 CX_EXTERN
156 void cxMempoolFree(CxMempool *pool);
160 157
161 /** 158 /**
162 * Creates an array-based memory pool. 159 * Creates an array-based memory pool.
163 * 160 *
164 * The type determines how much additional memory is allocated per block 161 * The type determines how much additional memory is allocated per block
166 * 163 *
167 * @param capacity the initial capacity of the pool (an implementation default if zero) 164 * @param capacity the initial capacity of the pool (an implementation default if zero)
168 * @param type the type of memory pool 165 * @param type the type of memory pool
169 * @return the created memory pool or @c NULL if allocation failed 166 * @return the created memory pool or @c NULL if allocation failed
170 */ 167 */
171 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxMempoolFree, 1) 168 CX_EXTERN CX_NODISCARD CX_MALLOC CX_DEALLOC(cxMempoolFree, 1)
172 CX_EXPORT CxMempool *cxMempoolCreate(size_t capacity, enum cx_mempool_type type); 169 CxMempool *cxMempoolCreate(size_t capacity, enum cx_mempool_type type);
173 170
174 /** 171 /**
175 * Creates a basic array-based memory pool. 172 * Creates a basic array-based memory pool.
176 * 173 *
177 * Convenience macro to create a memory pool of type #CX_MEMPOOL_TYPE_SIMPLE. 174 * Convenience macro to create a memory pool of type #CX_MEMPOOL_TYPE_SIMPLE.
205 * Sets the global destructor for all memory blocks within the specified pool. 202 * Sets the global destructor for all memory blocks within the specified pool.
206 * 203 *
207 * @param pool the memory pool 204 * @param pool the memory pool
208 * @param fnc the destructor that shall be applied to all memory blocks 205 * @param fnc the destructor that shall be applied to all memory blocks
209 */ 206 */
210 cx_attr_nonnull_arg(1) 207 CX_EXTERN CX_NONNULL_ARG(1)
211 CX_EXPORT void cxMempoolGlobalDestructor(CxMempool *pool, cx_destructor_func fnc); 208 void cxMempoolGlobalDestructor(CxMempool *pool, cx_destructor_func fnc);
212 209
213 /** 210 /**
214 * Sets the global destructor for all memory blocks within the specified pool. 211 * Sets the global destructor for all memory blocks within the specified pool.
215 * 212 *
216 * @param pool the memory pool 213 * @param pool the memory pool
217 * @param fnc the destructor that shall be applied to all memory blocks 214 * @param fnc the destructor that shall be applied to all memory blocks
218 * @param data additional data for the destructor function 215 * @param data additional data for the destructor function
219 */ 216 */
220 cx_attr_nonnull_arg(1) 217 CX_EXTERN CX_NONNULL_ARG(1)
221 CX_EXPORT void cxMempoolGlobalDestructor2(CxMempool *pool, cx_destructor_func2 fnc, void *data); 218 void cxMempoolGlobalDestructor2(CxMempool *pool, cx_destructor_func2 fnc, void *data);
222 219
223 /** 220 /**
224 * Sets the destructor function for a specific allocated memory object. 221 * Sets the destructor function for a specific allocated memory object.
225 * 222 *
226 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. 223 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined.
228 * The destructor MUST NOT free the memory. 225 * The destructor MUST NOT free the memory.
229 * 226 *
230 * @param memory the object allocated in the pool 227 * @param memory the object allocated in the pool
231 * @param fnc the destructor function 228 * @param fnc the destructor function
232 */ 229 */
233 cx_attr_nonnull 230 CX_EXTERN CX_NONNULL
234 CX_EXPORT void cxMempoolSetDestructor(void *memory, cx_destructor_func fnc); 231 void cxMempoolSetDestructor(void *memory, cx_destructor_func fnc);
235 232
236 /** 233 /**
237 * Sets the destructor function for a specific allocated memory object. 234 * Sets the destructor function for a specific allocated memory object.
238 * 235 *
239 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. 236 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined.
242 * 239 *
243 * @param memory the object allocated in the pool 240 * @param memory the object allocated in the pool
244 * @param fnc the destructor function 241 * @param fnc the destructor function
245 * @param data additional data for the destructor function 242 * @param data additional data for the destructor function
246 */ 243 */
247 cx_attr_nonnull 244 CX_EXTERN CX_NONNULL
248 CX_EXPORT void cxMempoolSetDestructor2(void *memory, cx_destructor_func2 fnc, void *data); 245 void cxMempoolSetDestructor2(void *memory, cx_destructor_func2 fnc, void *data);
249 246
250 /** 247 /**
251 * Removes the destructor function for a specific allocated memory object. 248 * Removes the destructor function for a specific allocated memory object.
252 * 249 *
253 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined. 250 * If the type of memory pool is not #CX_MEMPOOL_TYPE_SIMPLE, the behavior is undefined.
254 * If the memory is not managed by a UCX memory pool, the behavior is undefined. 251 * If the memory is not managed by a UCX memory pool, the behavior is undefined.
255 * 252 *
256 * @param memory the object allocated in the pool 253 * @param memory the object allocated in the pool
257 */ 254 */
258 cx_attr_nonnull 255 CX_EXTERN CX_NONNULL
259 CX_EXPORT void cxMempoolRemoveDestructor(void *memory); 256 void cxMempoolRemoveDestructor(void *memory);
260 257
261 /** 258 /**
262 * Removes the destructor function for a specific allocated memory object. 259 * Removes the destructor function for a specific allocated memory object.
263 * 260 *
264 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined. 261 * If the type of memory pool is not #CX_MEMPOOL_TYPE_ADVANCED, the behavior is undefined.
265 * If the memory is not managed by a UCX memory pool, the behavior is undefined. 262 * If the memory is not managed by a UCX memory pool, the behavior is undefined.
266 * 263 *
267 * @param memory the object allocated in the pool 264 * @param memory the object allocated in the pool
268 */ 265 */
269 cx_attr_nonnull 266 CX_EXTERN CX_NONNULL
270 CX_EXPORT void cxMempoolRemoveDestructor2(void *memory); 267 void cxMempoolRemoveDestructor2(void *memory);
271 268
272 /** 269 /**
273 * Registers foreign memory with this pool. 270 * Registers foreign memory with this pool.
274 * 271 *
275 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. 272 * The destructor, in contrast to memory allocated by the pool, MUST free the memory.
282 * @param memory the object to register (MUST NOT be already allocated in the pool) 279 * @param memory the object to register (MUST NOT be already allocated in the pool)
283 * @param destr the destructor function 280 * @param destr the destructor function
284 * @retval zero success 281 * @retval zero success
285 * @retval non-zero failure 282 * @retval non-zero failure
286 */ 283 */
287 cx_attr_nonnull 284 CX_EXTERN CX_NONNULL
288 CX_EXPORT int cxMempoolRegister(CxMempool *pool, void *memory, cx_destructor_func destr); 285 int cxMempoolRegister(CxMempool *pool, void *memory, cx_destructor_func destr);
289
290 286
291 /** 287 /**
292 * Registers foreign memory with this pool. 288 * Registers foreign memory with this pool.
293 * 289 *
294 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. 290 * The destructor, in contrast to memory allocated by the pool, MUST free the memory.
305 * @param destr the destructor function 301 * @param destr the destructor function
306 * @param data additional data for the destructor function 302 * @param data additional data for the destructor function
307 * @retval zero success 303 * @retval zero success
308 * @retval non-zero failure 304 * @retval non-zero failure
309 */ 305 */
310 cx_attr_nonnull 306 CX_EXTERN CX_NONNULL
311 CX_EXPORT int cxMempoolRegister2(CxMempool *pool, void *memory, cx_destructor_func2 destr, void *data); 307 int cxMempoolRegister2(CxMempool *pool, void *memory, cx_destructor_func2 destr, void *data);
312 308
313 /** 309 /**
314 * Transfers all the memory managed by one pool to another. 310 * Transfers all the memory managed by one pool to another.
315 * 311 *
316 * The allocator of the source pool will also be transferred and registered with the destination pool 312 * The allocator of the source pool will also be transferred and registered with the destination pool
323 * @param source the pool to move the memory from 319 * @param source the pool to move the memory from
324 * @param dest the pool where to transfer the memory to 320 * @param dest the pool where to transfer the memory to
325 * @retval zero success 321 * @retval zero success
326 * @retval non-zero allocation failure or incompatible pools 322 * @retval non-zero allocation failure or incompatible pools
327 */ 323 */
328 cx_attr_nonnull 324 CX_EXTERN CX_NONNULL
329 CX_EXPORT int cxMempoolTransfer(CxMempool *source, CxMempool *dest); 325 int cxMempoolTransfer(CxMempool *source, CxMempool *dest);
330 326
331 /** 327 /**
332 * Transfers an object from one pool to another. 328 * Transfers an object from one pool to another.
333 * 329 *
334 * This function fails when the destination pool has a different type than the source pool. 330 * This function fails when the destination pool has a different type than the source pool.
340 * @param dest the pool where to transfer the memory to 336 * @param dest the pool where to transfer the memory to
341 * @param obj pointer to the object that shall be transferred 337 * @param obj pointer to the object that shall be transferred
342 * @retval zero success 338 * @retval zero success
343 * @retval non-zero failure, or the object was not found in the source pool, or the pools are incompatible 339 * @retval non-zero failure, or the object was not found in the source pool, or the pools are incompatible
344 */ 340 */
345 cx_attr_nonnull 341 CX_EXTERN CX_NONNULL
346 CX_EXPORT int cxMempoolTransferObject(CxMempool *source, CxMempool *dest, const void *obj); 342 int cxMempoolTransferObject(CxMempool *source, CxMempool *dest, const void *obj);
347
348 #ifdef __cplusplus
349 } // extern "C"
350 #endif
351 343
352 #endif // UCX_MEMPOOL_H 344 #endif // UCX_MEMPOOL_H

mercurial