| 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 |