--- a/ucx/cx/allocator.h Tue Oct 14 21:02:26 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;
/**
@@ -100,15 +86,13 @@
/**
* A pre-defined allocator using standard library malloc() etc.
*/
-cx_attr_export
-extern const CxAllocator * const cxStdlibAllocator;
+CX_EXPORT extern const CxAllocator * const cxStdlibAllocator;
/**
* The default allocator that is used by UCX.
* Initialized with cxStdlibAllocator, but you may change it.
*/
-cx_attr_export
-extern const CxAllocator * cxDefaultAllocator;
+CX_EXPORT extern const CxAllocator * cxDefaultAllocator;
/**
* Function pointer type for destructor functions.
@@ -133,10 +117,33 @@
* @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,
@@ -153,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,
@@ -180,14 +182,8 @@
* @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,
@@ -244,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.
@@ -257,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.
@@ -281,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.
@@ -310,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,
@@ -330,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
@@ -338,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,
@@ -355,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
@@ -385,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,
@@ -425,17 +384,9 @@
* @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.
@@ -444,16 +395,9 @@
* @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 *cxZalloc(
- 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 *cxZalloc(const CxAllocator *allocator, size_t n);
/**
* Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.