1 /* |
|
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
|
3 * |
|
4 * Copyright 2015 Olaf Wintermann. All rights reserved. |
|
5 * |
|
6 * Redistribution and use in source and binary forms, with or without |
|
7 * modification, are permitted provided that the following conditions are met: |
|
8 * |
|
9 * 1. Redistributions of source code must retain the above copyright |
|
10 * notice, this list of conditions and the following disclaimer. |
|
11 * |
|
12 * 2. Redistributions in binary form must reproduce the above copyright |
|
13 * notice, this list of conditions and the following disclaimer in the |
|
14 * documentation and/or other materials provided with the distribution. |
|
15 * |
|
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
|
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
|
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
|
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
|
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
|
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
|
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
|
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
|
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
|
26 * POSSIBILITY OF SUCH DAMAGE. |
|
27 */ |
|
28 /** |
|
29 * Allocator for custom memory management. |
|
30 * |
|
31 * An UCX allocator consists of a pointer to the memory area / pool and four |
|
32 * function pointers to memory management functions operating on this memory |
|
33 * area / pool. These functions shall behave equivalent to the standard libc |
|
34 * functions <code>malloc(), calloc(), realloc()</code> and <code>free()</code>. |
|
35 * |
|
36 * The signature of the memory management functions is based on the signature |
|
37 * of the respective libc function but each of them takes the pointer to the |
|
38 * memory area / pool as first argument. |
|
39 * |
|
40 * As the pointer to the memory area / pool can be arbitrarily chosen, any data |
|
41 * can be provided to the memory management functions. An UcxMempool is just |
|
42 * one example. |
|
43 * |
|
44 * @see mempool.h |
|
45 * @see UcxMap |
|
46 * |
|
47 * @file allocator.h |
|
48 * @author Mike Becker |
|
49 * @author Olaf Wintermann |
|
50 */ |
|
51 |
|
52 #ifndef UCX_ALLOCATOR_H |
|
53 #define UCX_ALLOCATOR_H |
|
54 |
|
55 #include "ucx.h" |
|
56 |
|
57 #ifdef __cplusplus |
|
58 extern "C" { |
|
59 #endif |
|
60 |
|
61 /** |
|
62 * A function pointer to the allocators <code>malloc()</code> function. |
|
63 * @see UcxAllocator |
|
64 */ |
|
65 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n); |
|
66 |
|
67 /** |
|
68 * A function pointer to the allocators <code>calloc()</code> function. |
|
69 * @see UcxAllocator |
|
70 */ |
|
71 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size); |
|
72 |
|
73 /** |
|
74 * A function pointer to the allocators <code>realloc()</code> function. |
|
75 * @see UcxAllocator |
|
76 */ |
|
77 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n); |
|
78 |
|
79 /** |
|
80 * A function pointer to the allocators <code>free()</code> function. |
|
81 * @see UcxAllocator |
|
82 */ |
|
83 typedef void(*ucx_allocator_free)(void *pool, void *data); |
|
84 |
|
85 /** |
|
86 * UCX allocator data structure containing memory management functions. |
|
87 */ |
|
88 typedef struct { |
|
89 /** Pointer to an area of memory or a complex memory pool. |
|
90 * This pointer will be passed to any memory management function as first |
|
91 * argument. |
|
92 */ |
|
93 void *pool; |
|
94 /** |
|
95 * The <code>malloc()</code> function for this allocator. |
|
96 */ |
|
97 ucx_allocator_malloc malloc; |
|
98 /** |
|
99 * The <code>calloc()</code> function for this allocator. |
|
100 */ |
|
101 ucx_allocator_calloc calloc; |
|
102 /** |
|
103 * The <code>realloc()</code> function for this allocator. |
|
104 */ |
|
105 ucx_allocator_realloc realloc; |
|
106 /** |
|
107 * The <code>free()</code> function for this allocator. |
|
108 */ |
|
109 ucx_allocator_free free; |
|
110 } UcxAllocator; |
|
111 |
|
112 /** |
|
113 * Returns a pointer to the default allocator. |
|
114 * |
|
115 * The default allocator contains wrappers to the standard libc memory |
|
116 * management functions. Use this function to get a pointer to a globally |
|
117 * available allocator. You may also define an own UcxAllocator by assigning |
|
118 * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable |
|
119 * to any function that takes an UcxAllocator as argument. Note that using |
|
120 * this function is the recommended way of passing a default allocator, thus |
|
121 * it never runs out of scope. |
|
122 * |
|
123 * @return a pointer to the default allocator |
|
124 * |
|
125 * @see UCX_ALLOCATOR_DEFAULT |
|
126 */ |
|
127 UcxAllocator *ucx_default_allocator(); |
|
128 |
|
129 /** |
|
130 * A wrapper for the standard libc <code>malloc()</code> function. |
|
131 * @param ignore ignored (may be used by allocators for pooled memory) |
|
132 * @param n argument passed to <code>malloc()</code> |
|
133 * @return return value of <code>malloc()</code> |
|
134 */ |
|
135 void *ucx_default_malloc(void *ignore, size_t n); |
|
136 /** |
|
137 * A wrapper for the standard libc <code>calloc()</code> function. |
|
138 * @param ignore ignored (may be used by allocators for pooled memory) |
|
139 * @param n argument passed to <code>calloc()</code> |
|
140 * @param size argument passed to <code>calloc()</code> |
|
141 * @return return value of <code>calloc()</code> |
|
142 */ |
|
143 void *ucx_default_calloc(void *ignore, size_t n, size_t size); |
|
144 /** |
|
145 * A wrapper for the standard libc <code>realloc()</code> function. |
|
146 * @param ignore ignored (may be used by allocators for pooled memory) |
|
147 * @param data argumend passed to <code>realloc()</code> |
|
148 * @param n argument passed to <code>realloc()</code> |
|
149 * @return return value of <code>realloc()</code> |
|
150 */ |
|
151 void *ucx_default_realloc(void *ignore, void *data, size_t n); |
|
152 /** |
|
153 * A wrapper for the standard libc <code>free()</code> function. |
|
154 * @param ignore ignored (may be used by allocators for pooled memory) |
|
155 * @param data argument passed to <code>free()</code> |
|
156 */ |
|
157 void ucx_default_free(void *ignore, void *data); |
|
158 |
|
159 /** |
|
160 * Shorthand for calling an allocators malloc function. |
|
161 * @param allocator the allocator to use |
|
162 * @param n size of space to allocate |
|
163 * @return a pointer to the allocated memory area |
|
164 */ |
|
165 #define almalloc(allocator, n) ((allocator)->malloc((allocator)->pool, n)) |
|
166 |
|
167 /** |
|
168 * Shorthand for calling an allocators calloc function. |
|
169 * @param allocator the allocator to use |
|
170 * @param n the count of elements the space should be allocated for |
|
171 * @param size the size of each element |
|
172 * @return a pointer to the allocated memory area |
|
173 */ |
|
174 #define alcalloc(allocator, n, size) \ |
|
175 ((allocator)->calloc((allocator)->pool, n, size)) |
|
176 |
|
177 /** |
|
178 * Shorthand for calling an allocators realloc function. |
|
179 * @param allocator the allocator to use |
|
180 * @param ptr the pointer to the memory area that shall be reallocated |
|
181 * @param n the new size of the allocated memory area |
|
182 * @return a pointer to the reallocated memory area |
|
183 */ |
|
184 #define alrealloc(allocator, ptr, n) \ |
|
185 ((allocator)->realloc((allocator)->pool, ptr, n)) |
|
186 |
|
187 /** |
|
188 * Shorthand for calling an allocators free function. |
|
189 * @param allocator the allocator to use |
|
190 * @param ptr the pointer to the memory area that shall be freed |
|
191 */ |
|
192 #define alfree(allocator, ptr) ((allocator)->free((allocator)->pool, ptr)) |
|
193 |
|
194 /** |
|
195 * Convenient macro for a default allocator <code>struct</code> definition. |
|
196 */ |
|
197 #define UCX_ALLOCATOR_DEFAULT {NULL, \ |
|
198 ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \ |
|
199 ucx_default_free } |
|
200 |
|
201 #ifdef __cplusplus |
|
202 } |
|
203 #endif |
|
204 |
|
205 #endif /* UCX_ALLOCATOR_H */ |
|
206 |
|