Mercurial > hg > toolkit / file diff

--- a/ucx/cx/mempool.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/mempool.h	Sun Jan 05 22:00:39 2025 +0100
@@ -26,11 +26,11 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file mempool.h
- * \brief Interface for memory pool implementations.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file mempool.h
+ * @brief Interface for memory pool implementations.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 #ifndef UCX_MEMPOOL_H
@@ -76,35 +76,33 @@
 typedef struct cx_mempool_s CxMempool;
 
 /**
+ * Deallocates a memory pool and frees the managed memory.
+ *
+ * @param pool the memory pool to free
+ */
+void cxMempoolFree(CxMempool *pool);
+
+/**
  * Creates an array-based memory pool with a shared destructor function.
  *
  * This destructor MUST NOT free the memory.
  *
  * @param capacity the initial capacity of the pool
- * @param destr the destructor function to use for allocated memory
- * @return the created memory pool or \c NULL if allocation failed
+ * @param destr optional destructor function to use for allocated memory
+ * @return the created memory pool or @c NULL if allocation failed
  */
-__attribute__((__warn_unused_result__))
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc(cxMempoolFree, 1)
 CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr);
 
 /**
  * Creates a basic array-based memory pool.
  *
- * @param capacity the initial capacity of the pool
- * @return the created memory pool or \c NULL if allocation failed
+ * @param capacity (@c size_t) the initial capacity of the pool
+ * @return (@c CxMempool*) the created memory pool or @c NULL if allocation failed
  */
-__attribute__((__warn_unused_result__))
-static inline CxMempool *cxBasicMempoolCreate(size_t capacity) {
-    return cxMempoolCreate(capacity, NULL);
-}
-
-/**
- * Destroys a memory pool and frees the managed memory.
- *
- * @param pool the memory pool to destroy
- */
-__attribute__((__nonnull__))
-void cxMempoolDestroy(CxMempool *pool);
+#define cxBasicMempoolCreate(capacity) cxMempoolCreate(capacity, NULL)
 
 /**
  * Sets the destructor function for a specific allocated memory object.
@@ -115,13 +113,24 @@
  * @param memory the object allocated in the pool
  * @param fnc the destructor function
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxMempoolSetDestructor(
         void *memory,
         cx_destructor_func fnc
 );
 
 /**
+ * Removes the destructor function for a specific allocated memory object.
+ *
+ * If the memory is not managed by a UCX memory pool, the behavior is undefined.
+ * The destructor MUST NOT free the memory.
+ *
+ * @param memory the object allocated in the pool
+ */
+cx_attr_nonnull
+void cxMempoolRemoveDestructor(void *memory);
+
+/**
  * Registers foreign memory with this pool.
  *
  * The destructor, in contrast to memory allocated by the pool, MUST free the memory.
@@ -130,11 +139,12 @@
  * If that allocation fails, this function will return non-zero.
  *
  * @param pool the pool
- * @param memory the object allocated in the pool
+ * @param memory the object to register (MUST NOT be already allocated in the pool)
  * @param destr the destructor function
- * @return zero on success, non-zero on failure
+ * @retval zero success
+ * @retval non-zero failure
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxMempoolRegister(
         CxMempool *pool,
         void *memory,