Mercurial > hg > ucx / changeset

--- a/CHANGELOG	Sun Oct 12 20:21:56 2025 +0200
+++ b/CHANGELOG	Wed Oct 15 22:45:21 2025 +0200
@@ -29,6 +29,7 @@
  * changes all cxListIterator() and cxMapIterator() family of functions to also accept NULL as argument
  * changes insert_element member function of CxList to accept NULL source and return a pointer to the inserted element
  * changes the compare function wrapper for pointer lists so that it no longer invokes the actual compare function for NULL pointers
+ * changes struct cx_array_reallocator_s by replacing the four generic data members with two specifically named members
  * fixes critical memory overflow in the stack-based array reallocator (this unfortunately breaks the function signature)
  * fixes critical bug in cx_array_insert_sorted() that caused an infinite loop when inserting duplicates
  * fixes mempool implementation not supporting NULL as argument for realloc

--- a/docs/Writerside/topics/about.md	Sun Oct 12 20:21:56 2025 +0200
+++ b/docs/Writerside/topics/about.md	Wed Oct 15 22:45:21 2025 +0200
@@ -56,6 +56,7 @@
 * changes all cxListIterator() and cxMapIterator() family of functions to also accept NULL as argument
 * changes insert_element member function of CxList to accept NULL source and return a pointer to the inserted element
 * changes the compare function wrapper for pointer lists so that it no longer invokes the actual compare function for NULL pointers
+* changes struct cx_array_reallocator_s by replacing the four generic data members with two specifically named members
 * fixes critical memory overflow in the stack-based array reallocator (this unfortunately breaks the function signature)
 * fixes critical bug in cx_array_insert_sorted() that caused an infinite loop when inserting duplicates
 * fixes mempool implementation not supporting NULL as argument for realloc

--- a/docs/Writerside/topics/array_list.h.md	Sun Oct 12 20:21:56 2025 +0200
+++ b/docs/Writerside/topics/array_list.h.md	Wed Oct 15 22:45:21 2025 +0200
@@ -96,15 +96,13 @@
     void *(*realloc)(void *array,
             size_t old_capacity, size_t new_capacity,
             size_t elem_size, CxArrayReallocator *alloc);
-    void *ptr1;
-    void *ptr2;
-    size_t int1;
-    size_t int2;
+    const CxAllocator *allocator;
+    const void *stack_ptr;
 } CxArrayReallocator;
 
 CxArrayReallocator cx_array_reallocator(
         const struct cx_allocator_s *allocator,
-        const void *stackmem
+        const void *stack_ptr
 );
 
 extern CxArrayReallocator* cx_array_default_reallocator;
@@ -120,12 +118,13 @@
 A reallocator created with the `cx_array_reallocator()` function uses a more sophisticated approach.
 On the one hand, it can use an arbitrary UCX [allocator](allocator.h.md) for the reallocation,
 and on the other hand, it can optionally keep track of a stack memory pointer.
-If you pass a non-`NULL` pointer to `stackmem`, the reallocator will _always_ allocate _new_ memory for the array,
-if the current location equals the `stackmem` address.
+If you pass a non-`NULL` pointer to `stack_ptr`, the reallocator will _always_ allocate _new_ memory for the array,
+if the current location equals the `stack_ptr` address.
 
 This allows you to allocate an array on the stack and instruct UCX to automatically move it to heap memory when the capacity is exceeded.
-Combined with a UCX [memory pool](mempool.h.md) this can be a powerful tool for local arrays
-which are expected to stay within the bounds of the stack memory most of the time, but are also allowed to sometimes grow their capacity.
+Combined with a UCX [memory pool](mempool.h.md) this can be a powerful tool.
+For example, you can add small arrays to your structs plus a memory pool and then use that memory pool to reallocate the arrays on the heap when needed.
+When you are done with the arrays, you can then use the memory pool to free the memory for those arrays that needed to be moved to the heap.
 
 ## Reserve
 
@@ -312,7 +311,7 @@
 and the latter function returns the closest element that is larger or equal (the least upper bound / supremum)
 than the searched element.
 
-> Note that all of the above functions are only well-defined on arrays which are sorted with respect to the given compare function.
+> Note that all the above functions are only well-defined on arrays which are sorted with respect to the given compare function.
 > 
 > This can, for example, easily be achieved by calling the standard library's `qsort()` function.
 >{style="note"}

