Mercurial > hg > ucx / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/allocator.h.md	Thu Jan 23 01:33:36 2025 +0100
@@ -0,0 +1,34 @@
+# allocator.h
+
+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;
+}
+```
+