comparison: docs/Writerside/topics/allocator.h.md
docs/Writerside/topics/allocator.h.md
- branch
- docs/3.1
- changeset 1169
- 6a33a5648027
- parent 1146
- 151c057faf7c
equal
deleted
inserted
replaced
| 1168:d92124c8db73 | 1169:6a33a5648027 |
|---|---|
| 1 # Allocator | 1 # Allocator |
| 2 | 2 |
| 3 <warning> | 3 The allocator interface provides a mechanism to implement own custom allocators |
| 4 Outdated - Rewrite! | 4 that can also be used in many other function in UCX. |
| 5 </warning> | |
| 6 | 5 |
| 7 The UCX allocator provides an interface for implementing an own memory allocation mechanism. | 6 A default allocator implementation using the stdlib functions is |
| 8 Various function in UCX provide an additional alternative signature that takes an allocator as | 7 available via the global symbol `cxDefaultAllocator` |
| 9 argument. A default allocator implementation using the stdlib memory management functions is | 8 and UCX also provides a [memory pool](mempool.h.md) implementation. |
| 10 available via the global symbol `cxDefaultAllocator`. | 9 You are free to add additional own custom implementations. |
| 10 A general sketch that illustrates how to do this can be found [below](#custom-allocator). | |
| 11 | |
| 12 ## Overview | |
| 13 | |
| 14 ```C | |
| 15 void *cxMalloc(const CxAllocator *allocator, size_t n); | |
| 16 | |
| 17 void *cxCalloc(const CxAllocator *allocator, | |
| 18 size_t nmemb, size_t size); | |
| 19 | |
| 20 void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n); | |
| 21 | |
| 22 void *cxReallocArray(const CxAllocator *allocator, void *mem, | |
| 23 size_t nmemb, size_t size); | |
| 24 | |
| 25 int cxReallocate(const CxAllocator *allocator, void **mem, size_t n); | |
| 26 | |
| 27 int cxReallocateArray(const CxAllocator *allocator, void **mem, | |
| 28 size_t nmemb, size_t size); | |
| 29 | |
| 30 void cxFree(const CxAllocator *allocator, void *mem); | |
| 31 | |
| 32 int cx_reallocate(void **mem, size_t size); | |
| 33 | |
| 34 int cx_reallocatearray(void **mem, size_t nmemb, size_t size); | |
| 35 | |
| 36 // predefined allocator that uses stdlib functions | |
| 37 CxAllocator *cxDefaultAllocator; | |
| 38 ``` | |
| 39 | |
| 40 > All UCX functions that are not _explicitly_ designed for taking an allocator argument | |
| 41 > (recognizable by a `_a` suffix in the function's name) do support a `NULL` argument | |
| 42 > in which case the `cxDefaultAllocator` will be used. | |
| 43 | |
| 44 ## Description | |
| 45 | |
| 46 The functions `cxMalloc()`, `cxCalloc()`, `cxRealloc()`, `cxReallocArray()`, and `cxFree()` | |
| 47 invoke the memory management functions specified in the `allocator` and should behave like | |
| 48 their respective stdlibc pendants. | |
| 49 Implementations of the allocator interface are strongly encouraged to guarantee this behavior, | |
| 50 most prominently that invocations of `cxFree()` with a `NULL`-pointer for `mem` are ignored | |
| 51 instead of causing segfault error. | |
| 52 | |
| 53 Additionally, UCX provides the functions `cxReallocate()` and `cxReallocateArray()`, as well as | |
| 54 their independent pendants `cx_reallocate()` and `cx_reallocatearray()`. | |
| 55 All those functions solve the problem that a possible reallocation might fail, | |
| 56 leading to a quite common programming mistake: | |
| 57 | |
| 58 ```C | |
| 59 // common mistake - mem will be lost hen realloc() returns NULL | |
| 60 mem = realloc(mem, capacity + 32); | |
| 61 if (mem == NULL) // ... do error handling | |
| 62 ``` | |
| 63 | |
| 64 The above code can be replaced with `cx_reallocate()` which keeps the pointer intact and returns an error code instead. | |
| 65 | |
| 66 ```C | |
| 67 // when cx_reallocate() fails, mem will still point to the old memory | |
| 68 if (cx_reallocate(&mem, capacity + 32)) // ... do error handling | |
| 69 ``` | |
| 70 | |
| 71 > Please pay special attention to always use `cxFree()` and the `cxRealloc()`-family of functions | |
| 72 > with the **same** allocator that was used to allocate the memory. | |
| 73 {style="warning"} | |
| 74 | |
| 75 ## Custom Allocator | |
| 11 | 76 |
| 12 If you want to define your own allocator, you need to initialize the `CxAllocator` structure | 77 If you want to define your own allocator, you need to initialize the `CxAllocator` structure |
| 13 with a pointer to an allocator class (containing function pointers for the memory management | 78 with a pointer to an allocator class (containing function pointers for the memory management |
| 14 functions) and an optional pointer to an arbitrary memory region that can be used to store | 79 functions) and an optional pointer to custom data. An example is shown below: |
| 15 state information for the allocator. An example is shown below: | |
| 16 | 80 |
| 17 ```c | 81 ```c |
| 82 | |
| 18 struct my_allocator_state { | 83 struct my_allocator_state { |
| 19 size_t total; | 84 // ... some internal state ... |
| 20 size_t avail; | |
| 21 char mem[]; | |
| 22 }; | 85 }; |
| 23 | 86 |
| 24 static cx_allocator_class my_allocator_class = { | 87 static cx_allocator_class my_allocator_class = { |
| 25 my_malloc_impl, | 88 my_malloc_impl, |
| 26 my_realloc_impl, // all these functions are somewhere defined | 89 my_realloc_impl, // all these functions are somewhere defined |
| 27 my_calloc_impl, | 90 my_calloc_impl, |
| 28 my_free_impl | 91 my_free_impl |
| 29 }; | 92 }; |
| 30 | 93 |
| 31 CxAllocator create_my_allocator(size_t n) { | 94 CxAllocator create_my_allocator(void) { |
| 32 CxAllocator alloc; | 95 CxAllocator alloc; |
| 33 alloc.cl = &my_allocator_class; | 96 alloc.cl = &my_allocator_class; |
| 34 alloc.data = calloc(1, sizeof(struct my_allocator_state) + n); | 97 struct my_allocator_state *state = malloc(sizeof(*state)); |
| 98 // ... initialize state ... | |
| 99 alloc.data = state; | |
| 35 return alloc; | 100 return alloc; |
| 101 } | |
| 102 | |
| 103 void destroy_my_allocator(CxAllocator *al) { | |
| 104 struct my_allocator_state *state = al->state; | |
| 105 // ... destroy state -- | |
| 106 free(state); | |
| 36 } | 107 } |
| 37 ``` | 108 ``` |
| 38 | 109 |
| 39 ## Undocumented Symbols (TODO) | 110 <seealso> |
| 40 | 111 <category ref="apidoc"> |
| 41 ### cxCalloc | 112 <a href="https://ucx.sourceforge.io/api/allocator_8h.html">allocator.h</a> |
| 42 ### cx_default_allocator | 113 </category> |
| 43 ### cxDefaultAllocator | 114 </seealso> |
| 44 ### cxFree | |
| 45 ### cxMalloc | |
| 46 ### cxRealloc | |
| 47 ### cxReallocArray | |
| 48 ### cx_reallocate_ | |
| 49 ### cxReallocate_ | |
| 50 ### cx_reallocatearray_ | |
| 51 ### cxReallocateArray_ |
