Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/allocator.h.md

docs/Writerside/topics/allocator.h.md

changeset 1188
b0300de92b72
parent 1174
ee473780cc0d
equal deleted inserted replaced
1187:0f70bb04f7ba 1188:b0300de92b72
1 # Allocator
2
3 The allocator interface provides a mechanism to implement own custom allocators
4 that can also be used in many other function in UCX.
5
6 A default allocator implementation using the stdlib functions is
7 available via the global symbol `cxDefaultAllocator`
8 and UCX also provides a [memory pool](mempool.h.md) implementation.
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 #include <cx/allocator.h>
16
17 void *cxMalloc(const CxAllocator *allocator, size_t n);
18
19 void *cxCalloc(const CxAllocator *allocator,
20 size_t nmemb, size_t size);
21
22 void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
23
24 void *cxReallocArray(const CxAllocator *allocator, void *mem,
25 size_t nmemb, size_t size);
26
27 int cxReallocate(const CxAllocator *allocator, void **mem, size_t n);
28
29 int cxReallocateArray(const CxAllocator *allocator, void **mem,
30 size_t nmemb, size_t size);
31
32 void cxFree(const CxAllocator *allocator, void *mem);
33
34 int cx_reallocate(void **mem, size_t size);
35
36 int cx_reallocatearray(void **mem, size_t nmemb, size_t size);
37
38 // predefined allocator that uses stdlib functions
39 CxAllocator *cxDefaultAllocator;
40 ```
41
42 > All UCX functions that are not _explicitly_ designed for taking an allocator argument
43 > (recognizable by a `_a` suffix in the function's name) do support a `NULL` argument
44 > in which case the `cxDefaultAllocator` will be used.
45
46 ## Description
47
48 The functions `cxMalloc()`, `cxCalloc()`, `cxRealloc()`, `cxReallocArray()`, and `cxFree()`
49 invoke the memory management functions specified in the `allocator` and should behave like
50 their respective stdlibc pendants.
51 Implementations of the allocator interface are strongly encouraged to guarantee this behavior,
52 most prominently that invocations of `cxFree()` with a `NULL`-pointer for `mem` are ignored
53 instead of causing segfault error.
54
55 Additionally, UCX provides the functions `cxReallocate()` and `cxReallocateArray()`, as well as
56 their independent pendants `cx_reallocate()` and `cx_reallocatearray()`.
57 All those functions solve the problem that a possible reallocation might fail,
58 leading to a quite common programming mistake:
59
60 ```C
61 // common mistake - mem will be lost hen realloc() returns NULL
62 mem = realloc(mem, capacity + 32);
63 if (mem == NULL) // ... do error handling
64 ```
65
66 The above code can be replaced with `cx_reallocate()` which keeps the pointer intact and returns an error code instead.
67
68 ```C
69 // when cx_reallocate() fails, mem will still point to the old memory
70 if (cx_reallocate(&mem, capacity + 32)) // ... do error handling
71 ```
72
73 > Please pay special attention to always use `cxFree()` and the `cxRealloc()`-family of functions
74 > with the **same** allocator that was used to allocate the memory.
75 {style="warning"}
76
77 ## Custom Allocator
78
79 If you want to define your own allocator, you need to initialize the `CxAllocator` structure
80 with a pointer to an allocator class (containing function pointers for the memory management
81 functions) and an optional pointer to custom data. An example is shown below:
82
83 ```c
84
85 struct my_allocator_state {
86 // ... some internal state ...
87 };
88
89 static cx_allocator_class my_allocator_class = {
90 my_malloc_impl,
91 my_realloc_impl, // all these functions are somewhere defined
92 my_calloc_impl,
93 my_free_impl
94 };
95
96 CxAllocator create_my_allocator(void) {
97 CxAllocator alloc;
98 alloc.cl = &my_allocator_class;
99 struct my_allocator_state *state = malloc(sizeof(*state));
100 // ... initialize state ...
101 alloc.data = state;
102 return alloc;
103 }
104
105 void destroy_my_allocator(CxAllocator *al) {
106 struct my_allocator_state *state = al->state;
107 // ... destroy state --
108 free(state);
109 }
110 ```
111
112 When you are implementing
113
114 ## Destructor Functions
115
116 The `allocator.h` header also declares two function pointers for destructor functions.
117
118 ```C
119 typedef void (*cx_destructor_func)(void *memory);
120 typedef void (*cx_destructor_func2)(void *data, void *memory);
121 ```
122
123 The first one is called _simple_ destructor (e.g. in the context of [collections](collection.h.md)),
124 and the second one is called _advanced_ destructor.
125 The only difference is that you can pass additional custom `data` to an advanced destructor function.
126
127 Destructor functions play a vital role in deep de-allocations.
128 Another scenarios, besides destroying elements in a collection, are the de-allocation of objects
129 stored in a [memory pool](mempool.h.md) or de-allocations of deeply nested [JSON](json.h.md) objects.
130
131 > Destructor functions are not to be confused with `free()`-like functions.
132 > The fundamental differences are that
133 > * it is not safe to pass `NULL` to a destructor function
134 > * a destructor may only de-allocate the contents inside an object but not the object itself, depending on context
135 >
136 {style="note"}
137
138 > For example, when you are using a [list](list.h.md) that stores elements directly, a destructor function
139 > assigned to that collection may only destroy the element's contents but must not deallocate the element's memory.
140 > On the other hand, when the list is storing just pointers to the elements, you _may_ want the destructor
141 > function to also de-allocate the element's memory when the element is removed from that list.
142
143 <seealso>
144 <category ref="apidoc">
145 <a href="https://ucx.sourceforge.io/api/allocator_8h.html">allocator.h</a>
146 </category>
147 </seealso>

Mercurial Repository: ucx

mercurial