Tue, 27 Jun 2023 18:10:34 +0200
add allocator example
docs/src/features.md | file | annotate | diff | comparison | revisions |
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)