23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
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 |
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
26 * POSSIBILITY OF SUCH DAMAGE. |
26 * POSSIBILITY OF SUCH DAMAGE. |
27 */ |
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 */ |
28 |
51 |
29 #ifndef ALLOCATOR_H |
52 #ifndef UCX_ALLOCATOR_H |
30 #define ALLOCATOR_H |
53 #define UCX_ALLOCATOR_H |
31 |
54 |
32 #include "ucx.h" |
55 #include "ucx.h" |
33 |
56 |
34 #ifdef __cplusplus |
57 #ifdef __cplusplus |
35 extern "C" { |
58 extern "C" { |
36 #endif |
59 #endif |
37 |
60 |
|
61 /** |
|
62 * A function pointer to the allocators <code>malloc()</code> function. |
|
63 * @see UcxAllocator |
|
64 */ |
38 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n); |
65 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n); |
|
66 /** |
|
67 * A function pointer to the allocators <code>calloc()</code> function. |
|
68 * @see UcxAllocator |
|
69 */ |
39 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size); |
70 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size); |
|
71 /** |
|
72 * A function pointer to the allocators <code>realloc()</code> function. |
|
73 * @see UcxAllocator |
|
74 */ |
40 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n); |
75 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n); |
|
76 /** |
|
77 * A function pointer to the allocators <code>free()</code> function. |
|
78 * @see UcxAllocator |
|
79 */ |
41 typedef void(*ucx_allocator_free)(void *pool, void *data); |
80 typedef void(*ucx_allocator_free)(void *pool, void *data); |
42 |
81 |
|
82 /** |
|
83 * UCX allocator data structure containing memory management functions. |
|
84 */ |
43 typedef struct { |
85 typedef struct { |
|
86 /** Pointer to an area of memory or a complex memory pool. |
|
87 * This pointer will be passed to any memory management function as first |
|
88 * argument. |
|
89 */ |
44 void *pool; |
90 void *pool; |
|
91 /** |
|
92 * The <code>malloc()</code> function for this allocator. |
|
93 */ |
45 ucx_allocator_malloc malloc; |
94 ucx_allocator_malloc malloc; |
|
95 /** |
|
96 * The <code>calloc()</code> function for this allocator. |
|
97 */ |
46 ucx_allocator_calloc calloc; |
98 ucx_allocator_calloc calloc; |
|
99 /** |
|
100 * The <code>realloc()</code> function for this allocator. |
|
101 */ |
47 ucx_allocator_realloc realloc; |
102 ucx_allocator_realloc realloc; |
|
103 /** |
|
104 * The <code>free()</code> function for this allocator. |
|
105 */ |
48 ucx_allocator_free free; |
106 ucx_allocator_free free; |
49 } UcxAllocator; |
107 } UcxAllocator; |
50 |
108 |
|
109 /** |
|
110 * Returns a pointer to the default allocator. |
|
111 * |
|
112 * The default allocator contains wrappers to the standard libc memory |
|
113 * management functions. Use this function to get a pointer to a globally |
|
114 * available allocator. You may also define an own UcxAllocator by assigning |
|
115 * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable |
|
116 * to any function that takes an UcxAllocator as argument. Note that using |
|
117 * this function is the recommended way of passing a default allocator, thus |
|
118 * it never runs out of scope. |
|
119 * |
|
120 * @return a pointer to the default allocator |
|
121 * |
|
122 * @see UCX_ALLOCATOR_DEFAULT |
|
123 */ |
51 UcxAllocator *ucx_default_allocator(); |
124 UcxAllocator *ucx_default_allocator(); |
52 |
125 |
|
126 /** |
|
127 * A wrapper for the standard libc <code>malloc()</code> function. |
|
128 * @param ignore ignored (may be used by allocators for pooled memory) |
|
129 * @param n argument passed to <code>malloc()</code> |
|
130 * @return return value of <code>malloc()</code> |
|
131 */ |
53 void *ucx_default_malloc(void *ignore, size_t n); |
132 void *ucx_default_malloc(void *ignore, size_t n); |
|
133 /** |
|
134 * A wrapper for the standard libc <code>calloc()</code> function. |
|
135 * @param ignore ignored (may be used by allocators for pooled memory) |
|
136 * @param n argument passed to <code>calloc()</code> |
|
137 * @param size argument passed to <code>calloc()</code> |
|
138 * @return return value of <code>calloc()</code> |
|
139 */ |
54 void *ucx_default_calloc(void *ignore, size_t n, size_t size); |
140 void *ucx_default_calloc(void *ignore, size_t n, size_t size); |
|
141 /** |
|
142 * A wrapper for the standard libc <code>realloc()</code> function. |
|
143 * @param ignore ignored (may be used by allocators for pooled memory) |
|
144 * @param data argumend passed to <code>realloc()</code> |
|
145 * @param n argument passed to <code>realloc()</code> |
|
146 * @return return value of <code>realloc()</code> |
|
147 */ |
55 void *ucx_default_realloc(void *ignore, void *data, size_t n); |
148 void *ucx_default_realloc(void *ignore, void *data, size_t n); |
|
149 /** |
|
150 * A wrapper for the standard libc <code>free()</code> function. |
|
151 * @param ignore ignored (may be used by allocators for pooled memory) |
|
152 * @param data argument passed to <code>free()</code> |
|
153 * @return return value of <code>free()</code> |
|
154 */ |
56 void ucx_default_free(void *ignore, void *data); |
155 void ucx_default_free(void *ignore, void *data); |
57 |
156 |
|
157 /** |
|
158 * Convenient macro for a default allocator <code>struct</code> definition. |
|
159 */ |
58 #define UCX_ALLOCATOR_DEFAULT {NULL, \ |
160 #define UCX_ALLOCATOR_DEFAULT {NULL, \ |
59 ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \ |
161 ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \ |
60 ucx_default_free } |
162 ucx_default_free } |
61 |
163 |
62 #ifdef __cplusplus |
164 #ifdef __cplusplus |
63 } |
165 } |
64 #endif |
166 #endif |
65 |
167 |
66 #endif /* ALLOCATOR_H */ |
168 #endif /* UCX_ALLOCATOR_H */ |
67 |
169 |