Mercurial > hg > ucx / file diff

--- a/src/cx/allocator.h	Tue Dec 16 11:32:18 2025 +0100
+++ b/src/cx/allocator.h	Tue Dec 16 11:48:52 2025 +0100
@@ -157,13 +157,9 @@
 CX_EXPORT unsigned long cx_system_page_size(void);
 
 /**
- * Reallocate a previously allocated block and changes the pointer in-place,
- * if necessary.
+ * Reallocate a previously allocated block.
  *
- * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
- *
- * @par Error handling
- * @c errno will be set by realloc() on failure.
+ * Internal function - do not use.
  *
  * @param mem pointer to the pointer to allocated block
  * @param n the new size in bytes
@@ -175,16 +171,9 @@
 CX_EXPORT int cx_reallocate_(void **mem, size_t n);
 
 /**
- * Reallocate a previously allocated block and changes the pointer in-place,
- * if necessary.
- *
- * The size is calculated by multiplying @p nemb and @p size.
+ * Reallocate a previously allocated block.
  *
- * @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.
+ * Internal function - do not use.
  *
  * @param mem pointer to the pointer to allocated block
  * @param nmemb the number of elements
@@ -272,6 +261,8 @@
  *
  * @note Re-allocating a block allocated by a different allocator is undefined.
  *
+ * @attention This function is bug-prone. Consider using cxReallocate().
+ *
  * @param allocator the allocator
  * @param mem pointer to the previously allocated block
  * @param n the new size in bytes
@@ -282,8 +273,8 @@
 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.
+ * Reallocate the previously allocated block in @p mem.
+ *
  * This function may return the same pointer passed to it if moving
  * the memory was not necessary.
  *
@@ -293,6 +284,8 @@
  *
  * @note Re-allocating a block allocated by a different allocator is undefined.
  *
+ * @attention This function is bug-prone. Consider using cxReallocateArray().
+ *
  * @param allocator the allocator
  * @param mem pointer to the previously allocated block
  * @param nmemb the number of elements
@@ -305,14 +298,9 @@
         void *mem, size_t nmemb, size_t size);
 
 /**
- * Reallocate a previously allocated block and changes the pointer in-place,
- * if necessary.
- * This function acts like cxRealloc() using the pointer pointed to by @p mem.
+ * Reallocate a previously allocated block.
  *
- * @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.
+ * Internal function - do not use.
  *
  * @param allocator the allocator
  * @param mem pointer to the pointer to allocated block
@@ -343,16 +331,9 @@
     cxReallocate_(allocator, (void**)(mem), n)
 
 /**
- * Reallocate a previously allocated block and changes the pointer in-place,
- * if necessary.
- * This function acts like cxReallocArray() using the pointer pointed to
- * by @p mem.
+ * Reallocate a previously allocated block.
  *
- * @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 or the
- * multiplication of @p nmemb and @p size overflows.
+ * Internal function - do not use.
  *
  * @param allocator the allocator
  * @param mem pointer to the pointer to allocated block
@@ -388,7 +369,7 @@
         cxReallocateArray_(allocator, (void**) (mem), nmemb, size)
 
 /**
- * Allocate @p nmemb elements of @p n bytes each, all initialized to zero.
+ * Allocate @p nmemb elements of @p size bytes each, all initialized to zero.
  *
  * @param allocator the allocator
  * @param nmemb the number of elements
@@ -411,35 +392,123 @@
 CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
 
 /**
+ * Allocate @p n bytes of memory.
+ *
  * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
+ *
+ * @param n (@c size_t) the number of bytes
+ * @return (@c void*) a pointer to the allocated memory
  */
-#define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)
+#define cxMallocDefault(n) cxMalloc(cxDefaultAllocator, n)
+
 /**
+ * Allocate @p n bytes of memory and sets every byte to zero.
+ *
  * Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
+ *
+ * @param n (@c size_t) the number of bytes
+ * @return (@c void*) a pointer to the allocated memory
  */
