1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 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 * \file allocator.h
30 * Interface for custom allocators.
31 */
32
33 #ifndef UCX_ALLOCATOR_H
34 #define UCX_ALLOCATOR_H
35
36 #include "common.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /**
43 * The class definition for an allocator.
44 */
45 typedef struct {
46 /**
47 * The allocator's malloc() implementation.
48 */
49 void *(*malloc)(
50 void *data,
51 size_t n
52 );
53
54 /**
55 * The allocator's realloc() implementation.
56 */
57 __attribute__((__warn_unused_result__))
58 void *(*realloc)(
59 void *data,
60 void *mem,
61 size_t n
62 );
63
64 /**
65 * The allocator's calloc() implementation.
66 */
67 void *(*calloc)(
68 void *data,
69 size_t nelem,
70 size_t n
71 );
72
73 /**
74 * The allocator's free() implementation.
75 */
76 __attribute__((__nonnull__))
77 void (*free)(
78 void *data,
79 void *mem
80 );
81 } cx_allocator_class;
82
83 /**
84 * Structure holding the data for an allocator.
85 */
86 struct cx_allocator_s {
87 /**
88 * A pointer to the instance of the allocator class.
89 */
90 cx_allocator_class *cl;
91 /**
92 * A pointer to the data this allocator uses.
93 */
94 void *data;
95 };
96
97 /**
98 * High-Level type alias for the allocator type.
99 */
100 typedef struct cx_allocator_s CxAllocator;
101
102 /**
103 * A default allocator using standard library malloc() etc.
104 */
105 extern CxAllocator *cxDefaultAllocator;
106
107 /**
108 * Function pointer type for destructor functions.
109 *
110 * A destructor function deallocates possible contents and MAY free the memory
111 * pointed to by \p memory. Read the documentation of the respective function
112 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
113 * particular implementation.
114 *
115 * @param memory a pointer to the object to destruct
116 */
117 __attribute__((__nonnull__))
118 typedef void (*cx_destructor_func)(void *memory);
119
120 /**
121 * Function pointer type for destructor functions.
122 *
123 * A destructor function deallocates possible contents and MAY free the memory
124 * pointed to by \p memory. Read the documentation of the respective function
125 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
126 * particular implementation.
127 *
128 * @param data an optional pointer to custom data
129 * @param memory a pointer to the object to destruct
130 */
131 __attribute__((__nonnull__(2)))
132 typedef void (*cx_destructor_func2)(
133 void *data,
134 void *memory
135 );
136
137 /**
138 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
139 *
140 * \par Error handling
141 * \c errno will be set by realloc() on failure.
142 *
143 * @param mem pointer to the pointer to allocated block
144 * @param n the new size in bytes
145 * @return zero on success, non-zero on failure
146 */
147 __attribute__((__nonnull__))
148 int cx_reallocate(
149 void **mem,
150 size_t n
151 );
152
153 /**
154 * Allocate \p n bytes of memory.
155 *
156 * @param allocator the allocator
157 * @param n the number of bytes
158 * @return a pointer to the allocated memory
159 */
160 __attribute__((__malloc__))
161 __attribute__((__alloc_size__(2)))
162 void *cxMalloc(
163 const CxAllocator *allocator,
164 size_t n
165 );
166
167 /**
168 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
169 * This function may return the same pointer that was passed to it, if moving the memory
170 * was not necessary.
171 *
172 * \note Re-allocating a block allocated by a different allocator is undefined.
173 *
174 * @param allocator the allocator
175 * @param mem pointer to the previously allocated block
176 * @param n the new size in bytes
177 * @return a pointer to the re-allocated memory
178 */
179 __attribute__((__warn_unused_result__))
180 __attribute__((__alloc_size__(3)))
181 void *cxRealloc(
182 const CxAllocator *allocator,
183 void *mem,
184 size_t n
185 );
186
187 /**
188 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
189 * This function acts like cxRealloc() using the pointer pointed to by \p mem.
190 *
191 * \note Re-allocating a block allocated by a different allocator is undefined.
192 *
193 * \par Error handling
194 * \c errno will be set, if the underlying realloc function does so.
195 *
196 * @param allocator the allocator
197 * @param mem pointer to the pointer to allocated block
198 * @param n the new size in bytes
199 * @return zero on success, non-zero on failure
200 */
201 __attribute__((__nonnull__))
202 int cxReallocate(
203 const CxAllocator *allocator,
204 void **mem,
205 size_t n
206 );
207
208 /**
209 * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
210 *
211 * @param allocator the allocator
212 * @param nelem the number of elements
213 * @param n the size of each element in bytes
214 * @return a pointer to the allocated memory
215 */
216 __attribute__((__malloc__))
217 __attribute__((__alloc_size__(2, 3)))
218 void *cxCalloc(
219 const CxAllocator *allocator,
220 size_t nelem,
221 size_t n
222 );
223
224 /**
225 * Free a block allocated by this allocator.
226 *
227 * \note Freeing a block of a different allocator is undefined.
228 *
229 * @param allocator the allocator
230 * @param mem a pointer to the block to free
231 */
232 __attribute__((__nonnull__))
233 void cxFree(
234 const CxAllocator *allocator,
235 void *mem
236 );
237
238 #ifdef __cplusplus
239 } // extern "C"
240 #endif
241
242 #endif // UCX_ALLOCATOR_H
243