# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1687882234 -7200
# Node ID adc3c48dd3afa831bf30c6d4e7dd4c1ff17c40da
# Parent  b79340dee0b4e33b557f473d7d647014c7d93d49
add allocator example

diff -r b79340dee0b4 -r adc3c48dd3af docs/src/features.md
--- a/docs/src/features.md	Tue Jun 27 17:53:56 2023 +0200
+++ b/docs/src/features.md	Tue Jun 27 18:10:34 2023 +0200
@@ -16,6 +16,43 @@
 
 *Header file:* [allocator.h](api/allocator_8h.html)  
 
+The UCX allocator provides an interface for implementing an own memory allocation mechanism.
+Various function in UCX provide an additional alternative signature that takes an allocator as
+argument. A default allocator implementation using the stdlib memory management functions is
+available via the global symbol `cxDefaultAllocator`.
+
+If you want to define your own allocator, you need to initialize the `CxAllocator` structure
+with a pointer to an allocator class (containing function pointers for the memory management
+functions) and an optional pointer to an arbitrary memory region that can be used to store
+state information for the allocator. An example is shown below:
+
+```c
+struct my_allocator_state {
+    size_t total;
+    size_t avail;
+    char[] mem;
+};
+
+static cx_allocator_class my_allocator_class = {
+        my_malloc_impl,
+        my_realloc_impl,   // all these functions are somewhere defined
+        my_calloc_impl,
+        my_free_impl
+};
+
+CxAllocator create_my_allocator(size_t n) {
+    CxAllocator alloc;
+    alloc.cl = &my_allocator_class;
+    alloc.data = calloc(1, sizeof(struct my_allocator_state) + n);
+    return alloc;
+}
+
+void free_my_allocator(CxAllocator *alloc) {
+    free(alloc.data);
+    free(alloc);
+}
+```
+
 ## String
 
 *Header file:* [string.h](api/string_8h.html)