docs/Writerside/topics/allocator.h.md

# Allocator

<warning>
Outdated - Rewrite!
</warning>

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;
}
```

## Undocumented Symbols (TODO)

### cxCalloc
### cx_default_allocator
### cxDefaultAllocator
### cxFree
### cxMalloc
### cxRealloc
### cxReallocArray
### cx_reallocate_
### cxReallocate_
### cx_reallocatearray_
### cxReallocateArray_