src/ucx/allocator.h@2f5dea574a75
src/ucx/allocator.h
Sat, 28 Oct 2017 15:43:51 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Sat, 28 Oct 2017 15:43:51 +0200
- changeset 259
- 2f5dea574a75
- parent 251
- fae240d633fc
- permissions
- -rw-r--r--
modules documentation
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2017 Mike Becker, 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 * A 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. A 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 */
52 #ifndef UCX_ALLOCATOR_H
53 #define UCX_ALLOCATOR_H
55 #include "ucx.h"
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
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);
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);
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);
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);
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;
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 a 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();
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);
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))
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))
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))
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))
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 }
201 #ifdef __cplusplus
202 }
203 #endif
205 #endif /* UCX_ALLOCATOR_H */
