2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
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.
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.
30 * Interface for custom allocators.
33 #ifndef UCX_ALLOCATOR_H
34 #define UCX_ALLOCATOR_H
43 * The class definition for an allocator.
47 * The allocator's malloc() implementation.
55 * The allocator's realloc() implementation.
62 __attribute__((__warn_unused_result__));
65 * The allocator's calloc() implementation.
74 * The allocator's free() implementation.
80 __attribute__((__nonnull__));
84 * Structure holding the data for an allocator.
86 struct cx_allocator_s {
88 * A pointer to the instance of the allocator class.
90 cx_allocator_class *cl;
92 * A pointer to the data this allocator uses.
98 * High-Level type alias for the allocator type.
100 typedef struct cx_allocator_s CxAllocator;
103 * A default allocator using standard library malloc() etc.
105 extern CxAllocator *cxDefaultAllocator;
108 * Function pointer type for destructor functions.
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.
115 * @param memory a pointer to the object to destruct
117 typedef void (*cx_destructor_func)(void *memory) __attribute__((__nonnull__));
120 * Function pointer type for destructor functions.
122 * A destructor function deallocates possible contents and MAY free the memory
123 * pointed to by \p memory. Read the documentation of the respective function
124 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
125 * particular implementation.
127 * @param data an optional pointer to custom data
128 * @param memory a pointer to the object to destruct
130 typedef void (*cx_destructor_func2)(
133 ) __attribute__((__nonnull__(2)));
136 * Structure holding an advanced destructor function and the desired payload.
137 * Invocations of func should use data as first argument.
141 * A pointer to the data that SHALL be used to invoke func.
145 * A pointer to the function to invoke.
147 cx_destructor_func2 func;
148 } cx_advanced_destructor;
151 * Specifies the type of destructor to use.
153 enum cx_destructor_type {
155 * Do not use a destructor function.
159 * Use a simple destructor.
160 * @see cx_destructor_func
162 CX_DESTRUCTOR_SIMPLE,
164 * Use an advanced destructor.
165 * @see cx_advanced_destructor
167 CX_DESTRUCTOR_ADVANCED
171 * Allocate \p n bytes of memory.
173 * @param allocator the allocator
174 * @param n the number of bytes
175 * @return a pointer to the allocated memory
178 CxAllocator const *allocator,
181 __attribute__((__malloc__))
182 __attribute__((__alloc_size__(2)));
185 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
186 * This function may return the same pointer that was passed to it, if moving the memory
189 * \note Re-allocating a block allocated by a different allocator is undefined.
191 * @param allocator the allocator
192 * @param mem pointer to the previously allocated block
193 * @param n the new size in bytes
194 * @return a pointer to the re-allocated memory
197 CxAllocator const *allocator,
201 __attribute__((__warn_unused_result__))
202 __attribute__((__alloc_size__(3)));
205 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
206 * This function acts like cxRealloc() using the pointer pointed to by \p mem.
207 * On success, the pointer is changed to the new location (in case the
209 * \note Re-allocating a block allocated by a different allocator is undefined.
211 * \par Error handling
212 * \c errno will be set, if the underlying realloc function does so.
214 * @param allocator the allocator
215 * @param mem pointer to the pointer to allocated block
216 * @param n the new size in bytes
217 * @return zero on success, non-zero on failure
220 CxAllocator const *allocator,
224 __attribute__((__nonnull__));
227 * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
229 * @param allocator the allocator
230 * @param nelem the number of elements
231 * @param n the size of each element in bytes
232 * @return a pointer to the allocated memory
235 CxAllocator const *allocator,
239 __attribute__((__malloc__))
240 __attribute__((__alloc_size__(2, 3)));
243 * Free a block allocated by this allocator.
245 * \note Freeing a block of a different allocator is undefined.
247 * @param allocator the allocator
248 * @param mem a pointer to the block to free
251 CxAllocator const *allocator,
254 __attribute__((__nonnull__));
260 #endif // UCX_ALLOCATOR_H