Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Tue Jun 27 17:53:56 2023 +0200
     1.2 +++ b/docs/src/features.md	Tue Jun 27 18:10:34 2023 +0200
     1.3 @@ -16,6 +16,43 @@
     1.4  
     1.5  *Header file:* [allocator.h](api/allocator_8h.html)  
     1.6  
     1.7 +The UCX allocator provides an interface for implementing an own memory allocation mechanism.
     1.8 +Various function in UCX provide an additional alternative signature that takes an allocator as
     1.9 +argument. A default allocator implementation using the stdlib memory management functions is
    1.10 +available via the global symbol `cxDefaultAllocator`.
    1.11 +
    1.12 +If you want to define your own allocator, you need to initialize the `CxAllocator` structure
    1.13 +with a pointer to an allocator class (containing function pointers for the memory management
    1.14 +functions) and an optional pointer to an arbitrary memory region that can be used to store
    1.15 +state information for the allocator. An example is shown below:
    1.16 +
    1.17 +```c
    1.18 +struct my_allocator_state {
    1.19 +    size_t total;
    1.20 +    size_t avail;
    1.21 +    char[] mem;
    1.22 +};
    1.23 +
    1.24 +static cx_allocator_class my_allocator_class = {
    1.25 +        my_malloc_impl,
    1.26 +        my_realloc_impl,   // all these functions are somewhere defined
    1.27 +        my_calloc_impl,
    1.28 +        my_free_impl
    1.29 +};
    1.30 +
    1.31 +CxAllocator create_my_allocator(size_t n) {
    1.32 +    CxAllocator alloc;
    1.33 +    alloc.cl = &my_allocator_class;
    1.34 +    alloc.data = calloc(1, sizeof(struct my_allocator_state) + n);
    1.35 +    return alloc;
    1.36 +}
    1.37 +
    1.38 +void free_my_allocator(CxAllocator *alloc) {
    1.39 +    free(alloc.data);
    1.40 +    free(alloc);
    1.41 +}
    1.42 +```
    1.43 +
    1.44  ## String
    1.45  
    1.46  *Header file:* [string.h](api/string_8h.html)