--- a/src/array_list.c	Sun Oct 12 20:21:56 2025 +0200
+++ b/src/array_list.c	Wed Oct 15 22:45:21 2025 +0200
@@ -50,7 +50,7 @@
 }
 
 CxArrayReallocator cx_array_default_reallocator_impl = {
-        cx_array_default_realloc, NULL, NULL, 0, 0
+        cx_array_default_realloc, NULL, NULL
 };
 
 CxArrayReallocator *cx_array_default_reallocator = &cx_array_default_reallocator_impl;
@@ -72,11 +72,11 @@
     }
 
     // retrieve the pointer to the actual allocator
-    const CxAllocator *al = alloc->ptr1;
+    const CxAllocator *al = alloc->allocator;
 
     // check if the array is still located on the stack
     void *newmem;
-    if (array == alloc->ptr2) {
+    if (array == alloc->stack_ptr) {
         newmem = cxMalloc(al, n);
         if (newmem != NULL && array != NULL) {
             memcpy(newmem, array, old_capacity*elem_size);
@@ -89,15 +89,14 @@
 
 struct cx_array_reallocator_s cx_array_reallocator(
         const struct cx_allocator_s *allocator,
-        const void *stackmem
+        const void *stack_ptr
 ) {
     if (allocator == NULL) {
         allocator = cxDefaultAllocator;
     }
     return (struct cx_array_reallocator_s) {
             cx_array_advanced_realloc,
-            (void*) allocator, (void*) stackmem,
-            0, 0
+            allocator, stack_ptr,
     };
 }
 

--- a/src/cx/array_list.h	Sun Oct 12 20:21:56 2025 +0200
+++ b/src/cx/array_list.h	Wed Oct 15 22:45:21 2025 +0200
@@ -172,10 +172,9 @@
      * Reallocates space for the given array.
      *
      * Implementations are not required to free the original array.
-     * This allows reallocation of static memory by allocating heap memory
-     * and copying the array contents. The information in the custom fields of
-     * the referenced allocator can be used to track the state of the memory
-     * or to transport other additional data.
+     * This allows reallocation of static or stack memory by allocating heap memory
+     * and copying the array contents; namely when @c stack_ptr in this struct
+     * is not @c NULL and @p array equals @c stack_ptr.
      *
      * @param array the array to reallocate
      * @param old_capacity the old number of elements
@@ -196,21 +195,14 @@
     );
 
     /**
-     * Custom data pointer.
+     * The allocator that shall be used for the reallocations.
      */
-    void *ptr1;
-    /**
-     * Custom data pointer.
-     */
-    void *ptr2;
+    const CxAllocator *allocator;
     /**
-     * Custom data integer.
+     * Optional pointer to stack memory
+     * if the array is originally located on the stack.
      */
-    size_t int1;
-    /**
-     * Custom data integer.
-     */
-    size_t int2;
+    const void *stack_ptr;
 };
 
 /**
@@ -229,23 +221,23 @@
  *
  * When @p allocator is @c NULL, the cxDefaultAllocator will be used.
  *
- * When @p stackmem is not @c NULL, the reallocator is supposed to be used
- * @em only for the specific array initially located at @p stackmem.
+ * When @p stack_ptr is not @c NULL, the reallocator is supposed to be used
+ * @em only for the specific array initially located at @p stack_ptr.
  * When reallocation is needed, the reallocator checks if the array is
- * still located at @p stackmem and copies the contents to the heap.
+ * still located at @p stack_ptr and copies the contents to the heap.
  *
  * @note Invoking this function with both arguments being @c NULL will return a
  * reallocator that behaves like #cx_array_default_reallocator.
  *
  * @param allocator the allocator this reallocator shall be based on
- * @param stackmem the address of the array when the array is initially located
+ * @param stack_ptr the address of the array when the array is initially located
  * on the stack or shall not reallocate in place
  * @return an array reallocator
  */
 cx_attr_export
 CxArrayReallocator cx_array_reallocator(
         const struct cx_allocator_s *allocator,
-        const void *stackmem
+        const void *stack_ptr
 );
 
 /**