comparison: src/cx/mempool.h
src/cx/mempool.h
- changeset 985
- 68754c7de906
- parent 890
- 54565fd74e74
equal
deleted
inserted
replaced
| 984:e8f354a25ac8 | 985:68754c7de906 |
|---|---|
| 74 * Common type for all memory pool implementations. | 74 * Common type for all memory pool implementations. |
| 75 */ | 75 */ |
| 76 typedef struct cx_mempool_s CxMempool; | 76 typedef struct cx_mempool_s CxMempool; |
| 77 | 77 |
| 78 /** | 78 /** |
| 79 * Destroys a memory pool and frees the managed memory. | |
| 80 * | |
| 81 * @param pool the memory pool to destroy | |
| 82 */ | |
| 83 void cxMempoolDestroy(CxMempool *pool); | |
| 84 | |
| 85 /** | |
| 79 * Creates an array-based memory pool with a shared destructor function. | 86 * Creates an array-based memory pool with a shared destructor function. |
| 80 * | 87 * |
| 81 * This destructor MUST NOT free the memory. | 88 * This destructor MUST NOT free the memory. |
| 82 * | 89 * |
| 83 * @param capacity the initial capacity of the pool | 90 * @param capacity the initial capacity of the pool |
| 84 * @param destr the destructor function to use for allocated memory | 91 * @param destr optional destructor function to use for allocated memory |
| 85 * @return the created memory pool or \c NULL if allocation failed | 92 * @return the created memory pool or \c NULL if allocation failed |
| 86 */ | 93 */ |
| 87 __attribute__((__warn_unused_result__)) | 94 cx_attr_nodiscard |
| 95 cx_attr_malloc | |
| 96 cx_attr_dealloc(cxMempoolDestroy, 1) | |
| 88 CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr); | 97 CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr); |
| 89 | 98 |
| 90 /** | 99 /** |
| 91 * Creates a basic array-based memory pool. | 100 * Creates a basic array-based memory pool. |
| 92 * | 101 * |
| 93 * @param capacity the initial capacity of the pool | 102 * @param capacity the initial capacity of the pool |
| 94 * @return the created memory pool or \c NULL if allocation failed | 103 * @return the created memory pool or \c NULL if allocation failed |
| 95 */ | 104 */ |
| 96 __attribute__((__warn_unused_result__)) | 105 #define cxBasicMempoolCreate(capacity) cxMempoolCreate(capacity, NULL) |
| 97 static inline CxMempool *cxBasicMempoolCreate(size_t capacity) { | |
| 98 return cxMempoolCreate(capacity, NULL); | |
| 99 } | |
| 100 | |
| 101 /** | |
| 102 * Destroys a memory pool and frees the managed memory. | |
| 103 * | |
| 104 * @param pool the memory pool to destroy | |
| 105 */ | |
| 106 __attribute__((__nonnull__)) | |
| 107 void cxMempoolDestroy(CxMempool *pool); | |
| 108 | 106 |
| 109 /** | 107 /** |
| 110 * Sets the destructor function for a specific allocated memory object. | 108 * Sets the destructor function for a specific allocated memory object. |
| 111 * | 109 * |
| 112 * If the memory is not managed by a UCX memory pool, the behavior is undefined. | 110 * If the memory is not managed by a UCX memory pool, the behavior is undefined. |
| 113 * The destructor MUST NOT free the memory. | 111 * The destructor MUST NOT free the memory. |
| 114 * | 112 * |
| 115 * @param memory the object allocated in the pool | 113 * @param memory the object allocated in the pool |
| 116 * @param fnc the destructor function | 114 * @param fnc the destructor function |
| 117 */ | 115 */ |
| 118 __attribute__((__nonnull__)) | 116 cx_attr_nonnull |
| 119 void cxMempoolSetDestructor( | 117 void cxMempoolSetDestructor( |
| 120 void *memory, | 118 void *memory, |
| 121 cx_destructor_func fnc | 119 cx_destructor_func fnc |
| 122 ); | 120 ); |
| 121 | |
| 122 /** | |
| 123 * Removes the destructor function for a specific allocated memory object. | |
| 124 * | |
| 125 * If the memory is not managed by a UCX memory pool, the behavior is undefined. | |
| 126 * The destructor MUST NOT free the memory. | |
| 127 * | |
| 128 * @param memory the object allocated in the pool | |
| 129 */ | |
| 130 cx_attr_nonnull | |
| 131 void cxMempoolRemoveDestructor(void *memory); | |
| 123 | 132 |
| 124 /** | 133 /** |
| 125 * Registers foreign memory with this pool. | 134 * Registers foreign memory with this pool. |
| 126 * | 135 * |
| 127 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. | 136 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. |
| 128 * | 137 * |
| 129 * A small portion of memory will be allocated to register the information in the pool. | 138 * A small portion of memory will be allocated to register the information in the pool. |
| 130 * If that allocation fails, this function will return non-zero. | 139 * If that allocation fails, this function will return non-zero. |
| 131 * | 140 * |
| 132 * @param pool the pool | 141 * @param pool the pool |
| 133 * @param memory the object allocated in the pool | 142 * @param memory the object to register (MUST NOT be already allocated in the pool) |
| 134 * @param destr the destructor function | 143 * @param destr the destructor function |
| 135 * @return zero on success, non-zero on failure | 144 * @return zero on success, non-zero on failure |
| 136 */ | 145 */ |
| 137 __attribute__((__nonnull__)) | 146 cx_attr_nonnull |
| 138 int cxMempoolRegister( | 147 int cxMempoolRegister( |
| 139 CxMempool *pool, | 148 CxMempool *pool, |
| 140 void *memory, | 149 void *memory, |
| 141 cx_destructor_func destr | 150 cx_destructor_func destr |
| 142 ); | 151 ); |
