Mercurial > hg > toolkit / changeset

--- a/ucx/Makefile	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/Makefile	Sun Jan 05 22:00:39 2025 +0100
@@ -26,7 +26,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #
 
-BUILD_ROOT = ../
 include ../config.mk
 
 # list of source files
@@ -37,14 +36,16 @@
 SRC += compare.c
 SRC += hash_key.c
 SRC += hash_map.c
+SRC += iterator.c
 SRC += linked_list.c
 SRC += list.c
 SRC += map.c
 SRC += printf.c
 SRC += string.c
-SRC += utils.c
 SRC += tree.c
-SRC += iterator.c
+SRC += streams.c
+SRC += properties.c
+SRC += json.c
 
 OBJ   = $(SRC:%.c=../build/ucx/%$(OBJ_EXT))
 

--- a/ucx/allocator.c	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/allocator.c	Sun Jan 05 22:00:39 2025 +0100
@@ -28,35 +28,33 @@
 
 #include "cx/allocator.h"
 
-__attribute__((__malloc__, __alloc_size__(2)))
+#include <errno.h>
+
 static void *cx_malloc_stdlib(
-        __attribute__((__unused__)) void *d,
+        cx_attr_unused void *d,
         size_t n
 ) {
     return malloc(n);
 }
 
-__attribute__((__warn_unused_result__, __alloc_size__(3)))
 static void *cx_realloc_stdlib(
-        __attribute__((__unused__)) void *d,
+        cx_attr_unused void *d,
         void *mem,
         size_t n
 ) {
     return realloc(mem, n);
 }
 
-__attribute__((__malloc__, __alloc_size__(2, 3)))
 static void *cx_calloc_stdlib(
-        __attribute__((__unused__)) void *d,
+        cx_attr_unused void *d,
         size_t nelem,
         size_t n
 ) {
     return calloc(nelem, n);
 }
 
-__attribute__((__nonnull__))
 static void cx_free_stdlib(
-        __attribute__((__unused__)) void *d,
+        cx_attr_unused void *d,
         void *mem
 ) {
     free(mem);
@@ -75,20 +73,41 @@
 };
 CxAllocator *cxDefaultAllocator = &cx_default_allocator;
 
-
+#undef cx_reallocate
 int cx_reallocate(
         void **mem,
         size_t n
 ) {
     void *nmem = realloc(*mem, n);
     if (nmem == NULL) {
-        return 1;
+        return 1; // LCOV_EXCL_LINE
     } else {
         *mem = nmem;
         return 0;
     }
 }
 
+#undef cx_reallocatearray
+int cx_reallocatearray(
+        void **mem,
+        size_t nmemb,
+        size_t size
+) {
+    size_t n;
+    if (cx_szmul(nmemb, size, &n)) {
+        errno = EOVERFLOW;
+        return 1;
+    } else {
+        void *nmem = realloc(*mem, n);
+        if (nmem == NULL) {
+            return 1; // LCOV_EXCL_LINE
+        } else {
+            *mem = nmem;
+            return 0;
+        }
+    }
+}
+
 // IMPLEMENTATION OF HIGH LEVEL API
 
 void *cxMalloc(
@@ -106,6 +125,22 @@
     return allocator->cl->realloc(allocator->data, mem, n);
 }
 
