Mercurial > hg > ucx / file comparison

comparison: src/cx/allocator.h

src/cx/allocator.h

changeset 429
3d8235c96a27
parent 419
b5d6cb88d05d
child 434
38ee262e8b94
equal deleted inserted replaced
428:da66264af8ad 429:3d8235c96a27
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 * \file allocator.h
30 * Interface for custom allocators.
31 */
28 32
29 #ifndef UCX_ALLOCATOR_H 33 #ifndef UCX_ALLOCATOR_H
30 #define UCX_ALLOCATOR_H 34 #define UCX_ALLOCATOR_H
31 35
32 #include <stdlib.h> 36 #include <stdlib.h>
33 37
34 #ifdef __cplusplus 38 #ifdef __cplusplus
35 extern "C" { 39 extern "C" {
36 #endif 40 #endif
37 41
42 /**
43 * The class definition for an allocator.
44 */
38 typedef struct { 45 typedef struct {
46 /**
47 * Allocate \p n bytes of memory.
48 *
49 * @param data the allocator's data
50 * @param n the number of bytes
51 * @return a pointer to the allocated memory
52 */
39 void *(*malloc)(void *data, size_t n); 53 void *(*malloc)(void *data, size_t n);
54
55 /**
56 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
57 * This function may return the same pointer that was passed to it, if moving the memory
58 * was not necessary.
59 *
60 * \note Re-allocating a block allocated by a different allocator is undefined.
61 *
62 * @param data the allocator's data
63 * @param mem pointer to the previously allocated block
64 * @param n the new size in bytes
65 * @return a pointer to the re-allocated memory
66 */
40 void *(*realloc)(void *data, void *mem, size_t n); 67 void *(*realloc)(void *data, void *mem, size_t n);
68
69 /**
70 * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
71 *
72 * @param data the allocator's data
73 * @param nelem the number of elements
74 * @param n the size of each element in bytes
75 * @return a pointer to the allocated memory
76 */
41 void *(*calloc)(void *data, size_t nelem, size_t n); 77 void *(*calloc)(void *data, size_t nelem, size_t n);
42 void(*free)(void *data, void *mem); 78
79 /**
80 * Free a block allocated by this allocator.
81 *
82 * \note Freeing a block of a different allocator is undefined.
83 *
84 * @param data the allocator's data
85 * @param mem a pointer to the block to free
86 */
87 void (*free)(void *data, void *mem);
43 } cx_allocator_class; 88 } cx_allocator_class;
44 89
90 /**
91 * Structure holding the data for an allocator.
92 */
45 struct cx_allocator_s { 93 struct cx_allocator_s {
94 /**
95 * A pointer to the instance of the allocator class.
96 */
46 cx_allocator_class *cl; 97 cx_allocator_class *cl;
98 /**
99 * A pointer to the data this allocator uses.
100 */
47 void *data; 101 void *data;
48 }; 102 };
103
104 /**
105 * High-Level type alias for the allocator type.
106 */
49 typedef struct cx_allocator_s *CxAllocator; 107 typedef struct cx_allocator_s *CxAllocator;
50 108
109 /**
110 * A default allocator using standard library malloc() etc.
111 */
51 extern CxAllocator cxDefaultAllocator; 112 extern CxAllocator cxDefaultAllocator;
52 113
114 /**
115 * Allocate \p n bytes of memory.
116 *
117 * @param allocator the allocator
118 * @param n the number of bytes
119 * @return a pointer to the allocated memory
120 */
53 void *cxMalloc(CxAllocator allocator, size_t n); 121 void *cxMalloc(CxAllocator allocator, size_t n);
54 122
123 /**
124 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
125 * This function may return the same pointer that was passed to it, if moving the memory
126 * was not necessary.
127 *
128 * \note Re-allocating a block allocated by a different allocator is undefined.
129 *
130 * @param allocator the allocator
131 * @param mem pointer to the previously allocated block
132 * @param n the new size in bytes
133 * @return a pointer to the re-allocated memory
134 */
55 void *cxRealloc(CxAllocator allocator, void *mem, size_t n); 135 void *cxRealloc(CxAllocator allocator, void *mem, size_t n);
56 136
137 /**
138 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
139 * This function acts like cxRealloc() using the pointer pointed to by \p mem.
140 * On success, the pointer is changed to the new location (in case the
141 *
142 * \note Re-allocating a block allocated by a different allocator is undefined.
143 *
144 * \par Error handling
145 * \c errno will be set, if the underlying realloc function does so.
146 *
147 * @param allocator the allocator
148 * @param mem pointer to the pointer to allocated block
149 * @param n the new size in bytes
150 * @return zero on success, non-zero on failure
151 */
57 int cxReallocate(CxAllocator allocator, void **mem, size_t n); 152 int cxReallocate(CxAllocator allocator, void **mem, size_t n);
58 153
154 /**
155 * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
156 *
157 * @param allocator the allocator
158 * @param nelem the number of elements
159 * @param n the size of each element in bytes
160 * @return a pointer to the allocated memory
161 */
59 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n); 162 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n);
60 163
164 /**
165 * Free a block allocated by this allocator.
166 *
167 * \note Freeing a block of a different allocator is undefined.
168 *
169 * @param allocator the allocator
170 * @param mem a pointer to the block to free
171 */
61 void cxFree(CxAllocator allocator, void *mem); 172 void cxFree(CxAllocator allocator, void *mem);
62 173
63 #ifdef __cplusplus 174 #ifdef __cplusplus
64 } /* extern "C" */ 175 } /* extern "C" */
65 #endif 176 #endif

Mercurial Repository: ucx

mercurial