-#define cxZallocDefault(...) cxZalloc(cxDefaultAllocator, __VA_ARGS__)
+#define cxZallocDefault(n) cxZalloc(cxDefaultAllocator, n)
+
 /**
+ * Allocate @p nmemb elements of @p size bytes each, all initialized to zero.
+ *
  * Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
+ *
+ * @param nmemb (@c size_t) the number of elements
+ * @param size (@c size_t) the size of each element in bytes
+ * @return (@c void*) a pointer to the allocated memory
  */
-#define cxCallocDefault(...) cxCalloc(cxDefaultAllocator, __VA_ARGS__)
+#define cxCallocDefault(nmemb, size) cxCalloc(cxDefaultAllocator, nmemb, size)
+
 /**
+ * Reallocate the previously allocated block in @p mem.
+ *
+ * This function may return the same pointer passed to it if moving
+ * the memory was not necessary.
+ *
  * Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
+ *
+ * @attention This function is bug-prone. Consider using cxReallocateDefault().
+ *
+ * @param mem (@c void*) pointer to the previously allocated block
+ * @param n (@c size_t) the new size in bytes
+ * @return (@c void*) a pointer to the reallocated memory
  */
-#define cxReallocDefault(...) cxRealloc(cxDefaultAllocator, __VA_ARGS__)
+#define cxReallocDefault(mem, n) cxRealloc(cxDefaultAllocator, mem, n)
+
 /**
+ * Reallocate a previously allocated block and changes the pointer in-place,
+ * if necessary.
+ * This function acts like cxRealloc() using the pointer pointed to by @p mem.
+ *
  * Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
- */
-#define cxReallocateDefault(...) cxReallocate(cxDefaultAllocator, __VA_ARGS__)
-/**
- * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
+ *
+ * @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.
+ *
+ * @param mem (@c void**) pointer to the pointer to allocated block
+ * @param n (@c size_t) the new size in bytes
+ * @retval zero success
+ * @retval non-zero failure
  */
-#define cxReallocateArrayDefault(...) cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)
+#define cxReallocateDefault(mem, n) cxReallocate(cxDefaultAllocator, mem, n)
+
 /**
- * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
+ * Reallocate a previously allocated block and changes the pointer in-place,
+ * if necessary.
+ * This function acts like cxReallocArray() using the pointer pointed to
+ * by @p mem.
+ *
+ * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
+ *
+ * @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 or the
+ * multiplication of @p nmemb and @p size overflows.
+ *
+ * @param mem (@c void**) pointer to the pointer to allocated block
+ * @param nmemb (@c size_t) the number of elements
+ * @param size (@c size_t) the size of each element
+ * @retval zero success
+ * @retval non-zero failure
  */
-#define cxReallocArrayDefault(...) cxReallocArray(cxDefaultAllocator, __VA_ARGS__)
+#define cxReallocateArrayDefault(mem, nmemb, size) \
+        cxReallocateArray(cxDefaultAllocator, mem, nmemb, size)
+
 /**
+ * Reallocate the previously allocated block in @p mem.
+ *
+ * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
+ *
+ * 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
+ * will be set.
+ *
+ * @note Re-allocating a block allocated by a different allocator is undefined.
+ *
+ * @attention This function is bug-prone. Consider using cxReallocateArrayDefault().
+ *
+ * @param mem (@c void*) pointer to the previously allocated block
+ * @param nmemb (@c size_t) the number of elements
+ * @param size (@c size_t) the size of each element
+ * @return (@c void*) a pointer to the reallocated memory
+ */
+#define cxReallocArrayDefault(mem, nmemb, size) cxReallocArray(cxDefaultAllocator, mem, nmemb, size)
+
+/**
+ * Free a block of memory.
+ *
  * Convenience function that invokes cxFree() with the cxDefaultAllocator.
+ *
+ * @param mem the memory to deallocate
  */
 CX_EXPORT void cxFreeDefault(void *mem);