--- a/ucx/cx/allocator.h Sun Aug 31 14:39:13 2025 +0200
+++ b/ucx/cx/allocator.h Sat Nov 08 23:06:11 2025 +0100
@@ -46,36 +46,22 @@
/**
* The allocator's malloc() implementation.
*/
- void *(*malloc)(
- void *data,
- size_t n
- );
+ void *(*malloc)(void *data, size_t n);
/**
* The allocator's realloc() implementation.
*/
- void *(*realloc)(
- void *data,
- void *mem,
- size_t n
- );
+ void *(*realloc)(void *data, void *mem, size_t n);
/**
* The allocator's calloc() implementation.
*/
- void *(*calloc)(
- void *data,
- size_t nmemb,
- size_t size
- );
+ void *(*calloc)(void *data, size_t nmemb, size_t size);
/**
* The allocator's free() implementation.
*/
- void (*free)(
- void *data,
- void *mem
- );
+ void (*free)(void *data, void *mem);
} cx_allocator_class;
/**
@@ -98,10 +84,15 @@
typedef struct cx_allocator_s CxAllocator;
/**
- * A default allocator using standard library malloc() etc.
+ * A pre-defined allocator using standard library malloc() etc.
*/
-cx_attr_export
-extern const CxAllocator * const cxDefaultAllocator;
+CX_EXPORT extern const CxAllocator * const cxStdlibAllocator;
+
+/**
+ * The default allocator that is used by UCX.
+ * Initialized with cxStdlibAllocator, but you may change it.
+ */
+CX_EXPORT extern const CxAllocator * cxDefaultAllocator;
/**
* Function pointer type for destructor functions.
@@ -126,15 +117,40 @@
* @param data an optional pointer to custom data
* @param memory a pointer to the object to destruct
*/
-typedef void (*cx_destructor_func2)(
- void *data,
- void *memory
-);
+typedef void (*cx_destructor_func2)(void *data, void *memory);
+
+
+/**
+ * Function pointer type for clone functions.
+ *
+ * A clone function is supposed to create a deep copy of the memory pointed to
+ * by the @p source pointer.
+ * If the @p target pointer is non-null, the clone function is supposed to store
+ * the copy into that memory region.
+ * Otherwise, the clone function shall use the specified @p allocator to create
+ * a new object.
+ *
+ * The return value of a clone function is always a pointer to the target
+ * memory region, or @c NULL if any allocation failed.
+ * A clone function SHOULD NOT fail for any other reason than an allocation
+ * failure.
+ *
+ * @param target the target memory or @c NULL, if memory shall be allocated
+ * @param source the source memory
+ * @param allocator the allocator that shall be used
+ * @param data optional additional data
+ * @return either the specified @p target, a pointer to the allocated memory,
+ * or @c NULL, if any error occurred
+ */
+typedef void*(cx_clone_func)(void *target, const void *source,
+ const CxAllocator *allocator, void *data);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
*
+ * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
+ *
* @par Error handling
* @c errno will be set by realloc() on failure.
*
@@ -144,13 +160,8 @@
* @retval non-zero failure
* @see cx_reallocatearray()
*/
-cx_attr_nonnull
-cx_attr_nodiscard
-cx_attr_export
-int cx_reallocate_(
- void **mem,
- size_t n
-);
+cx_attr_nonnull cx_attr_nodiscard
+CX_EXPORT int cx_reallocate_(void **mem, size_t n);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
@@ -158,6 +169,8 @@
*
* The size is calculated by multiplying @p nemb and @p size.
*
+ * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
+ *
* @par Error handling
* @c errno will be set by realloc() on failure or when the multiplication of
* @p nmemb and @p size overflows.
@@ -169,19 +182,15 @@
* @retval non-zero failure
* @see cx_reallocate()
*/
-cx_attr_nonnull
-cx_attr_nodiscard
-cx_attr_export
-int cx_reallocatearray_(
- void **mem,
- size_t nmemb,
- size_t size
-);
+cx_attr_nonnull cx_attr_nodiscard
+CX_EXPORT int cx_reallocatearray_(void **mem, size_t nmemb, size_t size);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
*
+ * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
+ *
* @par Error handling
* @c errno will be set by realloc() on failure.
*
@@ -199,6 +208,8 @@
*
* The size is calculated by multiplying @p nemb and @p size.
*
+ * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
+ *
* @par Error handling
* @c errno will be set by realloc() on failure or when the multiplication of
* @p nmemb and @p size overflows.
@@ -213,6 +224,14 @@
cx_reallocatearray_((void**)(mem), nmemb, size)
/**
+ * Allocates memory and sets every byte to zero.
+ *
+ * @param n (@c size_t) the number of bytes
+ * @return (@c void*) a pointer to the allocated memory
+ */
+#define cx_zalloc(n) calloc(1, n)
+
+/**
* Free a block allocated by this allocator.
*
* @note Freeing a block of a different allocator is undefined.
@@ -221,11 +240,7 @@
* @param mem a pointer to the block to free
*/
cx_attr_nonnull_arg(1)
-cx_attr_export
-void cxFree(
- const CxAllocator *allocator,
- void *mem
-);
+CX_EXPORT void cxFree(const CxAllocator *allocator, void *mem);
/**
* Allocate @p n bytes of memory.
@@ -234,21 +249,14 @@
* @param n the number of bytes
* @return a pointer to the allocated memory
*/
-cx_attr_nodiscard
-cx_attr_nonnull
-cx_attr_malloc
-cx_attr_dealloc_ucx
-cx_attr_allocsize(2)
-cx_attr_export
-void *cxMalloc(
- const CxAllocator *allocator,
- size_t n
-);
+cx_attr_nodiscard cx_attr_nonnull
+cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
+CX_EXPORT void *cxMalloc(const CxAllocator *allocator, size_t n);
/**
* Reallocate the previously allocated block in @p mem, making the new block
* @p n bytes long.
- * This function may return the same pointer that was passed to it, if moving
+ * This function may return the same pointer passed to it if moving
* the memory was not necessary.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
@@ -258,25 +266,18 @@
* @param n the new size in bytes
* @return a pointer to the reallocated memory
*/
-cx_attr_nodiscard
-cx_attr_nonnull_arg(1)
-cx_attr_dealloc_ucx
-cx_attr_allocsize(3)
-cx_attr_export
-void *cxRealloc(
- const CxAllocator *allocator,
- void *mem,
- size_t n
-);
+cx_attr_nodiscard cx_attr_nonnull_arg(1)
+cx_attr_dealloc_ucx cx_attr_allocsize(3)
+CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
/**
* Reallocate the previously allocated block in @p mem, making the new block
* @p n bytes long.
- * This function may return the same pointer that was passed to it, if moving
+ * This function may return the same pointer passed to it if moving
* the memory was not necessary.
*
* The size is calculated by multiplying @p nemb and @p size.
- * If that multiplication overflows, this function returns @c NULL and @c errno
+ * If that multiplication overflows, this function returns @c NULL, and @c errno
* will be set.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
@@ -287,17 +288,10 @@
* @param size the size of each element
* @return a pointer to the reallocated memory
*/
-cx_attr_nodiscard
-cx_attr_nonnull_arg(1)
-cx_attr_dealloc_ucx
-cx_attr_allocsize(3, 4)
-cx_attr_export
-void *cxReallocArray(
- const CxAllocator *allocator,
- void *mem,
- size_t nmemb,
- size_t size
-);
+cx_attr_nodiscard cx_attr_nonnull_arg(1)
+cx_attr_dealloc_ucx cx_attr_allocsize(3, 4)
+CX_EXPORT void *cxReallocArray(const CxAllocator *allocator,
+ void *mem, size_t nmemb, size_t size);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
@@ -307,7 +301,7 @@
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @par Error handling
- * @c errno will be set, if the underlying realloc function does so.
+ * @c errno will be set if the underlying realloc function does so.
*
* @param allocator the allocator
* @param mem pointer to the pointer to allocated block
@@ -315,14 +309,8 @@
* @retval zero success
* @retval non-zero failure
*/
-cx_attr_nodiscard
-cx_attr_nonnull
-cx_attr_export
-int cxReallocate_(
- const CxAllocator *allocator,
- void **mem,
- size_t n
-);
+cx_attr_nodiscard cx_attr_nonnull
+CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
@@ -332,7 +320,7 @@
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @par Error handling
- * @c errno will be set, if the underlying realloc function does so.
+ * @c errno will be set if the underlying realloc function does so.
*
* @param allocator (@c CxAllocator*) the allocator
* @param mem (@c void**) pointer to the pointer to allocated block
@@ -362,15 +350,9 @@
* @retval zero success
* @retval non-zero on failure
*/
-cx_attr_nodiscard
-cx_attr_nonnull
-cx_attr_export
-int cxReallocateArray_(
- const CxAllocator *allocator,
- void **mem,
- size_t nmemb,
- size_t size
-);
+cx_attr_nodiscard cx_attr_nonnull
+CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator,
+ void **mem, size_t nmemb, size_t size);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
@@ -402,17 +384,53 @@
* @param size the size of each element in bytes
* @return a pointer to the allocated memory
*/
-cx_attr_nonnull_arg(1)
-cx_attr_nodiscard
-cx_attr_malloc
-cx_attr_dealloc_ucx
-cx_attr_allocsize(2, 3)
-cx_attr_export
-void *cxCalloc(
- const CxAllocator *allocator,
- size_t nmemb,
- size_t size
-);
+cx_attr_nonnull_arg(1) cx_attr_nodiscard
+cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
+CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
+
+/**
+ * Allocate @p n bytes of memory and sets every byte to zero.
+ *
+ * @param allocator the allocator
+ * @param n the number of bytes
+ * @return a pointer to the allocated memory
+ */
+cx_attr_nodiscard cx_attr_nonnull
+cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
+CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
+
+/**
+ * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
+ */
+#define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
+ */
+#define cxZallocDefault(...) cxZalloc(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
+ */
+#define cxCallocDefault(...) cxCalloc(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
+ */
+#define cxReallocDefault(...) cxRealloc(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
+ */
+#define cxReallocateDefault(...) cxReallocate(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
+ */
+#define cxReallocateArrayDefault(...) cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
+ */
+#define cxReallocArrayDefault(...) cxReallocArray(cxDefaultAllocator, __VA_ARGS__)
+/**
+ * Convenience macro that invokes cxFree() with the cxDefaultAllocator.
+ */
+#define cxFreeDefault(...) cxFree(cxDefaultAllocator, __VA_ARGS__)
#ifdef __cplusplus
} // extern "C"