+void *cxReallocArray(
+        const CxAllocator *allocator,
+        void *mem,
+        size_t nmemb,
+        size_t size
+) {
+    size_t n;
+    if (cx_szmul(nmemb, size, &n)) {
+        errno = EOVERFLOW;
+        return NULL;
+    } else {
+        return allocator->cl->realloc(allocator->data, mem, n);
+    }
+}
+
+#undef cxReallocate
 int cxReallocate(
         const CxAllocator *allocator,
         void **mem,
@@ -113,7 +148,23 @@
 ) {
     void *nmem = allocator->cl->realloc(allocator->data, *mem, n);
     if (nmem == NULL) {
-        return 1;
+        return 1; // LCOV_EXCL_LINE
+    } else {
+        *mem = nmem;
+        return 0;
+    }
+}
+
+#undef cxReallocateArray
+int cxReallocateArray(
+        const CxAllocator *allocator,
+        void **mem,
+        size_t nmemb,
+        size_t size
+) {
+    void *nmem = cxReallocArray(allocator, *mem, nmemb, size);
+    if (nmem == NULL) {
+        return 1; // LCOV_EXCL_LINE
     } else {
         *mem = nmem;
         return 0;

--- a/ucx/array_list.c	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/array_list.c	Sun Jan 05 22:00:39 2025 +0100
@@ -30,6 +30,7 @@
 #include "cx/compare.h"
 #include <assert.h>
 #include <string.h>
+#include <errno.h>
 
 // Default array reallocator
 
@@ -37,65 +38,258 @@
         void *array,
         size_t capacity,
         size_t elem_size,
-        __attribute__((__unused__)) struct cx_array_reallocator_s *alloc
+        cx_attr_unused CxArrayReallocator *alloc
 ) {
-    return realloc(array, capacity * elem_size);
+    size_t n;
+    if (cx_szmul(capacity, elem_size, &n)) {
+        errno = EOVERFLOW;
+        return NULL;
+    }
+    return realloc(array, n);
 }
 
-struct cx_array_reallocator_s cx_array_default_reallocator_impl = {
+CxArrayReallocator cx_array_default_reallocator_impl = {
         cx_array_default_realloc, NULL, NULL, 0, 0
 };
 
-struct cx_array_reallocator_s *cx_array_default_reallocator = &cx_array_default_reallocator_impl;
+CxArrayReallocator *cx_array_default_reallocator = &cx_array_default_reallocator_impl;
+
+// Stack-aware array reallocator
+
+static void *cx_array_advanced_realloc(
+        void *array,
+        size_t capacity,
+        size_t elem_size,
+        cx_attr_unused CxArrayReallocator *alloc
+) {
+    // check for overflow
+    size_t n;
+    if (cx_szmul(capacity, elem_size, &n)) {
+        errno = EOVERFLOW;
+        return NULL;
+    }
+
+    // retrieve the pointer to the actual allocator
+    const CxAllocator *al = alloc->ptr1;
+
+    // check if the array is still located on the stack
+    void *newmem;
+    if (array == alloc->ptr2) {
+        newmem = cxMalloc(al, n);
+        if (newmem != NULL && array != NULL) {
+            memcpy(newmem, array, n);
+        }
+    } else {
+        newmem = cxRealloc(al, array, n);
+    }
+    return newmem;
+}
+
+struct cx_array_reallocator_s cx_array_reallocator(
+        const struct cx_allocator_s *allocator,
+        const void *stackmem
+) {
+    if (allocator == NULL) {
+        allocator = cxDefaultAllocator;
+    }
+    return (struct cx_array_reallocator_s) {
+            cx_array_advanced_realloc,
+            (void*) allocator, (void*) stackmem,
+            0, 0
+    };
+}
 
 // LOW LEVEL ARRAY LIST FUNCTIONS
 
-enum cx_array_result cx_array_copy(
+static size_t cx_array_align_capacity(
+        size_t cap,
+        size_t alignment,
+        size_t max
+) {
+    if (cap > max - alignment) {
+        return cap;
+    } else {
+        return cap - (cap % alignment) + alignment;
+    }
+}
+
+int cx_array_reserve(
+        void **array,
+        void *size,
+        void *capacity,
+        unsigned width,
+        size_t elem_size,
+        size_t elem_count,
+        CxArrayReallocator *reallocator
+) {
+    // assert pointers
+    assert(array != NULL);
+    assert(size != NULL);
+    assert(capacity != NULL);
+
+    // default reallocator
+    if (reallocator == NULL) {
+        reallocator = cx_array_default_reallocator;
+    }
+
+    // determine size and capacity
+    size_t oldcap;
+    size_t oldsize;
+    size_t max_size;
+    if (width == 0 || width == sizeof(size_t)) {
+        oldcap = *(size_t*) capacity;
+        oldsize = *(size_t*) size;
+        max_size = SIZE_MAX;
+    } else if (width == sizeof(uint16_t)) {
+        oldcap = *(uint16_t*) capacity;
+        oldsize = *(uint16_t*) size;
+        max_size = UINT16_MAX;
+    } else if (width == sizeof(uint8_t)) {
+        oldcap = *(uint8_t*) capacity;
+        oldsize = *(uint8_t*) size;
+        max_size = UINT8_MAX;
+    }
+#if CX_WORDSIZE == 64
+    else if (width == sizeof(uint32_t)) {
+        oldcap = *(uint32_t*) capacity;
+        oldsize = *(uint32_t*) size;
+        max_size = UINT32_MAX;
+    }
+#endif
+    else {
+        errno = EINVAL;
+        return 1;
+    }
+
+    // assert that the array is allocated when it has capacity
+    assert(*array != NULL || oldcap == 0);
+
+    // check for overflow
+    if (elem_count > max_size - oldsize) {
+        errno = EOVERFLOW;
+        return 1;
+    }
+
+    // determine new capacity
+    size_t newcap = oldsize + elem_count;
+
+    // reallocate if possible
+    if (newcap > oldcap) {
+        // calculate new capacity (next number divisible by 16)
+        newcap = cx_array_align_capacity(newcap, 16, max_size);
+
+        // perform reallocation
+        void *newmem = reallocator->realloc(
+                *array, newcap, elem_size, reallocator
+        );
+        if (newmem == NULL) {
+            return 1; // LCOV_EXCL_LINE
+        }
+
+        // store new pointer
+        *array = newmem;
+
+        // store new capacity
+        if (width == 0 || width == sizeof(size_t)) {
+            *(size_t*) capacity = newcap;
+        } else if (width == sizeof(uint16_t)) {
+            *(uint16_t*) capacity = (uint16_t) newcap;
+        } else if (width == sizeof(uint8_t)) {
+            *(uint8_t*) capacity = (uint8_t) newcap;
+        }
+#if CX_WORDSIZE == 64
+        else if (width == sizeof(uint32_t)) {
+            *(uint32_t*) capacity = (uint32_t) newcap;
+        }
+#endif
+    }
+
+    return 0;
+}
+
+int cx_array_copy(
         void **target,
-        size_t *size,
-        size_t *capacity,
+        void *size,
+        void *capacity,
+        unsigned width,
         size_t index,
         const void *src,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 ) {
     // assert pointers
     assert(target != NULL);
     assert(size != NULL);
+    assert(capacity != NULL);
     assert(src != NULL);
 
-    // determine capacity
-    size_t cap = capacity == NULL ? *size : *capacity;
+    // default reallocator
+    if (reallocator == NULL) {
+        reallocator = cx_array_default_reallocator;
+    }
+
+    // determine size and capacity
+    size_t oldcap;
+    size_t oldsize;
+    size_t max_size;
+    if (width == 0 || width == sizeof(size_t)) {
+        oldcap = *(size_t*) capacity;
+        oldsize = *(size_t*) size;
+        max_size = SIZE_MAX;
+    } else if (width == sizeof(uint16_t)) {
+        oldcap = *(uint16_t*) capacity;
+        oldsize = *(uint16_t*) size;
+        max_size = UINT16_MAX;
+    } else if (width == sizeof(uint8_t)) {
+        oldcap = *(uint8_t*) capacity;
+        oldsize = *(uint8_t*) size;
+        max_size = UINT8_MAX;
+    }
+#if CX_WORDSIZE == 64
+    else if (width == sizeof(uint32_t)) {
+        oldcap = *(uint32_t*) capacity;
+        oldsize = *(uint32_t*) size;
+        max_size = UINT32_MAX;
+    }
+#endif
+    else {
+        errno = EINVAL;
+        return 1;
+    }
+
+    // assert that the array is allocated when it has capacity
+    assert(*target != NULL || oldcap == 0);
+
+    // check for overflow
+    if (index > max_size || elem_count > max_size - index) {
+        errno = EOVERFLOW;
+        return 1;
+    }
 
     // check if resize is required
     size_t minsize = index + elem_count;
-    size_t newsize = *size < minsize ? minsize : *size;
-    bool needrealloc = newsize > cap;
+    size_t newsize = oldsize < minsize ? minsize : oldsize;
 
     // reallocate if possible
-    if (needrealloc) {
-        // a reallocator and a capacity variable must be available
-        if (reallocator == NULL || capacity == NULL) {
-            return CX_ARRAY_REALLOC_NOT_SUPPORTED;
-        }
-
+    size_t newcap = oldcap;
+    if (newsize > oldcap) {
         // check, if we need to repair the src pointer
         uintptr_t targetaddr = (uintptr_t) *target;
         uintptr_t srcaddr = (uintptr_t) src;
         bool repairsrc = targetaddr <= srcaddr
-                         && srcaddr < targetaddr + cap * elem_size;
+                         && srcaddr < targetaddr + oldcap * elem_size;
 
         // calculate new capacity (next number divisible by 16)
-        cap = newsize - (newsize % 16) + 16;
-        assert(cap > newsize);
+        newcap = cx_array_align_capacity(newsize, 16, max_size);
+        assert(newcap > newsize);
 
         // perform reallocation
         void *newmem = reallocator->realloc(
-                *target, cap, elem_size, reallocator
+                *target, newcap, elem_size, reallocator
         );
         if (newmem == NULL) {
-            return CX_ARRAY_REALLOC_FAILED;
+            return 1;
         }
 
         // repair src pointer, if necessary
@@ -103,9 +297,8 @@
             src = ((char *) newmem) + (srcaddr - targetaddr);
         }
 
-        // store new pointer and capacity
+        // store new pointer
         *target = newmem;
-        *capacity = cap;
     }
 
     // determine target pointer
@@ -113,14 +306,34 @@
     start += index * elem_size;
 
     // copy elements and set new size
+    // note: no overflow check here, b/c we cannot get here w/o allocation
     memmove(start, src, elem_count * elem_size);
-    *size = newsize;
+
+    // if any of size or capacity changed, store them back
+    if (newsize != oldsize || newcap != oldcap) {
+        if (width == 0 || width == sizeof(size_t)) {
+            *(size_t*) capacity = newcap;
+            *(size_t*) size = newsize;
+        } else if (width == sizeof(uint16_t)) {
+            *(uint16_t*) capacity = (uint16_t) newcap;
+            *(uint16_t*) size = (uint16_t) newsize;
+        } else if (width == sizeof(uint8_t)) {
+            *(uint8_t*) capacity = (uint8_t) newcap;
+            *(uint8_t*) size = (uint8_t) newsize;
+        }
+#if CX_WORDSIZE == 64
+        else if (width == sizeof(uint32_t)) {
+            *(uint32_t*) capacity = (uint32_t) newcap;
+            *(uint32_t*) size = (uint32_t) newsize;
+        }
+#endif
+    }
 
     // return successfully
-    return CX_ARRAY_SUCCESS;
+    return 0;
 }
 
-enum cx_array_result cx_array_insert_sorted(
+int cx_array_insert_sorted(
         void **target,
         size_t *size,
         size_t *capacity,
@@ -128,7 +341,7 @@
         const void *sorted_data,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 ) {
     // assert pointers
     assert(target != NULL);
@@ -136,25 +349,35 @@
     assert(capacity != NULL);
     assert(cmp_func != NULL);
     assert(sorted_data != NULL);
-    assert(reallocator != NULL);
+
+    // default reallocator
+    if (reallocator == NULL) {
+        reallocator = cx_array_default_reallocator;
+    }
 
     // corner case
     if (elem_count == 0) return 0;
 
+    // overflow check
+    if (elem_count > SIZE_MAX - *size) {
+        errno = EOVERFLOW;
+        return 1;
+    }
+
     // store some counts
     size_t old_size = *size;
     size_t needed_capacity = old_size + elem_count;
 
     // if we need more than we have, try a reallocation
     if (needed_capacity > *capacity) {
-        size_t new_capacity = needed_capacity - (needed_capacity % 16) + 16;
+        size_t new_capacity = cx_array_align_capacity(needed_capacity, 16, SIZE_MAX);
         void *new_mem = reallocator->realloc(
                 *target, new_capacity, elem_size, reallocator
         );
         if (new_mem == NULL) {
             // give it up right away, there is no contract
             // that requires us to insert as much as we can
-            return CX_ARRAY_REALLOC_FAILED;
+            return 1;  // LCOV_EXCL_LINE
         }
         *target = new_mem;
         *capacity = new_capacity;
@@ -228,7 +451,7 @@
     // still buffer elements left?
     // don't worry, we already moved them to the correct place
 
-    return CX_ARRAY_SUCCESS;
+    return 0;
 }
 
 size_t cx_array_binary_search_inf(
@@ -255,6 +478,9 @@
         return 0;
     }
 
+    // special case: there is only one element and that is smaller
+    if (size == 1) return 0;
+
     // check the last array element
     result = cmp_func(elem, array + elem_size * (size - 1));
     if (result >= 0) {
@@ -287,10 +513,48 @@
     return result < 0 ? (pivot_index - 1) : pivot_index;
 }
 
+size_t cx_array_binary_search(
+        const void *arr,
+        size_t size,
+        size_t elem_size,
+        const void *elem,
+        cx_compare_func cmp_func
+) {
+    size_t index = cx_array_binary_search_inf(
+            arr, size, elem_size, elem, cmp_func
+    );
+    if (index < size &&
+            cmp_func(((const char *) arr) + index * elem_size, elem) == 0) {
+        return index;
+    } else {
+        return size;
+    }
+}
+
+size_t cx_array_binary_search_sup(
+        const void *arr,
+        size_t size,
+        size_t elem_size,
+        const void *elem,
+        cx_compare_func cmp_func
+) {
+    size_t inf = cx_array_binary_search_inf(
+            arr, size, elem_size, elem, cmp_func
+    );
+    if (inf == size) {
+        // no infimum means, first element is supremum
+        return 0;
+    } else if (cmp_func(((const char *) arr) + inf * elem_size, elem) == 0) {
+        return inf;
+    } else {
+        return inf + 1;
+    }
+}
+
 #ifndef CX_ARRAY_SWAP_SBO_SIZE
 #define CX_ARRAY_SWAP_SBO_SIZE 128
 #endif
-unsigned cx_array_swap_sbo_size = CX_ARRAY_SWAP_SBO_SIZE;
+const unsigned cx_array_swap_sbo_size = CX_ARRAY_SWAP_SBO_SIZE;
 
 void cx_array_swap(
         void *arr,
@@ -337,22 +601,9 @@
     struct cx_list_s base;
     void *data;
     size_t capacity;
-    struct cx_array_reallocator_s reallocator;
+    CxArrayReallocator reallocator;
 } cx_array_list;
 
-static void *cx_arl_realloc(
-        void *array,
-        size_t capacity,
-        size_t elem_size,
-        struct cx_array_reallocator_s *alloc
-) {
-    // retrieve the pointer to the list allocator
-    const CxAllocator *al = alloc->ptr1;
-
-    // use the list allocator to reallocate the memory
-    return cxRealloc(al, array, capacity * elem_size);
-}
-
 static void cx_arl_destructor(struct cx_list_s *list) {
     cx_array_list *arl = (cx_array_list *) list;
 
@@ -394,10 +645,11 @@
         size_t elems_to_move = list->collection.size - index;
         size_t start_of_moved = index + n;
 
-        if (CX_ARRAY_SUCCESS != cx_array_copy(
+        if (cx_array_copy(
                 &arl->data,
                 &list->collection.size,
                 &arl->capacity,
+                0,
                 start_of_moved,
                 first_to_move,
                 list->collection.elem_size,
@@ -414,20 +666,21 @@
     // therefore, it is impossible to leave this function with an invalid array
 
     // place the new elements
-    if (CX_ARRAY_SUCCESS == cx_array_copy(
+    if (cx_array_copy(
             &arl->data,
             &list->collection.size,
             &arl->capacity,
+            0,
             index,
             array,
             list->collection.elem_size,
             n,
             &arl->reallocator
     )) {
-        return n;
-    } else {
         // array list implementation is "all or nothing"
         return 0;
+    } else {
+        return n;
     }
 }
 
@@ -439,7 +692,7 @@
     // get a correctly typed pointer to the list
     cx_array_list *arl = (cx_array_list *) list;
 
-    if (CX_ARRAY_SUCCESS == cx_array_insert_sorted(
+    if (cx_array_insert_sorted(
             &arl->data,
             &list->collection.size,
             &arl->capacity,
@@ -449,10 +702,10 @@
             n,
             &arl->reallocator
     )) {
-        return n;
-    } else {
         // array list implementation is "all or nothing"
         return 0;
+    } else {
+        return n;
     }
 }
 
@@ -494,45 +747,66 @@
     }
 }
 
-static int cx_arl_remove(
+static size_t cx_arl_remove(
         struct cx_list_s *list,
-        size_t index
+        size_t index,
+        size_t num,
+        void *targetbuf
 ) {
     cx_array_list *arl = (cx_array_list *) list;
 
     // out-of-bounds check
+    size_t remove;
     if (index >= list->collection.size) {
-        return 1;
+        remove = 0;
+    } else if (index + num > list->collection.size) {
+        remove = list->collection.size - index;
+    } else {
+        remove = num;
     }
 
-    // content destruction
-    cx_invoke_destructor(list, ((char *) arl->data) + index * list->collection.elem_size);
+    // easy exit
+    if (remove == 0) return 0;
 
-    // short-circuit removal of last element
-    if (index == list->collection.size - 1) {
-        list->collection.size--;
-        return 0;
+    // destroy or copy contents
+    if (targetbuf == NULL) {
+        for (size_t idx = index; idx < index + remove; idx++) {
+            cx_invoke_destructor(
+                    list,
+                    ((char *) arl->data) + idx * list->collection.elem_size
+            );
+        }
+    } else {
+        memcpy(
+                targetbuf,
+                ((char *) arl->data) + index * list->collection.elem_size,
+                remove * list->collection.elem_size
+        );
     }
 
-    // just move the elements starting at index to the left
-    int result = cx_array_copy(
+    // short-circuit removal of last elements
+    if (index + remove == list->collection.size) {
+        list->collection.size -= remove;
+        return remove;
+    }
+
+    // just move the elements to the left
+    cx_array_copy(
             &arl->data,
             &list->collection.size,
             &arl->capacity,
+            0,
             index,
-            ((char *) arl->data) + (index + 1) * list->collection.elem_size,
+            ((char *) arl->data) + (index + remove) * list->collection.elem_size,
             list->collection.elem_size,
-            list->collection.size - index - 1,
+            list->collection.size - index - remove,
             &arl->reallocator
     );
 
-    // cx_array_copy cannot fail, array cannot grow
-    assert(result == 0);
+    // decrease the size
+    list->collection.size -= remove;
 
-    // decrease the size
-    list->collection.size--;
-
-    return 0;
+    return remove;
 }
 
 static void cx_arl_clear(struct cx_list_s *list) {
@@ -594,10 +868,11 @@
     for (ssize_t i = 0; i < (ssize_t) list->collection.size; i++) {
         if (0 == list->collection.cmpfunc(elem, cur)) {
             if (remove) {
-                if (0 == cx_arl_remove(list, i)) {
+                if (1 == cx_arl_remove(list, i, 1, NULL)) {
                     return i;
                 } else {
-                    return -1;
+                    // should be unreachable
+                    return -1;  // LCOV_EXCL_LINE
                 }
             } else {
                 return i;
@@ -664,7 +939,7 @@
     struct cx_iterator_s *iter = it;
     if (iter->base.remove) {
         iter->base.remove = false;
-        cx_arl_remove(iter->src_handle.m, iter->index);
+        cx_arl_remove(iter->src_handle.m, iter->index, 1, NULL);
     } else {
         iter->index++;
         iter->elem_handle =
@@ -678,7 +953,7 @@
     const cx_array_list *list = iter->src_handle.c;
     if (iter->base.remove) {
         iter->base.remove = false;
-        cx_arl_remove(iter->src_handle.m, iter->index);
+        cx_arl_remove(iter->src_handle.m, iter->index, 1, NULL);
     }
     iter->index--;
     if (iter->index < list->base.collection.size) {
@@ -754,14 +1029,13 @@
 
     // allocate the array after the real elem_size is known
     list->data = cxCalloc(allocator, initial_capacity, elem_size);
-    if (list->data == NULL) {
+    if (list->data == NULL) { // LCOV_EXCL_START
         cxFree(allocator, list);
         return NULL;
-    }
+    } // LCOV_EXCL_STOP
 
     // configure the reallocator
-    list->reallocator.realloc = cx_arl_realloc;
-    list->reallocator.ptr1 = (void *) allocator;
+    list->reallocator = cx_array_reallocator(allocator, NULL);
 
     return (CxList *) list;
 }

--- a/ucx/buffer.c	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/buffer.c	Sun Jan 05 22:00:39 2025 +0100
@@ -27,10 +27,21 @@
  */
 
 #include "cx/buffer.h"
-#include "cx/utils.h"
 
 #include <stdio.h>
 #include <string.h>
+#include <errno.h>
+
+static int buffer_copy_on_write(CxBuffer* buffer) {
+    if (0 == (buffer->flags & CX_BUFFER_COPY_ON_WRITE)) return 0;
+    void *newspace = cxMalloc(buffer->allocator, buffer->capacity);
+    if (NULL == newspace) return -1;
+    memcpy(newspace, buffer->space, buffer->size);
+    buffer->space = newspace;
+    buffer->flags &= ~CX_BUFFER_COPY_ON_WRITE;
+    buffer->flags |= CX_BUFFER_FREE_CONTENTS;
+    return 0;
+}
 
 int cxBufferInit(
         CxBuffer *buffer,
@@ -39,13 +50,18 @@
         const CxAllocator *allocator,
         int flags
 ) {
-    if (allocator == NULL) allocator = cxDefaultAllocator;
+    if (allocator == NULL) {
+        allocator = cxDefaultAllocator;
+    }
+    if (flags & CX_BUFFER_COPY_ON_EXTEND) {
+        flags |= CX_BUFFER_AUTO_EXTEND;
+    }
     buffer->allocator = allocator;
     buffer->flags = flags;
     if (!space) {
         buffer->bytes = cxMalloc(allocator, capacity);
         if (buffer->bytes == NULL) {
-            return 1;
+            return -1; // LCOV_EXCL_LINE
         }
         buffer->flags |= CX_BUFFER_FREE_CONTENTS;
     } else {
@@ -55,19 +71,27 @@
     buffer->size = 0;
     buffer->pos = 0;
 
-    buffer->flush_func = NULL;
-    buffer->flush_target = NULL;
-    buffer->flush_blkmax = 0;
-    buffer->flush_blksize = 4096;
-    buffer->flush_threshold = SIZE_MAX;
+    buffer->flush = NULL;
 
     return 0;
 }
 
+int cxBufferEnableFlushing(
+    CxBuffer *buffer,
+    CxBufferFlushConfig config
+) {
+    buffer->flush = malloc(sizeof(CxBufferFlushConfig));
+    if (buffer->flush == NULL) return -1; // LCOV_EXCL_LINE
+    memcpy(buffer->flush, &config, sizeof(CxBufferFlushConfig));
+    return 0;
+}
+
 void cxBufferDestroy(CxBuffer *buffer) {
-    if ((buffer->flags & CX_BUFFER_FREE_CONTENTS) == CX_BUFFER_FREE_CONTENTS) {
+    if (buffer->flags & CX_BUFFER_FREE_CONTENTS) {
         cxFree(buffer->allocator, buffer->bytes);
     }
+    free(buffer->flush);
+    memset(buffer, 0, sizeof(CxBuffer));
 }
 
 CxBuffer *cxBufferCreate(
@@ -76,21 +100,26 @@
         const CxAllocator *allocator,
         int flags
 ) {
+    if (allocator == NULL) {
+        allocator = cxDefaultAllocator;
+    }
     CxBuffer *buf = cxMalloc(allocator, sizeof(CxBuffer));
     if (buf == NULL) return NULL;
     if (0 == cxBufferInit(buf, space, capacity, allocator, flags)) {
         return buf;
     } else {
+        // LCOV_EXCL_START
         cxFree(allocator, buf);
         return NULL;
+        // LCOV_EXCL_STOP
     }
 }
 
 void cxBufferFree(CxBuffer *buffer) {
-    if ((buffer->flags & CX_BUFFER_FREE_CONTENTS) == CX_BUFFER_FREE_CONTENTS) {
-        cxFree(buffer->allocator, buffer->bytes);
-    }
-    cxFree(buffer->allocator, buffer);
+    if (buffer == NULL) return;
+    const CxAllocator *allocator = buffer->allocator;
+    cxBufferDestroy(buffer);
+    cxFree(allocator, buffer);
 }
 
 int cxBufferSeek(
@@ -117,10 +146,11 @@
     npos += offset;
 
     if ((offset > 0 && npos < opos) || (offset < 0 && npos > opos)) {
+        errno = EOVERFLOW;
         return -1;
     }
 
-    if (npos >= buffer->size) {
+    if (npos > buffer->size) {
         return -1;
     } else {
         buffer->pos = npos;
@@ -130,7 +160,9 @@
 }
 
 void cxBufferClear(CxBuffer *buffer) {
-    memset(buffer->bytes, 0, buffer->size);
+    if (0 == (buffer->flags & CX_BUFFER_COPY_ON_WRITE)) {
+        memset(buffer->bytes, 0, buffer->size);
+    }
     buffer->size = 0;
     buffer->pos = 0;
 }
@@ -140,7 +172,7 @@
     buffer->pos = 0;
 }
 
-int cxBufferEof(const CxBuffer *buffer) {
+bool cxBufferEof(const CxBuffer *buffer) {
     return buffer->pos >= buffer->size;
 }
 
@@ -152,48 +184,71 @@
         return 0;
     }
 
-    if (cxReallocate(buffer->allocator,
+    const int force_copy_flags = CX_BUFFER_COPY_ON_WRITE | CX_BUFFER_COPY_ON_EXTEND;
+    if (buffer->flags & force_copy_flags) {
+        void *newspace = cxMalloc(buffer->allocator, newcap);
+        if (NULL == newspace) return -1;
+        memcpy(newspace, buffer->space, buffer->size);
+        buffer->space = newspace;
+        buffer->capacity = newcap;
+        buffer->flags &= ~force_copy_flags;
+        buffer->flags |= CX_BUFFER_FREE_CONTENTS;
+        return 0;
+    } else if (cxReallocate(buffer->allocator,
                      (void **) &buffer->bytes, newcap) == 0) {
         buffer->capacity = newcap;
         return 0;
     } else {
-        return -1;
+        return -1; // LCOV_EXCL_LINE
     }
 }
 
-/**
- * Helps flushing data to the flush target of a buffer.
- *
- * @param buffer the buffer containing the config
- * @param space the data to flush
- * @param size the element size
- * @param nitems the number of items
- * @return the number of items flushed
- */
-static size_t cx_buffer_write_flush_helper(
-        CxBuffer *buffer,
-        const unsigned char *space,
+static size_t cx_buffer_flush_helper(
+        const CxBuffer *buffer,
         size_t size,
+        const unsigned char *src,
         size_t nitems
 ) {
-    size_t pos = 0;
-    size_t remaining = nitems;
-    size_t max_items = buffer->flush_blksize / size;
-    while (remaining > 0) {
-        size_t items = remaining > max_items ? max_items : remaining;
-        size_t flushed = buffer->flush_func(
-                space + pos,
-                size, items,
-                buffer->flush_target);
+    // flush data from an arbitrary source
+    // does not need to be the buffer's contents
+    size_t max_items = buffer->flush->blksize / size;
+    size_t fblocks = 0;
+    size_t flushed_total = 0;
+    while (nitems > 0 && fblocks < buffer->flush->blkmax) {
+        fblocks++;
+        size_t items = nitems > max_items ? max_items : nitems;
+        size_t flushed = buffer->flush->wfunc(
+            src, size, items, buffer->flush->target);
         if (flushed > 0) {
-            pos += (flushed * size);
-            remaining -= flushed;
+            flushed_total += flushed;
+            src += flushed * size;
+            nitems -= flushed;
         } else {
             // if no bytes can be flushed out anymore, we give up
             break;
         }
     }
-    return nitems - remaining;
+    return flushed_total;
+}
+
+static size_t cx_buffer_flush_impl(CxBuffer *buffer, size_t size) {
+    // flush the current contents of the buffer
+    unsigned char *space = buffer->bytes;
+    size_t remaining = buffer->pos / size;
+    size_t flushed_total = cx_buffer_flush_helper(
+        buffer, size, space, remaining);
+
+    // shift the buffer left after flushing
+    // IMPORTANT: up to this point, copy on write must have been
+    // performed already, because we can't do error handling here
+    cxBufferShiftLeft(buffer, flushed_total*size);
+
+    return flushed_total;
+}
+
+size_t cxBufferFlush(CxBuffer *buffer) {
+    if (buffer_copy_on_write(buffer)) return 0;
+    return cx_buffer_flush_impl(buffer, 1);
 }
 
 size_t cxBufferWrite(
@@ -204,6 +259,7 @@
 ) {
     // optimize for easy case
     if (size == 1 && (buffer->capacity - buffer->pos) >= nitems) {
+        if (buffer_copy_on_write(buffer)) return 0;
         memcpy(buffer->bytes + buffer->pos, ptr, nitems);
         buffer->pos += nitems;
         if (buffer->pos > buffer->size) {
@@ -213,80 +269,69 @@
     }
 
     size_t len;
-    size_t nitems_out = nitems;
     if (cx_szmul(size, nitems, &len)) {
+        errno = EOVERFLOW;
+        return 0;
+    }
+    if (buffer->pos > SIZE_MAX - len) {
+        errno = EOVERFLOW;
         return 0;
     }
     size_t required = buffer->pos + len;
-    if (buffer->pos > required) {
-        return 0;
-    }
 
     bool perform_flush = false;
     if (required > buffer->capacity) {
-        if ((buffer->flags & CX_BUFFER_AUTO_EXTEND) == CX_BUFFER_AUTO_EXTEND && required) {
-            if (buffer->flush_blkmax > 0 && required > buffer->flush_threshold) {
+        if (buffer->flags & CX_BUFFER_AUTO_EXTEND) {
+            if (buffer->flush != NULL && required > buffer->flush->threshold) {
                 perform_flush = true;
             } else {
                 if (cxBufferMinimumCapacity(buffer, required)) {
-                    return 0;
+                    return 0; // LCOV_EXCL_LINE
                 }
             }
         } else {
-            if (buffer->flush_blkmax > 0) {
+            if (buffer->flush != NULL) {
                 perform_flush = true;
             } else {
-                // truncate data to be written, if we can neither extend nor flush
+                // truncate data, if we can neither extend nor flush
                 len = buffer->capacity - buffer->pos;
                 if (size > 1) {
                     len -= len % size;
                 }
-                nitems_out = len / size;
+                nitems = len / size;
             }
         }
     }
 
+    // check here and not above because of possible truncation
     if (len == 0) {
-        return len;
+        return 0;
     }
 
-    if (perform_flush) {
-        size_t flush_max;
-        if (cx_szmul(buffer->flush_blkmax, buffer->flush_blksize, &flush_max)) {
-            return 0;
-        }
-        size_t flush_pos = buffer->flush_func == NULL || buffer->flush_target == NULL
-                           ? buffer->pos
-                           : cx_buffer_write_flush_helper(buffer, buffer->bytes, 1, buffer->pos);
-        if (flush_pos == buffer->pos) {
-            // entire buffer has been flushed, we can reset
-            buffer->size = buffer->pos = 0;
-
-            size_t items_flush; // how many items can also be directly flushed
-            size_t items_keep; // how many items have to be written to the buffer
+    // check if we need to copy
+    if (buffer_copy_on_write(buffer)) return 0;
 
-            items_flush = flush_max >= required ? nitems : (flush_max - flush_pos) / size;
-            if (items_flush > 0) {
-                items_flush = cx_buffer_write_flush_helper(buffer, ptr, size, items_flush / size);
-                // in case we could not flush everything, keep the rest
+    // perform the operation
+    if (perform_flush) {
+        size_t items_flush;
+        if (buffer->pos == 0) {
+            // if we don't have data in the buffer, but are instructed
+            // to flush, it means that we are supposed to relay the data
+            items_flush = cx_buffer_flush_helper(buffer, size, ptr, nitems);
+            if (items_flush == 0) {
+                // we needed to flush, but could not flush anything
+                // give up and avoid endless trying
+                return 0;
             }
-            items_keep = nitems - items_flush;
-            if (items_keep > 0) {
-                // try again with the remaining stuff
-                const unsigned char *new_ptr = ptr;
-                new_ptr += items_flush * size;
-                // report the directly flushed items as written plus the remaining stuff
-                return items_flush + cxBufferWrite(new_ptr, size, items_keep, buffer);
-            } else {
-                // all items have been flushed - report them as written
-                return nitems;
+            size_t ritems = nitems - items_flush;
+            const unsigned char *rest = ptr;
+            rest += items_flush * size;
+            return items_flush + cxBufferWrite(rest, size, ritems, buffer);
+        } else {
+            items_flush = cx_buffer_flush_impl(buffer, size);
+            if (items_flush == 0) {
+                return 0;
             }
-        } else if (flush_pos == 0) {
-            // nothing could be flushed at all, we immediately give up without writing any data
-            return 0;
-        } else {
-            // we were partially successful, we shift left and try again
-            cxBufferShiftLeft(buffer, flush_pos);
             return cxBufferWrite(ptr, size, nitems, buffer);
         }
     } else {
@@ -295,11 +340,24 @@
         if (buffer->pos > buffer->size) {
             buffer->size = buffer->pos;
         }
-        return nitems_out;
+        return nitems;
     }
 
 }
 
+size_t cxBufferAppend(
+        const void *ptr,
+        size_t size,
+        size_t nitems,
+        CxBuffer *buffer
+) {
+    size_t pos = buffer->pos;
+    buffer->pos = buffer->size;
+    size_t written = cxBufferWrite(ptr, size, nitems, buffer);
+    buffer->pos = pos;
+    return written;
+}
+
 int cxBufferPut(
         CxBuffer *buffer,
         int c
@@ -313,6 +371,17 @@
     }
 }
 
+int cxBufferTerminate(CxBuffer *buffer) {
+    bool success = 0 == cxBufferPut(buffer, 0);
+    if (success) {
+        buffer->pos--;
+        buffer->size--;
+        return 0;
+    } else {
+        return -1;
+    }
+}
+
 size_t cxBufferPutString(
         CxBuffer *buffer,
         const char *str
@@ -328,6 +397,7 @@
 ) {
     size_t len;
     if (cx_szmul(size, nitems, &len)) {
+        errno = EOVERFLOW;
         return 0;
     }
     if (buffer->pos + len > buffer->size) {
@@ -362,6 +432,7 @@
     if (shift >= buffer->size) {
         buffer->pos = buffer->size = 0;
     } else {
+        if (buffer_copy_on_write(buffer)) return -1;
         memmove(buffer->bytes, buffer->bytes + shift, buffer->size - shift);
         buffer->size -= shift;
 
@@ -378,14 +449,18 @@
         CxBuffer *buffer,
         size_t shift
 ) {
+    if (buffer->size > SIZE_MAX - shift) {
+        errno = EOVERFLOW;
+        return -1;
+    }
     size_t req_capacity = buffer->size + shift;
     size_t movebytes;
 
     // auto extend buffer, if required and enabled
     if (buffer->capacity < req_capacity) {
-        if ((buffer->flags & CX_BUFFER_AUTO_EXTEND) == CX_BUFFER_AUTO_EXTEND) {
+        if (buffer->flags & CX_BUFFER_AUTO_EXTEND) {
             if (cxBufferMinimumCapacity(buffer, req_capacity)) {
-                return 1;
+                return -1; // LCOV_EXCL_LINE
             }
             movebytes = buffer->size;
         } else {
@@ -395,8 +470,11 @@
         movebytes = buffer->size;
     }
 
-    memmove(buffer->bytes + shift, buffer->bytes, movebytes);
-    buffer->size = shift + movebytes;
+    if (movebytes > 0) {
+        if (buffer_copy_on_write(buffer)) return -1;
+        memmove(buffer->bytes + shift, buffer->bytes, movebytes);
+        buffer->size = shift + movebytes;
+    }
 
     buffer->pos += shift;
     if (buffer->pos > buffer->size) {

--- a/ucx/compare.c	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/compare.c	Sun Jan 05 22:00:39 2025 +0100
@@ -30,9 +30,21 @@
 
 #include <math.h>
 
+int cx_vcmp_int(int a, int b) {
+    if (a == b) {
+        return 0;
+    } else {
+        return a < b ? -1 : 1;
+    }
+}
+
 int cx_cmp_int(const void *i1, const void *i2) {
     int a = *((const int *) i1);
     int b = *((const int *) i2);
+    return cx_vcmp_int(a, b);
+}
+
+int cx_vcmp_longint(long int a, long int b) {
     if (a == b) {
         return 0;
     } else {
@@ -43,6 +55,10 @@
 int cx_cmp_longint(const void *i1, const void *i2) {
     long int a = *((const long int *) i1);
     long int b = *((const long int *) i2);
+    return cx_vcmp_longint(a, b);
+}
+
+int cx_vcmp_longlong(long long a, long long b) {
     if (a == b) {
         return 0;
     } else {
@@ -53,6 +69,10 @@
 int cx_cmp_longlong(const void *i1, const void *i2) {
     long long a = *((const long long *) i1);
     long long b = *((const long long *) i2);
+    return cx_vcmp_longlong(a, b);
+}
+
+int cx_vcmp_int16(int16_t a, int16_t b) {
     if (a == b) {
         return 0;
     } else {
@@ -63,6 +83,10 @@
 int cx_cmp_int16(const void *i1, const void *i2) {
     int16_t a = *((const int16_t *) i1);
     int16_t b = *((const int16_t *) i2);
+    return cx_vcmp_int16(a, b);
+}
+
+int cx_vcmp_int32(int32_t a, int32_t b) {
     if (a == b) {
         return 0;
     } else {
@@ -73,6 +97,10 @@
 int cx_cmp_int32(const void *i1, const void *i2) {
     int32_t a = *((const int32_t *) i1);
     int32_t b = *((const int32_t *) i2);
+    return cx_vcmp_int32(a, b);
+}
+
+int cx_vcmp_int64(int64_t a, int64_t b) {
     if (a == b) {
         return 0;
     } else {
@@ -83,6 +111,10 @@
 int cx_cmp_int64(const void *i1, const void *i2) {
     int64_t a = *((const int64_t *) i1);
     int64_t b = *((const int64_t *) i2);
+    return cx_vcmp_int64(a, b);
+}
+
+int cx_vcmp_uint(unsigned int a, unsigned int b) {
     if (a == b) {
         return 0;
     } else {
@@ -93,6 +125,10 @@
 int cx_cmp_uint(const void *i1, const void *i2) {
     unsigned int a = *((const unsigned int *) i1);
     unsigned int b = *((const unsigned int *) i2);
+    return cx_vcmp_uint(a, b);
+}
+
+int cx_vcmp_ulongint(unsigned long int a, unsigned long int b) {
     if (a == b) {
         return 0;
     } else {
@@ -103,6 +139,10 @@
 int cx_cmp_ulongint(const void *i1, const void *i2) {
     unsigned long int a = *((const unsigned long int *) i1);
     unsigned long int b = *((const unsigned long int *) i2);
+    return cx_vcmp_ulongint(a, b);
+}
+
+int cx_vcmp_ulonglong(unsigned long long a, unsigned long long b) {
     if (a == b) {
         return 0;
     } else {
@@ -113,6 +153,10 @@
 int cx_cmp_ulonglong(const void *i1, const void *i2) {
     unsigned long long a = *((const unsigned long long *) i1);
     unsigned long long b = *((const unsigned long long *) i2);
+    return cx_vcmp_ulonglong(a, b);
+}
+
+int cx_vcmp_uint16(uint16_t a, uint16_t b) {
     if (a == b) {
         return 0;
     } else {
@@ -123,6 +167,10 @@
 int cx_cmp_uint16(const void *i1, const void *i2) {
     uint16_t a = *((const uint16_t *) i1);
     uint16_t b = *((const uint16_t *) i2);
+    return cx_vcmp_uint16(a, b);
+}
+
+int cx_vcmp_uint32(uint32_t a, uint32_t b) {
     if (a == b) {
         return 0;
     } else {
@@ -133,6 +181,10 @@
 int cx_cmp_uint32(const void *i1, const void *i2) {
     uint32_t a = *((const uint32_t *) i1);
     uint32_t b = *((const uint32_t *) i2);
+    return cx_vcmp_uint32(a, b);
+}
+
+int cx_vcmp_uint64(uint64_t a, uint64_t b) {
     if (a == b) {
         return 0;
     } else {
@@ -143,7 +195,11 @@
 int cx_cmp_uint64(const void *i1, const void *i2) {
     uint64_t a = *((const uint64_t *) i1);
     uint64_t b = *((const uint64_t *) i2);
-    if (a == b) {
+    return cx_vcmp_uint64(a, b);
+}
+
+int cx_vcmp_float(float a, float b) {
+    if (fabsf(a - b) < 1e-6f) {
         return 0;
     } else {
         return a < b ? -1 : 1;
@@ -153,7 +209,11 @@
 int cx_cmp_float(const void *f1, const void *f2) {
     float a = *((const float *) f1);
     float b = *((const float *) f2);
-    if (fabsf(a - b) < 1e-6f) {
+    return cx_vcmp_float(a, b);
+}
+
+int cx_vcmp_double(double a, double b) {
+    if (fabs(a - b) < 1e-14) {
         return 0;
     } else {
         return a < b ? -1 : 1;
@@ -166,10 +226,14 @@
 ) {
     double a = *((const double *) d1);
     double b = *((const double *) d2);
-    if (fabs(a - b) < 1e-14) {
+    return cx_vcmp_double(a, b);
+}
+
+int cx_vcmp_intptr(intptr_t p1, intptr_t p2) {
+    if (p1 == p2) {
         return 0;
     } else {
-        return a < b ? -1 : 1;
+        return p1 < p2 ? -1 : 1;
     }
 }
 
@@ -179,6 +243,10 @@
 ) {
     intptr_t p1 = *(const intptr_t *) ptr1;
     intptr_t p2 = *(const intptr_t *) ptr2;
+    return cx_vcmp_intptr(p1, p2);
+}
+
+int cx_vcmp_uintptr(uintptr_t p1, uintptr_t p2) {
     if (p1 == p2) {
         return 0;
     } else {
@@ -192,11 +260,7 @@
 ) {
     uintptr_t p1 = *(const uintptr_t *) ptr1;
     uintptr_t p2 = *(const uintptr_t *) ptr2;
-    if (p1 == p2) {
-        return 0;
-    } else {
-        return p1 < p2 ? -1 : 1;
-    }
+    return cx_vcmp_uintptr(p1, p2);
 }
 
 int cx_cmp_ptr(

--- a/ucx/cx/allocator.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/allocator.h	Sun Jan 05 22:00:39 2025 +0100
@@ -26,7 +26,7 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file allocator.h
+ * @file allocator.h
  * Interface for custom allocators.
  */
 
@@ -54,7 +54,6 @@
     /**
      * The allocator's realloc() implementation.
      */
-    __attribute__((__warn_unused_result__))
     void *(*realloc)(
             void *data,
             void *mem,
@@ -73,7 +72,6 @@
     /**
      * The allocator's free() implementation.
      */
-    __attribute__((__nonnull__))
     void (*free)(
             void *data,
             void *mem
@@ -108,76 +106,157 @@
  * Function pointer type for destructor functions.
  *
  * A destructor function deallocates possible contents and MAY free the memory
- * pointed to by \p memory. Read the documentation of the respective function
- * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
- * particular implementation.
+ * pointed to by @p memory. Read the documentation of the respective function
+ * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
+ * that particular implementation.
  *
  * @param memory a pointer to the object to destruct
   */
-__attribute__((__nonnull__))
 typedef void (*cx_destructor_func)(void *memory);
 
 /**
  * Function pointer type for destructor functions.
  *
  * A destructor function deallocates possible contents and MAY free the memory
- * pointed to by \p memory. Read the documentation of the respective function
- * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
- * particular implementation.
+ * pointed to by @p memory. Read the documentation of the respective function
+ * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
+ * that particular implementation.
  *
  * @param data an optional pointer to custom data
  * @param memory a pointer to the object to destruct
   */
-__attribute__((__nonnull__(2)))
 typedef void (*cx_destructor_func2)(
         void *data,
         void *memory
 );
 
 /**
- * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
+ * Re-allocate a previously allocated block and changes the pointer in-place,
+ * if necessary.
  *
- * \par Error handling
- * \c errno will be set by realloc() on failure.
+ * @par Error handling
+ * @c errno will be set by realloc() on failure.
  *
  * @param mem pointer to the pointer to allocated block
  * @param n the new size in bytes
- * @return zero on success, non-zero on failure
+ * @retval zero success
+ * @retval non-zero failure
+ * @see cx_reallocatearray()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 int cx_reallocate(
         void **mem,
         size_t n
 );
 
 /**
- * Allocate \p n bytes of memory.
+ * Re-allocate a previously allocated block and changes the pointer in-place,
+ * if necessary.
+ *
+ * The size is calculated by multiplying @p nemb and @p size.
+ *
+ * @par Error handling
+ * @c errno will be set by realloc() on failure or when the multiplication of
+ * @p nmemb and @p size overflows.
+ *
+ * @param mem pointer to the pointer to allocated block
+ * @param nmemb the number of elements
+ * @param size the size of each element
+ * @retval zero success
+ * @retval non-zero failure
+ * @see cx_reallocate()
+ */
+cx_attr_nonnull
+cx_attr_nodiscard
+int cx_reallocatearray(
+        void **mem,
+        size_t nmemb,
+        size_t size
+);
+
+/**
+ * Re-allocate a previously allocated block and changes the pointer in-place,
+ * if necessary.
+ *
+ * @par Error handling
+ * @c errno will be set by realloc() on failure.
+ *
+ * @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
+ * @see cx_reallocatearray()
+ */
+#define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n)
+
+/**
+ * Re-allocate a previously allocated block and changes the pointer in-place,
+ * if necessary.
+ *
+ * The size is calculated by multiplying @p nemb and @p size.
+ *
+ * @par Error handling
+ * @c errno will be set by realloc() on failure or when 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 cx_reallocatearray(mem, nmemb, size) \
+    cx_reallocatearray((void**)(mem), nmemb, size)
+
+/**
+ * Free a block allocated by this allocator.
+ *
+ * @note Freeing a block of a different allocator is undefined.
+ *
+ * @param allocator the allocator
+ * @param mem a pointer to the block to free
+ */
+cx_attr_nonnull_arg(1)
+void cxFree(
+        const CxAllocator *allocator,
+        void *mem
+);
+
+/**
+ * Allocate @p n bytes of memory.
  *
  * @param allocator the allocator
  * @param n the number of bytes
  * @return a pointer to the allocated memory
  */
-__attribute__((__malloc__))
-__attribute__((__alloc_size__(2)))
+cx_attr_nodiscard
+cx_attr_nonnull
+cx_attr_malloc
+cx_attr_dealloc_ucx
+cx_attr_allocsize(2)
 void *cxMalloc(
         const CxAllocator *allocator,
         size_t n
 );
 
 /**
- * Re-allocate 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 the memory
- * was not necessary.
+ * Re-allocate 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
+ * the memory was not necessary.
  *
- * \note Re-allocating a block allocated by a different allocator is undefined.
+ * @note Re-allocating a block allocated by a different allocator is undefined.
  *
  * @param allocator the allocator
  * @param mem pointer to the previously allocated block
  * @param n the new size in bytes
  * @return a pointer to the re-allocated memory
  */
-__attribute__((__warn_unused_result__))
-__attribute__((__alloc_size__(3)))
+cx_attr_nodiscard
+cx_attr_nonnull_arg(1)
+cx_attr_dealloc_ucx
+cx_attr_allocsize(3)
 void *cxRealloc(
         const CxAllocator *allocator,
         void *mem,
@@ -185,20 +264,52 @@
 );
 
 /**
- * Re-allocate 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.
+ * Re-allocate 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
+ * 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.
  *
- * \note Re-allocating a block allocated by a different allocator is undefined.
+ * @param allocator the allocator
+ * @param mem pointer to the previously allocated block
+ * @param nmemb the number of elements
+ * @param size the size of each element
+ * @return a pointer to the re-allocated memory
+ */
+cx_attr_nodiscard
+cx_attr_nonnull_arg(1)
+cx_attr_dealloc_ucx
+cx_attr_allocsize(3, 4)
+void *cxReallocArray(
+        const CxAllocator *allocator,
+        void *mem,
+        size_t nmemb,
+        size_t size
+);
+
+/**
+ * Re-allocate 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.
  *
- * \par Error handling
- * \c errno will be set, if the underlying realloc function does so.
+ * @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 allocator the allocator
  * @param mem pointer to the pointer to allocated block
  * @param n the new size in bytes
- * @return zero on success, non-zero on failure
+ * @retval zero success
+ * @retval non-zero failure
  */
-__attribute__((__nonnull__))
+cx_attr_nodiscard
+cx_attr_nonnull
 int cxReallocate(
         const CxAllocator *allocator,
         void **mem,
@@ -206,35 +317,93 @@
 );
 
 /**
- * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
+ * Re-allocate 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.
+ *
+ * @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 allocator (@c CxAllocator*) the allocator
+ * @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 cxReallocate(allocator, mem, n) \
+    cxReallocate(allocator, (void**)(mem), n)
+
+/**
+ * Re-allocate 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.
+ *
+ * @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 allocator the allocator
+ * @param mem pointer to the pointer to allocated block
+ * @param nmemb the number of elements
+ * @param size the size of each element
+ * @retval zero success
+ * @retval non-zero on failure
+ */
+cx_attr_nodiscard
+cx_attr_nonnull
+int cxReallocateArray(
+        const CxAllocator *allocator,
+        void **mem,
+        size_t nmemb,
+        size_t size
+);
+
+/**
+ * Re-allocate 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.
+ *
+ * @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 allocator (@c CxAllocator*) the allocator
+ * @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 cxReallocateArray(allocator, mem, nmemb, size) \
+        cxReallocateArray(allocator, (void**) (mem), nmemb, size)
+
+/**
+ * Allocate @p nelem elements of @p n bytes each, all initialized to zero.
  *
  * @param allocator the allocator
  * @param nelem the number of elements
  * @param n the size of each element in bytes
  * @return a pointer to the allocated memory
  */
-__attribute__((__malloc__))
-__attribute__((__alloc_size__(2, 3)))
+cx_attr_nonnull_arg(1)
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc_ucx
+cx_attr_allocsize(2, 3)
 void *cxCalloc(
         const CxAllocator *allocator,
         size_t nelem,
         size_t n
 );
 
-/**
- * Free a block allocated by this allocator.
- *
- * \note Freeing a block of a different allocator is undefined.
- *
- * @param allocator the allocator
- * @param mem a pointer to the block to free
- */
-__attribute__((__nonnull__))
-void cxFree(
-        const CxAllocator *allocator,
-        void *mem
-);
-
 #ifdef __cplusplus
 } // extern "C"
 #endif

--- a/ucx/cx/array_list.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/array_list.h	Sun Jan 05 22:00:39 2025 +0100
@@ -26,12 +26,11 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file array_list.h
- * \brief Array list implementation.
- * \details Also provides several low-level functions for custom array list implementations.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file array_list.h
+ * @brief Array list implementation.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 
@@ -45,30 +44,90 @@
 #endif
 
 /**
- * The maximum item size in an array list that fits into stack buffer when swapped.
+ * The maximum item size in an array list that fits into stack buffer
+ * when swapped.
  */
-extern unsigned cx_array_swap_sbo_size;
+extern const unsigned cx_array_swap_sbo_size;
+
+/**
+ * Declares variables for an array that can be used with the convenience macros.
+ *
+ * @par Examples
+ * @code
+ * // integer array with at most 255 elements
+ * CX_ARRAY_DECLARE_SIZED(int, myarray, uint8_t)
+ *
+ * // array of MyObject* pointers where size and capacity are stored as unsigned int
+ * CX_ARRAY_DECLARE_SIZED(MyObject*, objects, unsigned int)
+ *
+ * // initializing code
+ * cx_array_initialize(myarray, 16); // reserve space for 16
+ * cx_array_initialize(objects, 100); // reserve space for 100
+ * @endcode
+ *
+ * @param type the type of the data
+ * @param name the name of the array
+ * @param size_type the type of the size (should be uint8_t, uint16_t, uint32_t, or size_t)
+ *
+ * @see cx_array_initialize()
+ * @see cx_array_simple_add()
+ * @see cx_array_simple_copy()
+ * @see cx_array_simple_add_sorted()
+ * @see cx_array_simple_insert_sorted()
+ */
+#define CX_ARRAY_DECLARE_SIZED(type, name, size_type) \
+    type * name; \
+    /** Array size. */ size_type name##_size; \
+    /** Array capacity. */ size_type name##_capacity
 
 /**
  * Declares variables for an array that can be used with the convenience macros.
  *
+ * The size and capacity variables will have @c size_t type.
+ * Use #CX_ARRAY_DECLARE_SIZED() to specify a different type.
+ *
+ * @par Examples
+ * @code
+ * // int array
+ * CX_ARRAY_DECLARE(int, myarray)
+ *
+ * // initializing code
+ * cx_array_initialize(myarray, 32); // reserve space for 32
+ * @endcode
+ *
+ * @param type the type of the data
+ * @param name the name of the array
+ *
+ * @see cx_array_initialize()
  * @see cx_array_simple_add()
  * @see cx_array_simple_copy()
- * @see cx_array_initialize()
  * @see cx_array_simple_add_sorted()
  * @see cx_array_simple_insert_sorted()
  */
-#define CX_ARRAY_DECLARE(type, name) \
-    type * name;                     \
-    size_t name##_size;              \
-    size_t name##_capacity
+#define CX_ARRAY_DECLARE(type, name) CX_ARRAY_DECLARE_SIZED(type, name, size_t)
 
 /**
- * Initializes an array declared with CX_ARRAY_DECLARE().
+ * Initializes an array with the given capacity.
+ *
+ * The type of the capacity depends on the type used during declaration.
+ *
+ * @par Examples
+ * @code
+ * CX_ARRAY_DECLARE_SIZED(int, arr1, uint8_t)
+ * CX_ARRAY_DECLARE(int, arr2) // size and capacity are implicitly size_t
+ *
+ * // initializing code
+ * cx_array_initialize(arr1, 500); // error: maximum for uint8_t is 255
+ * cx_array_initialize(arr2, 500); // OK
+ * @endcode
+ *
  *
  * The memory for the array is allocated with stdlib malloc().
- * @param array the array
+ * @param array the name of the array
  * @param capacity the initial capacity
+ * @see cx_array_initialize_a()
+ * @see CX_ARRAY_DECLARE_SIZED()
+ * @see CX_ARRAY_DECLARE()
  */
 #define cx_array_initialize(array, capacity) \
         array##_capacity = capacity; \
@@ -76,7 +135,36 @@
         array = malloc(sizeof(array[0]) * capacity)
 
 /**
+ * Initializes an array with the given capacity using the specified allocator.
+ *
+ * @par Example
+ * @code
+ * CX_ARRAY_DECLARE(int, myarray)
+ *
+ *
+ * const CxAllocator *al = // ...
+ * cx_array_initialize_a(al, myarray, 128);
+ * // ...
+ * cxFree(al, myarray); // don't forget to free with same allocator
+ * @endcode
+ *
+ * The memory for the array is allocated with stdlib malloc().
+ * @param allocator (@c CxAllocator*) the allocator
+ * @param array the name of the array
+ * @param capacity the initial capacity
+ * @see cx_array_initialize()
+ * @see CX_ARRAY_DECLARE_SIZED()
+ * @see CX_ARRAY_DECLARE()
+ */
+#define cx_array_initialize_a(allocator, array, capacity) \
+        array##_capacity = capacity; \
+        array##_size = 0; \
+        array = cxMalloc(allocator, sizeof(array[0]) * capacity)
+
+/**
  * Defines a reallocation mechanism for arrays.
+ * You can create your own, use cx_array_reallocator(), or
+ * use the #cx_array_default_reallocator.
  */
 struct cx_array_reallocator_s {
     /**
@@ -92,8 +180,11 @@
      * @param capacity the new capacity (number of elements)
      * @param elem_size the size of each element
      * @param alloc a reference to this allocator
-     * @return a pointer to the reallocated memory or \c NULL on failure
+     * @return a pointer to the reallocated memory or @c NULL on failure
      */
+    cx_attr_nodiscard
+    cx_attr_nonnull_arg(4)
+    cx_attr_allocsize(2, 3)
     void *(*realloc)(
             void *array,
             size_t capacity,
@@ -120,125 +211,271 @@
 };
 
 /**
+ * Typedef for the array reallocator struct.
+ */
+typedef struct cx_array_reallocator_s CxArrayReallocator;
+
+/**
  * A default stdlib-based array reallocator.
  */
-extern struct cx_array_reallocator_s *cx_array_default_reallocator;
+extern CxArrayReallocator *cx_array_default_reallocator;
+
+/**
+ * Creates a new array reallocator.
+ *
+ * When @p allocator is @c NULL, the stdlib default allocator will be used.
+ *
+ * When @p stackmem is not @c NULL, the reallocator is supposed to be used
+ * @em only for the specific array that is initially located at @p stackmem.
+ * When reallocation is needed, the reallocator checks, if the array is
+ * still located at @p stackmem and copies the contents to the heap.
+ *
+ * @note Invoking this function with both arguments @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
+ * on the stack or shall not reallocated in place
+ * @return an array reallocator
+ */
+CxArrayReallocator cx_array_reallocator(
+        const struct cx_allocator_s *allocator,
+        const void *stackmem
+);
 
 /**
- * Return codes for array functions.
+ * Reserves memory for additional elements.
+ *
+ * This function checks if the @p capacity of the array is sufficient to hold
+ * at least @p size plus @p elem_count elements. If not, a reallocation is
+ * performed with the specified @p reallocator.
+ * You can create your own reallocator by hand, use #cx_array_default_reallocator,
+ * or use the convenience function cx_array_reallocator() to create a custom reallocator.
+ *
+ * This function can be useful to replace subsequent calls to cx_array_copy()
+ * with one single cx_array_reserve() and then - after guaranteeing a
+ * sufficient capacity - use simple memmove() or memcpy().
+ *
+ * The @p width in bytes refers to the size and capacity.
+ * Both must have the same width.
+ * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit
+ * architecture. If set to zero, the native word width is used.
+ *
+ * @param array a pointer to the target array
+ * @param size a pointer to the size of the array
+ * @param capacity a pointer to the capacity of the array
+ * @param width the width in bytes for the @p size and @p capacity or zero for default
+ * @param elem_size the size of one element
+ * @param elem_count the number of expected additional elements
+ * @param reallocator the array reallocator to use
+ * (@c NULL defaults to #cx_array_default_reallocator)
+ * @retval zero success
+ * @retval non-zero failure
+ * @see cx_array_reallocator()
  */
-enum cx_array_result {
-    CX_ARRAY_SUCCESS,
-    CX_ARRAY_REALLOC_NOT_SUPPORTED,
-    CX_ARRAY_REALLOC_FAILED,
-};
+cx_attr_nonnull_arg(1, 2, 3)
+int cx_array_reserve(
+        void **array,
+        void *size,
+        void *capacity,
+        unsigned width,
+        size_t elem_size,
+        size_t elem_count,
+        CxArrayReallocator *reallocator
+);
 
 /**
  * Copies elements from one array to another.
  *
- * The elements are copied to the \p target array at the specified \p index,
- * overwriting possible elements. The \p index does not need to be in range of
- * the current array \p size. If the new index plus the number of elements added
- * would extend the array's size, and \p capacity is not \c NULL, the remaining
- * capacity is used.
+ * The elements are copied to the @p target array at the specified @p index,
+ * overwriting possible elements. The @p index does not need to be in range of
+ * the current array @p size. If the new index plus the number of elements added
+ * would extend the array's size, the remaining @p capacity is used.
  *
- * If the capacity is insufficient to hold the new data, a reallocation
- * attempt is made, unless the \p reallocator is set to \c NULL, in which case
- * this function ultimately returns a failure.
+ * If the @p capacity is also insufficient to hold the new data, a reallocation
+ * attempt is made with the specified @p reallocator.
+ * You can create your own reallocator by hand, use #cx_array_default_reallocator,
+ * or use the convenience function cx_array_reallocator() to create a custom reallocator.
+ *
+ * The @p width in bytes refers to the size and capacity.
+ * Both must have the same width.
+ * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit
+ * architecture. If set to zero, the native word width is used.
  *
  * @param target a pointer to the target array
  * @param size a pointer to the size of the target array
- * @param capacity a pointer to the target array's capacity -
- * \c NULL if only the size shall be used to bound the array (reallocations
- * will NOT be supported in that case)
+ * @param capacity a pointer to the capacity of the target array
+ * @param width the width in bytes for the @p size and @p capacity or zero for default
  * @param index the index where the copied elements shall be placed
  * @param src the source array
  * @param elem_size the size of one element
  * @param elem_count the number of elements to copy
- * @param reallocator the array reallocator to use, or \c NULL
- * if reallocation shall not happen
- * @return zero on success, non-zero error code on failure
+ * @param reallocator the array reallocator to use
+ * (@c NULL defaults to #cx_array_default_reallocator)
+ * @retval zero success
+ * @retval non-zero failure
+ * @see cx_array_reallocator()
  */
-__attribute__((__nonnull__(1, 2, 5)))
-enum cx_array_result cx_array_copy(
+cx_attr_nonnull_arg(1, 2, 3, 6)
+int cx_array_copy(
         void **target,
-        size_t *size,
-        size_t *capacity,
+        void *size,
+        void *capacity,
+        unsigned width,
         size_t index,
         const void *src,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 );
 
 /**
- * Convenience macro that uses cx_array_copy() with a default layout and the default reallocator.
+ * Convenience macro that uses cx_array_copy() with a default layout and
+ * the specified reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
- * @param index the index where the copied elements shall be placed
- * @param src the source array
- * @param count the number of elements to copy
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param index (@c size_t) the index where the copied elements shall be placed
+ * @param src (@c void*) the source array
+ * @param count (@c size_t) the number of elements to copy
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_copy()
+ */
+#define cx_array_simple_copy_a(reallocator, array, index, src, count) \
+    cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \
+        sizeof(array##_size), index, src, sizeof((array)[0]), count, \
+        reallocator)
+
+/**
+ * Convenience macro that uses cx_array_copy() with a default layout and
+ * the default reallocator.
+ *
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param index (@c size_t) the index where the copied elements shall be placed
+ * @param src (@c void*) the source array
+ * @param count (@c size_t) the number of elements to copy
+ * @retval zero success
+ * @retval non-zero failure
+ * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_copy_a()
  */
 #define cx_array_simple_copy(array, index, src, count) \
-    cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \
-    index, src, sizeof((array)[0]), count, cx_array_default_reallocator)
+    cx_array_simple_copy_a(NULL, array, index, src, count)
+
+/**
+ * Convenience macro that uses cx_array_reserve() with a default layout and
+ * the specified reallocator.
+ *
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param count (@c size_t) the number of expected @em additional elements
+ * @retval zero success
+ * @retval non-zero failure
+ * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_reserve()
+ */
+#define cx_array_simple_reserve_a(reallocator, array, count) \
+    cx_array_reserve((void**)&(array), &(array##_size), &(array##_capacity), \
+        sizeof(array##_size), sizeof((array)[0]), count, \
+        reallocator)
+
+/**
+ * Convenience macro that uses cx_array_reserve() with a default layout and
+ * the default reallocator.
+ *
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param count (@c size_t) the number of expected additional elements
+ * @retval zero success
+ * @retval non-zero failure
+ * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_reserve_a()
+ */
+#define cx_array_simple_reserve(array, count) \
+    cx_array_simple_reserve_a(NULL, array, count)
 
 /**
  * Adds an element to an array with the possibility of allocating more space.
  *
- * The element \p elem is added to the end of the \p target array which containing
- * \p size elements, already. The \p capacity must not be \c NULL and point a
- * variable holding the current maximum number of elements the array can hold.
+ * The element @p elem is added to the end of the @p target array which contains
+ * @p size elements, already. The @p capacity must point to a variable denoting
+ * the current maximum number of elements the array can hold.
  *
- * If the capacity is insufficient to hold the new element, and the optional
- * \p reallocator is not \c NULL, an attempt increase the \p capacity is made
- * and the new capacity is written back.
+ * If the capacity is insufficient to hold the new element, an attempt to
+ * increase the @p capacity is made and the new capacity is written back.
  *
- * @param target a pointer to the target array
- * @param size a pointer to the size of the target array
- * @param capacity a pointer to the target array's capacity - must not be \c NULL
- * @param elem_size the size of one element
- * @param elem a pointer to the element to add
- * @param reallocator the array reallocator to use, or \c NULL if reallocation shall not happen
- * @return zero on success, non-zero error code on failure
+ * The \@ SIZE_TYPE is flexible and can be any unsigned integer type.
+ * It is important, however, that @p size and @p capacity are pointers to
+ * variables of the same type.
+ *
+ * @param target (@c void**) a pointer to the target array
+ * @param size (@c SIZE_TYPE*) a pointer to the size of the target array
+ * @param capacity (@c SIZE_TYPE*) a pointer to the capacity of the target array
+ * @param elem_size (@c size_t) the size of one element
+ * @param elem (@c void*) a pointer to the element to add
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @retval zero success
+ * @retval non-zero failure
  */
 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \
-    cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator)
+    cx_array_copy((void**)(target), size, capacity, sizeof(*(size)), \
+    *(size), elem, elem_size, 1, reallocator)
+
+/**
+ * Convenience macro that uses cx_array_add() with a default layout and
+ * the specified reallocator.
+ *
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param elem the element to add (NOT a pointer, address is automatically taken)
+ * @retval zero success
+ * @retval non-zero failure
+ * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_add()
+ */
+#define cx_array_simple_add_a(reallocator, array, elem) \
+    cx_array_simple_copy_a(reallocator, array, array##_size, &(elem), 1)
 
 /**
  * Convenience macro that uses cx_array_add() with a default layout and
  * the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
+ * @param array the name of the array (NOT a pointer or alias to the array)
  * @param elem the element to add (NOT a pointer, address is automatically taken)
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_add_a()
  */
 #define cx_array_simple_add(array, elem) \
-    cx_array_simple_copy(array, array##_size, &(elem), 1)
-
+    cx_array_simple_add_a(cx_array_default_reallocator, array, elem)
 
 /**
  * Inserts a sorted array into another sorted array.
  *
  * If either the target or the source array is not already sorted with respect
- * to the specified \p cmp_func, the behavior is undefined.
+ * to the specified @p cmp_func, the behavior is undefined.
  *
  * If the capacity is insufficient to hold the new data, a reallocation
  * attempt is made.
+ * You can create your own reallocator by hand, use #cx_array_default_reallocator,
+ * or use the convenience function cx_array_reallocator() to create a custom reallocator.
  *
  * @param target a pointer to the target array
  * @param size a pointer to the size of the target array
- * @param capacity a pointer to the target array's capacity
+ * @param capacity a pointer to the capacity of the target array
  * @param cmp_func the compare function for the elements
  * @param src the source array
  * @param elem_size the size of one element
  * @param elem_count the number of elements to insert
  * @param reallocator the array reallocator to use
- * @return zero on success, non-zero error code on failure
+ * (@c NULL defaults to #cx_array_default_reallocator)
+ * @retval zero success
+ * @retval non-zero failure
  */
-__attribute__((__nonnull__))
-enum cx_array_result cx_array_insert_sorted(
+cx_attr_nonnull_arg(1, 2, 3, 5)
+int cx_array_insert_sorted(
         void **target,
         size_t *size,
         size_t *capacity,
@@ -246,68 +483,112 @@
         const void *src,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 );
 
 /**
  * Inserts an element into a sorted array.
  *
  * If the target array is not already sorted with respect
- * to the specified \p cmp_func, the behavior is undefined.
+ * to the specified @p cmp_func, the behavior is undefined.
  *
  * If the capacity is insufficient to hold the new data, a reallocation
  * attempt is made.
  *
- * @param target a pointer to the target array
- * @param size a pointer to the size of the target array
- * @param capacity a pointer to the target array's capacity
- * @param elem_size the size of one element
- * @param elem a pointer to the element to add
- * @param reallocator the array reallocator to use
- * @return zero on success, non-zero error code on failure
+ * The \@ SIZE_TYPE is flexible and can be any unsigned integer type.
+ * It is important, however, that @p size and @p capacity are pointers to
+ * variables of the same type.
+ *
+ * @param target (@c void**) a pointer to the target array
+ * @param size (@c SIZE_TYPE*) a pointer to the size of the target array
+ * @param capacity (@c SIZE_TYPE*) a pointer to the capacity of the target array
+ * @param elem_size (@c size_t) the size of one element
+ * @param elem (@c void*) a pointer to the element to add
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @retval zero success
+ * @retval non-zero failure
  */
 #define cx_array_add_sorted(target, size, capacity, elem_size, elem, cmp_func, reallocator) \
     cx_array_insert_sorted((void**)(target), size, capacity, cmp_func, elem, elem_size, 1, reallocator)
 
 /**
  * Convenience macro for cx_array_add_sorted() with a default
+ * layout and the specified reallocator.
+ *
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param elem the element to add (NOT a pointer, address is automatically taken)
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
+ * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_add_sorted()
+ */
+#define cx_array_simple_add_sorted_a(reallocator, array, elem, cmp_func) \
+    cx_array_add_sorted(&array, &(array##_size), &(array##_capacity), \
+        sizeof((array)[0]), &(elem), cmp_func, reallocator)
+
+/**
+ * Convenience macro for cx_array_add_sorted() with a default
  * layout and the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
+ * @param array the name of the array (NOT a pointer or alias to the array)
  * @param elem the element to add (NOT a pointer, address is automatically taken)
- * @param cmp_func the compare function for the elements
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_add_sorted_a()
  */
 #define cx_array_simple_add_sorted(array, elem, cmp_func) \
-    cx_array_add_sorted(&array, &(array##_size), &(array##_capacity), \
-        sizeof((array)[0]), &(elem), cmp_func, cx_array_default_reallocator)
+    cx_array_simple_add_sorted_a(NULL, array, elem, cmp_func)
+
+/**
+ * Convenience macro for cx_array_insert_sorted() with a default
+ * layout and the specified reallocator.
+ *
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param src (@c void*) pointer to the source array
+ * @param n (@c size_t) number of elements in the source array
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
+ * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_insert_sorted()
+ */
+#define cx_array_simple_insert_sorted_a(reallocator, array, src, n, cmp_func) \
+    cx_array_insert_sorted((void**)(&array), &(array##_size), &(array##_capacity), \
+        cmp_func, src, sizeof((array)[0]), n, reallocator)
 
 /**
  * Convenience macro for cx_array_insert_sorted() with a default
  * layout and the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
- * @param src pointer to the source array
- * @param n number of elements in the source array
- * @param cmp_func the compare function for the elements
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param src (@c void*) pointer to the source array
+ * @param n (@c size_t) number of elements in the source array
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
+ * @see cx_array_simple_insert_sorted_a()
  */
 #define cx_array_simple_insert_sorted(array, src, n, cmp_func) \
-    cx_array_insert_sorted((void**)(&array), &(array##_size), &(array##_capacity), \
-        cmp_func, src, sizeof((array)[0]), n, cx_array_default_reallocator)
-
+    cx_array_simple_insert_sorted_a(NULL, array, src, n, cmp_func)
 
 /**
  * Searches the largest lower bound in a sorted array.
  *
  * In other words, this function returns the index of the largest element
- * in \p arr that is less or equal to \p elem with respect to \p cmp_func.
- * When no such element exists, \p size is returned.
+ * in @p arr that is less or equal to @p elem with respect to @p cmp_func.
+ * When no such element exists, @p size is returned.
  *
- * If \p elem is contained in the array, this is identical to
+ * If @p elem is contained in the array, this is identical to
  * #cx_array_binary_search().
  *
- * If the array is not sorted with respect to the \p cmp_func, the behavior
+ * If the array is not sorted with respect to the @p cmp_func, the behavior
  * is undefined.
  *
  * @param arr the array to search
@@ -315,9 +596,11 @@
  * @param elem_size the size of one element
  * @param elem the element to find
  * @param cmp_func the compare function
- * @return the index of the largest lower bound, or \p size
+ * @return the index of the largest lower bound, or @p size
+ * @see cx_array_binary_search_sup()
+ * @see cx_array_binary_search()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cx_array_binary_search_inf(
         const void *arr,
         size_t size,
@@ -329,7 +612,7 @@
 /**
  * Searches an item in a sorted array.
  *
- * If the array is not sorted with respect to the \p cmp_func, the behavior
+ * If the array is not sorted with respect to the @p cmp_func, the behavior
  * is undefined.
  *
  * @param arr the array to search
@@ -337,38 +620,31 @@
  * @param elem_size the size of one element
  * @param elem the element to find
  * @param cmp_func the compare function
- * @return the index of the element in the array, or \p size if the element
+ * @return the index of the element in the array, or @p size if the element
  * cannot be found
+ * @see cx_array_binary_search_inf()
+ * @see cx_array_binary_search_sup()
  */
-__attribute__((__nonnull__))
-static inline size_t cx_array_binary_search(
+cx_attr_nonnull
+size_t cx_array_binary_search(
         const void *arr,
         size_t size,
         size_t elem_size,
         const void *elem,
         cx_compare_func cmp_func
-) {
-    size_t index = cx_array_binary_search_inf(
-            arr, size, elem_size, elem, cmp_func
-    );
-    if (index < size && cmp_func(((const char *) arr) + index * elem_size, elem) == 0) {
-        return index;
-    } else {
-        return size;
-    }
-}
+);
 
 /**
  * Searches the smallest upper bound in a sorted array.
  *
  * In other words, this function returns the index of the smallest element
- * in \p arr that is greater or equal to \p elem with respect to \p cmp_func.
- * When no such element exists, \p size is returned.
+ * in @p arr that is greater or equal to @p elem with respect to @p cmp_func.
+ * When no such element exists, @p size is returned.
  *
- * If \p elem is contained in the array, this is identical to
+ * If @p elem is contained in the array, this is identical to
  * #cx_array_binary_search().
  *
- * If the array is not sorted with respect to the \p cmp_func, the behavior
+ * If the array is not sorted with respect to the @p cmp_func, the behavior
  * is undefined.
  *
  * @param arr the array to search
@@ -376,26 +652,18 @@
  * @param elem_size the size of one element
  * @param elem the element to find
  * @param cmp_func the compare function
- * @return the index of the smallest upper bound, or \p size
+ * @return the index of the smallest upper bound, or @p size
+ * @see cx_array_binary_search_inf()
+ * @see cx_array_binary_search()
  */
-__attribute__((__nonnull__))
-static inline size_t cx_array_binary_search_sup(
+cx_attr_nonnull
+size_t cx_array_binary_search_sup(
         const void *arr,
         size_t size,
         size_t elem_size,
         const void *elem,
         cx_compare_func cmp_func
-) {
-    size_t inf = cx_array_binary_search_inf(arr, size, elem_size, elem, cmp_func);
-    if (inf == size) {
-        // no infimum means, first element is supremum
-        return 0;
-    } else if (cmp_func(((const char *) arr) + inf * elem_size, elem) == 0) {
-        return inf;
-    } else {
-        return inf + 1;
-    }
-}
+);
 
 /**
  * Swaps two array elements.
@@ -405,7 +673,7 @@
  * @param idx1 index of first element
  * @param idx2 index of second element
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cx_array_swap(
         void *arr,
         size_t elem_size,
@@ -414,21 +682,24 @@
 );
 
 /**
- * Allocates an array list for storing elements with \p elem_size bytes each.
+ * Allocates an array list for storing elements with @p elem_size bytes each.
  *
- * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if
+ * If @p elem_size is CX_STORE_POINTERS, the created list will be created as if
  * cxListStorePointers() was called immediately after creation and the compare
  * function will be automatically set to cx_cmp_ptr(), if none is given.
  *
  * @param allocator the allocator for allocating the list memory
- * (if \c NULL the cxDefaultAllocator will be used)
+ * (if @c NULL, a default stdlib allocator will be used)
  * @param comparator the comparator for the elements
- * (if \c NULL, and the list is not storing pointers, sort and find
+ * (if @c NULL, and the list is not storing pointers, sort and find
  * functions will not work)
  * @param elem_size the size of each element in bytes
  * @param initial_capacity the initial number of elements the array can store
  * @return the created list
  */
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc(cxListFree, 1)
 CxList *cxArrayListCreate(
         const CxAllocator *allocator,
         cx_compare_func comparator,
@@ -437,18 +708,18 @@
 );
 
 /**
- * Allocates an array list for storing elements with \p elem_size bytes each.
+ * Allocates an array list for storing elements with @p elem_size bytes each.
  *
- * The list will use the cxDefaultAllocator and \em NO compare function.
+ * The list will use the cxDefaultAllocator and @em NO compare function.
  * If you want to call functions that need a compare function, you have to
  * set it immediately after creation or use cxArrayListCreate().
  *
- * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if
+ * If @p elem_size is CX_STORE_POINTERS, the created list will be created as if
  * cxListStorePointers() was called immediately after creation and the compare
  * function will be automatically set to cx_cmp_ptr().
  *
- * @param elem_size the size of each element in bytes
- * @param initial_capacity the initial number of elements the array can store
+ * @param elem_size (@c size_t) the size of each element in bytes
+ * @param initial_capacity (@c size_t) the initial number of elements the array can store
  * @return the created list
  */
 #define cxArrayListCreateSimple(elem_size, initial_capacity) \

--- a/ucx/cx/buffer.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/buffer.h	Sun Jan 05 22:00:39 2025 +0100
@@ -27,9 +27,9 @@
  */
 
 /**
- * \file buffer.h
+ * @file buffer.h
  *
- * \brief Advanced buffer implementation.
+ * @brief Advanced buffer implementation.
  *
  * Instances of CxBuffer can be used to read from or to write to like one
  * would do with a stream.
@@ -38,9 +38,9 @@
  * can be enabled. See the documentation of the macro constants for more
  * information.
  *
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 #ifndef UCX_BUFFER_H
@@ -49,7 +49,7 @@
 #include "common.h"
 #include "allocator.h"
 
-#ifdef    __cplusplus
+#ifdef __cplusplus
 extern "C" {
 #endif
 
@@ -60,16 +60,90 @@
 
 /**
  * If this flag is enabled, the buffer will automatically free its contents when destroyed.
+ *
+ * Do NOT set this flag together with #CX_BUFFER_COPY_ON_WRITE. It will be automatically
+ * set when the copy-on-write operations is performed.
  */
 #define CX_BUFFER_FREE_CONTENTS 0x01
 
 /**
- * If this flag is enabled, the buffer will automatically extends its capacity.
+ * If this flag is enabled, the buffer will automatically extend its capacity.
  */
 #define CX_BUFFER_AUTO_EXTEND 0x02
 
+/**
+ * If this flag is enabled, the buffer will allocate new memory when written to.
+ *
+ * The current contents of the buffer will be copied to the new memory and the flag
+ * will be cleared while the #CX_BUFFER_FREE_CONTENTS flag will be set automatically.
+ */
+#define CX_BUFFER_COPY_ON_WRITE 0x04
+
+/**
+ * If this flag is enabled, the buffer will copy its contents to a new memory area on reallocation.
+ *
+ * After performing the copy, the flag is automatically cleared.
+ * This flag has no effect on buffers which do not have #CX_BUFFER_AUTO_EXTEND set, which is why
+ * buffers automatically admit the auto-extend flag when initialized with copy-on-extend enabled.
+ */
+#define CX_BUFFER_COPY_ON_EXTEND 0x08
+
+/**
+ * Configuration for automatic flushing.
+ */
+struct cx_buffer_flush_config_s {
+    /**
+     * The buffer may not extend beyond this threshold before starting to flush.
+     *
+     * Only used when the buffer uses #CX_BUFFER_AUTO_EXTEND.
+     * The threshold will be the maximum capacity the buffer is extended to
+     * before flushing.
+     */
+    size_t threshold;
+    /**
+     * The block size for the elements to flush.
+     */
+    size_t blksize;
+    /**
+     * The maximum number of blocks to flush in one cycle.
+     *
+     * @attention while it is guaranteed that cxBufferFlush() will not flush
+     * more blocks, this is not necessarily the case for cxBufferWrite().
+     * After performing a flush cycle, cxBufferWrite() will retry the write
+     * operation and potentially trigger another flush cycle, until the
+     * flush target accepts no more data.
+     */
+    size_t blkmax;
+
+    /**
+     * The target for write function.
+     */
+    void *target;
+
+    /**
+     * The write-function used for flushing.
+     * If NULL, the flushed content gets discarded.
+     */
+    cx_write_func wfunc;
+};
+
+/**
+ * Type alais for the flush configuration struct.
+ *
+ * @code
+ * struct cx_buffer_flush_config_s {
+ *     size_t threshold;
+ *     size_t blksize;
+ *     size_t blkmax;
+ *     void *target;
+ *     cx_write_func wfunc;
+ * };
+ * @endcode
+ */
+typedef struct cx_buffer_flush_config_s CxBufferFlushConfig;
+
 /** Structure for the UCX buffer data. */
-typedef struct {
+struct cx_buffer_s {
     /** A pointer to the buffer contents. */
     union {
         /**
@@ -83,6 +157,12 @@
     };
     /** The allocator to use for automatic memory management. */
     const CxAllocator *allocator;
+    /**
+     * Optional flush configuration
+     *
+     * @see cxBufferEnableFlushing()
+     */
+    CxBufferFlushConfig* flush;
     /** Current position of the buffer. */
     size_t pos;
     /** Current capacity (i.e. maximum size) of the buffer. */
@@ -90,70 +170,52 @@
     /** Current size of the buffer content. */
     size_t size;
     /**
-     * The buffer may not extend beyond this threshold before starting to flush.
-     * Default is \c SIZE_MAX (flushing disabled when auto extension is enabled).
-     */
-    size_t flush_threshold;
-    /**
-     * The block size for the elements to flush.
-     * Default is 4096 bytes.
-     */
-    size_t flush_blksize;
-    /**
-     * The maximum number of blocks to flush in one cycle.
-     * Zero disables flushing entirely (this is the default).
-     * Set this to \c SIZE_MAX to flush the entire buffer.
-     *
-     * @attention if the maximum number of blocks multiplied with the block size
-     * is smaller than the expected contents written to this buffer within one write
-     * operation, multiple flush cycles are performed after that write.
-     * That means the total number of blocks flushed after one write to this buffer may
-     * be larger than \c flush_blkmax.
-     */
-    size_t flush_blkmax;
-
-    /**
-     * The write function used for flushing.
-     * If NULL, the flushed content gets discarded.
-     */
-    cx_write_func flush_func;
-
-    /**
-     * The target for \c flush_func.
-     */
-    void *flush_target;
-
-    /**
      * Flag register for buffer features.
      * @see #CX_BUFFER_DEFAULT
      * @see #CX_BUFFER_FREE_CONTENTS
      * @see #CX_BUFFER_AUTO_EXTEND
+     * @see #CX_BUFFER_COPY_ON_WRITE
      */
     int flags;
-} cx_buffer_s;
+};
 
 /**
  * UCX buffer.
  */
-typedef cx_buffer_s CxBuffer;
+typedef struct cx_buffer_s CxBuffer;
 
 /**
  * Initializes a fresh buffer.
  *
- * \note You may provide \c NULL as argument for \p space.
+ * You may also provide a read-only @p space, in which case
+ * you will need to cast the pointer, and you should set the
+ * #CX_BUFFER_COPY_ON_WRITE flag.
+ *
+ * You need to set the size manually after initialization, if
+ * you provide @p space which already contains data.
+ *
+ * When you specify stack memory as @p space and decide to use
+ * the auto-extension feature, you @em must use the
+ * #CX_BUFFER_COPY_ON_EXTEND flag, instead of the
+ * #CX_BUFFER_AUTO_EXTEND flag.
+ *
+ * @note You may provide @c NULL as argument for @p space.
  * Then this function will allocate the space and enforce
- * the #CX_BUFFER_FREE_CONTENTS flag.
+ * the #CX_BUFFER_FREE_CONTENTS flag. In that case, specifying
+ * copy-on-write should be avoided, because the allocated
+ * space will be leaking after the copy-on-write operation.
  *
  * @param buffer the buffer to initialize
- * @param space pointer to the memory area, or \c NULL to allocate
+ * @param space pointer to the memory area, or @c NULL to allocate
  * new memory
  * @param capacity the capacity of the buffer
  * @param allocator the allocator this buffer shall use for automatic
- * memory management. If \c NULL, the default heap allocator will be used.
+ * memory management
+ * (if @c NULL, a default stdlib allocator will be used)
  * @param flags buffer features (see cx_buffer_s.flags)
  * @return zero on success, non-zero if a required allocation failed
  */
-__attribute__((__nonnull__(1)))
+cx_attr_nonnull_arg(1)
 int cxBufferInit(
         CxBuffer *buffer,
         void *space,
@@ -163,25 +225,23 @@
 );
 
 /**
- * Allocates and initializes a fresh buffer.
+ * Configures the buffer for flushing.
  *
- * \note You may provide \c NULL as argument for \p space.
- * Then this function will allocate the space and enforce
- * the #CX_BUFFER_FREE_CONTENTS flag.
+ * Flushing can happen automatically when data is written
+ * to the buffer (see cxBufferWrite()) or manually when
+ * cxBufferFlush() is called.
  *
- * @param space pointer to the memory area, or \c NULL to allocate
- * new memory
- * @param capacity the capacity of the buffer
- * @param allocator the allocator to use for allocating the structure and the automatic
- * memory management within the buffer. If \c NULL, the default heap allocator will be used.
- * @param flags buffer features (see cx_buffer_s.flags)
- * @return a pointer to the buffer on success, \c NULL if a required allocation failed
+ * @param buffer the buffer
+ * @param config the flush configuration
+ * @retval zero success
+ * @retval non-zero failure
+ * @see cxBufferFlush()
+ * @see cxBufferWrite()
  */
-CxBuffer *cxBufferCreate(
-        void *space,
-        size_t capacity,
-        const CxAllocator *allocator,
-        int flags
+cx_attr_nonnull
+int cxBufferEnableFlushing(
+    CxBuffer *buffer,
+    CxBufferFlushConfig config
 );
 
 /**
@@ -193,22 +253,58 @@
  * @param buffer the buffer which contents shall be destroyed
  * @see cxBufferInit()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxBufferDestroy(CxBuffer *buffer);
 
 /**
  * Deallocates the buffer.
  *
  * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys
- * the contents. If you \em only want to destroy the contents, use cxBufferDestroy().
+ * the contents. If you @em only want to destroy the contents, use cxBufferDestroy().
+ *
+ * @remark As with all free() functions, this accepts @c NULL arguments in which
+ * case it does nothing.
  *
  * @param buffer the buffer to deallocate
  * @see cxBufferCreate()
  */
-__attribute__((__nonnull__))
 void cxBufferFree(CxBuffer *buffer);
 
 /**
+ * Allocates and initializes a fresh buffer.
+ *
+ * You may also provide a read-only @p space, in which case
+ * you will need to cast the pointer, and you should set the
+ * #CX_BUFFER_COPY_ON_WRITE flag.
+ * When you specify stack memory as @p space and decide to use
+ * the auto-extension feature, you @em must use the
+ * #CX_BUFFER_COPY_ON_EXTEND flag, instead of the
+ * #CX_BUFFER_AUTO_EXTEND flag.
+ *
+ * @note You may provide @c NULL as argument for @p space.
+ * Then this function will allocate the space and enforce
+ * the #CX_BUFFER_FREE_CONTENTS flag.
+ *
+ * @param space pointer to the memory area, or @c NULL to allocate
+ * new memory
+ * @param capacity the capacity of the buffer
+ * @param allocator the allocator to use for allocating the structure and the automatic
+ * memory management within the buffer
+ * (if @c NULL, a default stdlib allocator will be used)
+ * @param flags buffer features (see cx_buffer_s.flags)
+ * @return a pointer to the buffer on success, @c NULL if a required allocation failed
+ */
+cx_attr_malloc
+cx_attr_dealloc(cxBufferFree, 1)
+cx_attr_nodiscard
+CxBuffer *cxBufferCreate(
+        void *space,
+        size_t capacity,
+        const CxAllocator *allocator,
+        int flags
+);
+
+/**
  * Shifts the contents of the buffer by the given offset.
  *
  * If the offset is positive, the contents are shifted to the right.
@@ -219,7 +315,7 @@
  * are discarded.
  *
  * If the offset is negative, the contents are shifted to the left where the
- * first \p shift bytes are discarded.
+ * first @p shift bytes are discarded.
  * The new size of the buffer is the old size minus the absolute shift value.
  * If this value is larger than the buffer size, the buffer is emptied (but
  * not cleared, see the security note below).
@@ -227,11 +323,11 @@
  * The buffer position gets shifted alongside with the content but is kept
  * within the boundaries of the buffer.
  *
- * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and
- * cxBufferShiftRight() functions using a \c size_t as parameter type.
+ * @note For situations where @c off_t is not large enough, there are specialized cxBufferShiftLeft() and
+ * cxBufferShiftRight() functions using a @c size_t as parameter type.
  *
- * \attention
- * Security Note: The shifting operation does \em not erase the previously occupied memory cells.
+ * @attention
+ * Security Note: The shifting operation does @em not erase the previously occupied memory cells.
  * But you can easily do that manually, e.g. by calling
  * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or
  * <code>memset(buffer->bytes + buffer->size, 0, buffer->capacity - buffer->size)</code>
@@ -239,9 +335,12 @@
  *
  * @param buffer the buffer
  * @param shift the shift offset (negative means left shift)
- * @return 0 on success, non-zero if a required auto-extension fails
+ * @retval zero success
+ * @retval non-zero if a required auto-extension or copy-on-write fails
+ * @see cxBufferShiftLeft()
+ * @see cxBufferShiftRight()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferShift(
         CxBuffer *buffer,
         off_t shift
@@ -253,10 +352,11 @@
  *
  * @param buffer the buffer
  * @param shift the shift offset
- * @return 0 on success, non-zero if a required auto-extension fails
+ * @retval zero success
+ * @retval non-zero if a required auto-extension or copy-on-write fails
  * @see cxBufferShift()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferShiftRight(
         CxBuffer *buffer,
         size_t shift
@@ -266,15 +366,13 @@
  * Shifts the buffer to the left.
  * See cxBufferShift() for details.
  *
- * \note Since a left shift cannot fail due to memory allocation problems, this
- * function always returns zero.
- *
  * @param buffer the buffer
  * @param shift the positive shift offset
- * @return always zero
+ * @retval zero success
+ * @retval non-zero if the buffer uses copy-on-write and the allocation fails
  * @see cxBufferShift()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferShiftLeft(
         CxBuffer *buffer,
         size_t shift
@@ -284,23 +382,24 @@
 /**
  * Moves the position of the buffer.
  *
- * The new position is relative to the \p whence argument.
+ * The new position is relative to the @p whence argument.
  *
- * \li \c SEEK_SET marks the start of the buffer.
- * \li \c SEEK_CUR marks the current position.
- * \li \c SEEK_END marks the end of the buffer.
+ * @li @c SEEK_SET marks the start of the buffer.
+ * @li @c SEEK_CUR marks the current position.
+ * @li @c SEEK_END marks the end of the buffer.
  *
  * With an offset of zero, this function sets the buffer position to zero
- * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position
- * unchanged (\c SEEK_CUR).
+ * (@c SEEK_SET), the buffer size (@c SEEK_END) or leaves the buffer position
+ * unchanged (@c SEEK_CUR).
  *
  * @param buffer the buffer
- * @param offset position offset relative to \p whence
- * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
- * @return 0 on success, non-zero if the position is invalid
+ * @param offset position offset relative to @p whence
+ * @param whence one of @c SEEK_SET, @c SEEK_CUR or @c SEEK_END
+ * @retval zero success
+ * @retval non-zero if the position is invalid
  *
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferSeek(
         CxBuffer *buffer,
         off_t offset,
@@ -313,10 +412,13 @@
  * The data is deleted by zeroing it with a call to memset().
  * If you do not need that, you can use the faster cxBufferReset().
  *
+ * @note If the #CX_BUFFER_COPY_ON_WRITE flag is set, this function
+ * will not erase the data and behave exactly as cxBufferReset().
+ *
  * @param buffer the buffer to be cleared
  * @see cxBufferReset()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxBufferClear(CxBuffer *buffer);
 
 /**
@@ -328,18 +430,20 @@
  * @param buffer the buffer to be cleared
  * @see cxBufferClear()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxBufferReset(CxBuffer *buffer);
 
 /**
  * Tests, if the buffer position has exceeded the buffer size.
  *
  * @param buffer the buffer to test
- * @return non-zero, if the current buffer position has exceeded the last
- * byte of the buffer's contents.
+ * @retval true if the current buffer position has exceeded the last
+ * byte of the buffer's contents
+ * @retval false otherwise
  */
-__attribute__((__nonnull__))
-int cxBufferEof(const CxBuffer *buffer);
+cx_attr_nonnull
+cx_attr_nodiscard
+bool cxBufferEof(const CxBuffer *buffer);
 
 
 /**
@@ -349,9 +453,10 @@
  *
  * @param buffer the buffer
  * @param capacity the minimum required capacity for this buffer
- * @return 0 on success or a non-zero value on failure
+ * @retval zero the capacity was already sufficient or successfully increased
+ * @retval non-zero on allocation failure
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferMinimumCapacity(
         CxBuffer *buffer,
         size_t capacity
@@ -360,6 +465,10 @@
 /**
  * Writes data to a CxBuffer.
  *
+ * If automatic flushing is not enabled, the data is simply written into the
+ * buffer at the current position and the position of the buffer is increased
+ * by the number of bytes written.
+ *
  * If flushing is enabled and the buffer needs to flush, the data is flushed to
  * the target until the target signals that it cannot take more data by
  * returning zero via the respective write function. In that case, the remaining
@@ -367,23 +476,23 @@
  * newly available space can be used to append as much data as possible. This
  * function only stops writing more elements, when the flush target and this
  * buffer are both incapable of taking more data or all data has been written.
- * The number returned by this function is the total number of elements that
- * could be written during the process. It does not necessarily mean that those
- * elements are still in this buffer, because some of them could have also be
- * flushed already.
+ * If number of items that shall be written is larger than the buffer can hold,
+ * the first items from @c ptr are directly relayed to the flush target, if
+ * possible.
+ * The number returned by this function is only the number of elements from
+ * @c ptr that could be written to either the flush target or the buffer.
  *
- * If automatic flushing is not enabled, the position of the buffer is increased
- * by the number of bytes written.
- *
- * \note The signature is compatible with the fwrite() family of functions.
+ * @note The signature is compatible with the fwrite() family of functions.
  *
  * @param ptr a pointer to the memory area containing the bytes to be written
  * @param size the length of one element
  * @param nitems the element count
  * @param buffer the CxBuffer to write to
  * @return the total count of elements written
+ * @see cxBufferAppend()
+ * @see cxBufferRead()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cxBufferWrite(
         const void *ptr,
         size_t size,
@@ -392,19 +501,104 @@
 );
 
 /**
+ * Appends data to a CxBuffer.
+ *
+ * The data is always appended to current data within the buffer,
+ * regardless of the current position.
+ * This is especially useful when the buffer is primarily meant for reading
+ * while additional data is added to the buffer occasionally.
+ * Consequently, the position of the buffer is unchanged after this operation.
+ *
+ * @note The signature is compatible with the fwrite() family of functions.
+ *
+ * @param ptr a pointer to the memory area containing the bytes to be written
+ * @param size the length of one element
+ * @param nitems the element count
+ * @param buffer the CxBuffer to write to
+ * @return the total count of elements written
+ * @see cxBufferWrite()
+ * @see cxBufferRead()
+ */
+cx_attr_nonnull
+size_t cxBufferAppend(
+        const void *ptr,
+        size_t size,
+        size_t nitems,
+        CxBuffer *buffer
+);
+
+/**
+ * Performs a single flush-run on the specified buffer.
+ *
+ * Does nothing when the position in the buffer is zero.
+ * Otherwise, the data until the current position minus
+ * one is considered for flushing.
+ * Note carefully that flushing will never exceed the
+ * current @em position, even when the size of the
+ * buffer is larger than the current position.
+ *
+ * One flush run will try to flush @c blkmax many
+ * blocks of size @c blksize until either the @p buffer
+ * has no more data to flush or the write function
+ * used for flushing returns zero.
+ *
+ * The buffer is shifted left for that many bytes
+ * the flush operation has successfully flushed.
+ *
+ * @par Example 1
+ * Assume you have a buffer with size 340 and you are
+ * at position 200. The flush configuration is
+ * @c blkmax=4 and @c blksize=64 .
+ * Assume that the entire flush operation is successful.
+ * All 200 bytes on the left hand-side from the current
+ * position are written.
+ * That means, the size of the buffer is now 140 and the
+ * position is zero.
+ *
+ * @par Example 2
+ * Same as Example 1, but now the @c blkmax is 1.
+ * The size of the buffer is now 276 and the position is 136.
+ *
+ * @par Example 3
+ * Same as Example 1, but now assume the flush target
+ * only accepts 100 bytes before returning zero.
+ * That means, the flush operations manages to flush
+ * one complete block and one partial block, ending
+ * up with a buffer with size 240 and position 100.
+ *
+ * @remark Just returns zero when flushing was not enabled with
+ * cxBufferEnableFlushing().
+ *
+ * @remark When the buffer uses copy-on-write, the memory
+ * is copied first, before attempting any flush.
+ * This is, however, considered an erroneous use of the
+ * buffer, because it does not make much sense to put
+ * readonly data into an UCX buffer for flushing, instead
+ * of writing it directly to the target.
+ *
+ * @param buffer the buffer
+ * @return the number of successfully flushed bytes
+ * @see cxBufferEnableFlushing()
+ */
+cx_attr_nonnull
+size_t cxBufferFlush(CxBuffer *buffer);
+
+/**
  * Reads data from a CxBuffer.
  *
  * The position of the buffer is increased by the number of bytes read.
  *
- * \note The signature is compatible with the fread() family of functions.
+ * @note The signature is compatible with the fread() family of functions.
  *
  * @param ptr a pointer to the memory area where to store the read data
  * @param size the length of one element
  * @param nitems the element count
  * @param buffer the CxBuffer to read from
  * @return the total number of elements read
+ * @see cxBufferWrite()
+ * @see cxBufferAppend()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cxBufferRead(
         void *ptr,
         size_t size,
@@ -417,30 +611,52 @@
  *
  * The least significant byte of the argument is written to the buffer. If the
  * end of the buffer is reached and #CX_BUFFER_AUTO_EXTEND feature is enabled,
- * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is
- * disabled or buffer extension fails, \c EOF is returned.
+ * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature
+ * is disabled or buffer extension fails, @c EOF is returned.
  *
  * On successful write, the position of the buffer is increased.
  *
+ * If you just want to write a null-terminator at the current position, you
+ * should use cxBufferTerminate() instead.
+ *
  * @param buffer the buffer to write to
  * @param c the character to write
- * @return the byte that has bean written or \c EOF when the end of the stream is
+ * @return the byte that has been written or @c EOF when the end of the stream is
  * reached and automatic extension is not enabled or not possible
+ * @see cxBufferTerminate()
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferPut(
         CxBuffer *buffer,
         int c
 );
 
 /**
+ * Writes a terminating zero to a buffer at the current position.
+ *
+ * On successful write, @em neither the position @em nor the size of the buffer is
+ * increased.
+ *
+ * The purpose of this function is to have the written data ready to be used as
+ * a C string.
+ *
+ * @param buffer the buffer to write to
+ * @return zero, if the terminator could be written, non-zero otherwise
+ */
+cx_attr_nonnull
+int cxBufferTerminate(CxBuffer *buffer);
+
+/**
  * Writes a string to a buffer.
  *
+ * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>.
+ *
  * @param buffer the buffer
  * @param str the zero-terminated string
  * @return the number of bytes written
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_cstr_arg(2)
 size_t cxBufferPutString(
         CxBuffer *buffer,
         const char *str
@@ -452,9 +668,9 @@
  * The current position of the buffer is increased after a successful read.
  *
  * @param buffer the buffer to read from
- * @return the character or \c EOF, if the end of the buffer is reached
+ * @return the character or @c EOF, if the end of the buffer is reached
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferGet(CxBuffer *buffer);
 
 #ifdef __cplusplus

--- a/ucx/cx/collection.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/collection.h	Sun Jan 05 22:00:39 2025 +0100
@@ -26,11 +26,11 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file collection.h
- * \brief Common definitions for various collection implementations.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file collection.h
+ * @brief Common definitions for various collection implementations.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 #ifndef UCX_COLLECTION_H
@@ -96,13 +96,21 @@
 
 /**
  * Use this macro to declare common members for a collection structure.
+ *
+ * @par Example Use
+ * @code
+ * struct MyCustomSet {
+ *     CX_COLLECTION_BASE;
+ *     MySetElements *data;
+ * }
+ * @endcode
  */
 #define CX_COLLECTION_BASE struct cx_collection_s collection
 
 /**
  * Sets a simple destructor function for this collection.
  *
- * @param c the collection
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
  * @param destr the destructor function
  */
 #define cxDefineDestructor(c, destr) \
@@ -111,7 +119,7 @@
 /**
  * Sets a simple destructor function for this collection.
  *
- * @param c the collection
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
  * @param destr the destructor function
  */
 #define cxDefineAdvancedDestructor(c, destr, data) \
@@ -124,8 +132,11 @@
  * Usually only used by collection implementations. There should be no need
  * to invoke this macro manually.
  *
- * @param c the collection
- * @param e the element
+ * When the collection stores pointers, those pointers are directly passed
+ * to the destructor. Otherwise, a pointer to the element is passed.
+ *
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+ * @param e the element (the type is @c void* or @c void** depending on context)
  */
 #define cx_invoke_simple_destructor(c, e) \
     (c)->collection.simple_destructor((c)->collection.store_pointer ? (*((void **) (e))) : (e))
@@ -136,8 +147,11 @@
  * Usually only used by collection implementations. There should be no need
  * to invoke this macro manually.
  *
- * @param c the collection
- * @param e the element
+ * When the collection stores pointers, those pointers are directly passed
+ * to the destructor. Otherwise, a pointer to the element is passed.
+ *
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+ * @param e the element (the type is @c void* or @c void** depending on context)
  */
 #define cx_invoke_advanced_destructor(c, e) \
     (c)->collection.advanced_destructor((c)->collection.destructor_data, \
@@ -150,8 +164,11 @@
  * Usually only used by collection implementations. There should be no need
  * to invoke this macro manually.
  *
- * @param c the collection
- * @param e the element
+ * When the collection stores pointers, those pointers are directly passed
+ * to the destructor. Otherwise, a pointer to the element is passed.
+ *
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+ * @param e the element (the type is @c void* or @c void** depending on context)
  */
 #define cx_invoke_destructor(c, e) \
     if ((c)->collection.simple_destructor) cx_invoke_simple_destructor(c,e); \

--- a/ucx/cx/common.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/common.h	Sun Jan 05 22:00:39 2025 +0100
@@ -27,15 +27,15 @@
  */
 
 /**
- * \file common.h
+ * @file common.h
  *
- * \brief Common definitions and feature checks.
+ * @brief Common definitions and feature checks.
  *
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  *
- * \mainpage UAP Common Extensions
+ * @mainpage UAP Common Extensions
  * Library with common and useful functions, macros and data structures.
  * <p>
  * Latest available source:<br>
@@ -88,7 +88,9 @@
 /** Version constant which ensures to increase monotonically. */
 #define UCX_VERSION (((UCX_VERSION_MAJOR)<<16)|UCX_VERSION_MINOR)
 
-// Common Includes
+// ---------------------------------------------------------------------------
+//       Common includes
+// ---------------------------------------------------------------------------
 
 #include <stdlib.h>
 #include <stddef.h>
@@ -96,7 +98,194 @@
 #include <stdint.h>
 #include <sys/types.h>
 
-#ifndef UCX_TEST_H
+// ---------------------------------------------------------------------------
+//       Architecture Detection
+// ---------------------------------------------------------------------------
+
+#ifndef INTPTR_MAX
+#error Missing INTPTR_MAX definition
+#endif
+#if INTPTR_MAX == INT64_MAX
+/**
+ * The address width in bits on this platform.
+ */
+#define CX_WORDSIZE 64
+#elif INTPTR_MAX == INT32_MAX
+/**
+ * The address width in bits on this platform.
+ */
+#define CX_WORDSIZE 32
+#else
+#error Unknown pointer size or missing size macros!
+#endif
+
+// ---------------------------------------------------------------------------
+//       Missing Defines
+// ---------------------------------------------------------------------------
+
+#ifndef SSIZE_MAX // not defined in glibc since C23 and MSVC
+#if CX_WORDSIZE == 64
+/**
+ * The maximum representable value in ssize_t.
+ */
+#define SSIZE_MAX 0x7fffffffffffffffll
+#else
+#define SSIZE_MAX 0x7fffffffl
+#endif
+#endif
+
+
+// ---------------------------------------------------------------------------
+//       Attribute definitions
+// ---------------------------------------------------------------------------
+
+#ifndef __GNUC__
+/**
+ * Removes GNU C attributes where they are not supported.
+ */
+#define __attribute__(x)
+#endif
+
+/**
+ * All pointer arguments must be non-NULL.
+ */
+#define cx_attr_nonnull __attribute__((__nonnull__))
+
+/**
+ * The specified pointer arguments must be non-NULL.
+ */
+#define cx_attr_nonnull_arg(...) __attribute__((__nonnull__(__VA_ARGS__)))
+
+/**
+ * The returned value is guaranteed to be non-NULL.
+ */
+#define cx_attr_returns_nonnull __attribute__((__returns_nonnull__))
+
+/**
+ * The attributed function always returns freshly allocated memory.
+ */
+#define cx_attr_malloc __attribute__((__malloc__))
+
+#ifndef __clang__
+/**
+ * The pointer returned by the attributed function is supposed to be freed
+ * by @p freefunc.
+ *
+ * @param freefunc the function that shall be used to free the memory
+ * @param freefunc_arg the index of the pointer argument in @p freefunc
+ */
+#define cx_attr_dealloc(freefunc, freefunc_arg) \
+    __attribute__((__malloc__(freefunc, freefunc_arg)))
+#else
+/**
+ * Not supported in clang.
+ */
+#define cx_attr_dealloc(...)
+#endif // __clang__
+
+/**
+ * Shortcut to specify #cxFree() as deallocator.
+ */
+#define cx_attr_dealloc_ucx cx_attr_dealloc(cxFree, 2)
+
+/**
+ * Specifies the parameters from which the allocation size is calculated.
+ */
+#define cx_attr_allocsize(...) __attribute__((__alloc_size__(__VA_ARGS__)))
+
+
+#ifdef __clang__
+/**
+ * No support for @c null_terminated_string_arg in clang or GCC below 14.
+ */
+#define cx_attr_cstr_arg(idx)
+/**
+ * No support for access attribute in clang.
+ */
+#define cx_attr_access(mode, ...)
+#else
+#if __GNUC__ < 10
+/**
+ * No support for access attribute in GCC < 10.
+ */
+#define cx_attr_access(mode, ...)
+#else
+/**
+ * Helper macro to define access macros.
+ */
+#define cx_attr_access(mode, ...) __attribute__((__access__(mode, __VA_ARGS__)))
+#endif // __GNUC__ < 10
+#if __GNUC__ < 14
+/**
+ * No support for @c null_terminated_string_arg in clang or GCC below 14.
+ */
+#define cx_attr_cstr_arg(idx)
+#else
+/**
+ * The specified argument is expected to be a zero-terminated string.
+ *
+ * @param idx the index of the argument
+ */
+#define cx_attr_cstr_arg(idx) \
+    __attribute__((__null_terminated_string_arg__(idx)))
+#endif // __GNUC__ < 14
+#endif // __clang__
+
+
+/**
+ * Specifies that the function will only read through the given pointer.
+ *
+ * Takes one or two arguments: the index of the pointer and (optionally) the
+ * index of another argument specifying the maximum number of accessed bytes.
+ */
+#define cx_attr_access_r(...) cx_attr_access(__read_only__, __VA_ARGS__)
+
+/**
+ * Specifies that the function will read and write through the given pointer.
+ *
+ * Takes one or two arguments: the index of the pointer and (optionally) the
+ * index of another argument specifying the maximum number of accessed bytes.
+ */
+#define cx_attr_access_rw(...) cx_attr_access(__read_write__, __VA_ARGS__)
+
+/**
+ * Specifies that the function will only write through the given pointer.
+ *
+ * Takes one or two arguments: the index of the pointer and (optionally) the
+ * index of another argument specifying the maximum number of accessed bytes.
+ */
+#define cx_attr_access_w(...) cx_attr_access(__write_only__, __VA_ARGS__)
+
+#if __STDC_VERSION__ >= 202300L
+
+/**
+ * Do not warn about unused variable.
+ */
+#define cx_attr_unused [[maybe_unused]]
+
+/**
+ * Warn about discarded return value.
+ */
+#define cx_attr_nodiscard [[nodiscard]]
+
+#else // no C23
+
+/**
+ * Do not warn about unused variable.
+ */
+#define cx_attr_unused __attribute__((__unused__))
+
+/**
+ * Warn about discarded return value.
+ */
+#define cx_attr_nodiscard __attribute__((__warn_unused_result__))
+
+#endif // __STDC_VERSION__
+
+// ---------------------------------------------------------------------------
+//       Useful function pointers
+// ---------------------------------------------------------------------------
+
 /**
  * Function pointer compatible with fwrite-like functions.
  */
@@ -106,7 +295,6 @@
         size_t,
         void *
 );
-#endif // UCX_TEST_H
 
 /**
  * Function pointer compatible with fread-like functions.
@@ -118,25 +306,71 @@
         void *
 );
 
+// ---------------------------------------------------------------------------
+//       Utility macros
+// ---------------------------------------------------------------------------
 
-// Compiler specific stuff
+/**
+ * Determines the number of members in a static C array.
+ *
+ * @attention never use this to determine the size of a dynamically allocated
+ * array.
+ *
+ * @param arr the array identifier
+ * @return the number of elements
+ */
+#define cx_nmemb(arr) (sizeof(arr)/sizeof((arr)[0]))
 
-#ifndef __GNUC__
+// ---------------------------------------------------------------------------
+//       szmul implementation
+// ---------------------------------------------------------------------------
+
+#if (__GNUC__ >= 5 || defined(__clang__)) && !defined(CX_NO_SZMUL_BUILTIN)
+#define CX_SZMUL_BUILTIN
+#define cx_szmul(a, b, result) __builtin_mul_overflow(a, b, result)
+#else // no GNUC or clang bultin
 /**
- * Removes GNU C attributes where they are not supported.
+ * Performs a multiplication of size_t values and checks for overflow.
+  *
+ * @param a (@c size_t) first operand
+ * @param b (@c size_t) second operand
+ * @param result (@c size_t*) a pointer to a variable, where the result should
+ * be stored
+ * @retval zero success
+ * @retval non-zero the multiplication would overflow
  */
-#define __attribute__(x)
+#define cx_szmul(a, b, result) cx_szmul_impl(a, b, result)
+
+/**
+ * Implementation of cx_szmul() when no compiler builtin is available.
+ *
+ * Do not use in application code.
+ *
+ * @param a first operand
+ * @param b second operand
+ * @param result a pointer to a variable, where the result should
+ * be stored
+ * @retval zero success
+ * @retval non-zero the multiplication would overflow
+ */
+#if __cplusplus
+extern "C"
 #endif
+int cx_szmul_impl(size_t a, size_t b, size_t *result);
+#endif // cx_szmul
+
+
+// ---------------------------------------------------------------------------
+//       Fixes for MSVC incompatibilities
+// ---------------------------------------------------------------------------
 
 #ifdef _MSC_VER
-
 // fix missing ssize_t definition
 #include <BaseTsd.h>
 typedef SSIZE_T ssize_t;
 
 // fix missing _Thread_local support
 #define _Thread_local __declspec(thread)
-
-#endif
+#endif // _MSC_VER
 
 #endif // UCX_COMMON_H