Sun, 26 Sep 2021 18:01:51 +0200
add attributes to allocator functions
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 */
33 #ifndef UCX_ALLOCATOR_H
34 #define UCX_ALLOCATOR_H
36 #include <stdlib.h>
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
42 /**
43 * The class definition for an allocator.
44 */
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 */
53 void *(*malloc)(void *data, size_t n);
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 */
67 void *(*realloc)(void *data, void *mem, size_t n);
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 */
77 void *(*calloc)(void *data, size_t nelem, size_t n);
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);
88 } cx_allocator_class;
90 /**
91 * Structure holding the data for an allocator.
92 */
93 struct cx_allocator_s {
94 /**
95 * A pointer to the instance of the allocator class.
96 */
97 cx_allocator_class *cl;
98 /**
99 * A pointer to the data this allocator uses.
100 */
101 void *data;
102 };
104 /**
105 * High-Level type alias for the allocator type.
106 */
107 typedef struct cx_allocator_s *CxAllocator;
109 /**
110 * A default allocator using standard library malloc() etc.
111 */
112 extern CxAllocator cxDefaultAllocator;
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 */
121 __attribute__ ((malloc))
122 void *cxMalloc(CxAllocator allocator, size_t n);
124 /**
125 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
126 * This function may return the same pointer that was passed to it, if moving the memory
127 * was not necessary.
128 *
129 * \note Re-allocating a block allocated by a different allocator is undefined.
130 *
131 * @param allocator the allocator
132 * @param mem pointer to the previously allocated block
133 * @param n the new size in bytes
134 * @return a pointer to the re-allocated memory
135 */
136 void *cxRealloc(CxAllocator allocator, void *mem, size_t n);
138 /**
139 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
140 * This function acts like cxRealloc() using the pointer pointed to by \p mem.
141 * On success, the pointer is changed to the new location (in case the
142 *
143 * \note Re-allocating a block allocated by a different allocator is undefined.
144 *
145 * \par Error handling
146 * \c errno will be set, if the underlying realloc function does so.
147 *
148 * @param allocator the allocator
149 * @param mem pointer to the pointer to allocated block
150 * @param n the new size in bytes
151 * @return zero on success, non-zero on failure
152 */
153 __attribute__ ((nonnull))
154 int cxReallocate(CxAllocator allocator, void **mem, size_t n);
156 /**
157 * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
158 *
159 * @param allocator the allocator
160 * @param nelem the number of elements
161 * @param n the size of each element in bytes
162 * @return a pointer to the allocated memory
163 */
164 __attribute__ ((malloc))
165 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n);
167 /**
168 * Free a block allocated by this allocator.
169 *
170 * \note Freeing a block of a different allocator is undefined.
171 *
172 * @param allocator the allocator
173 * @param mem a pointer to the block to free
174 */
175 __attribute__((nonnull))
176 void cxFree(CxAllocator allocator, void *mem);
178 #ifdef __cplusplus
179 } /* extern "C" */
180 #endif
182 #endif /* UCX_ALLOCATOR_H */