src/cx/allocator.h@3d8235c96a27
src/cx/allocator.h
Sun, 26 Sep 2021 16:12:21 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Sun, 26 Sep 2021 16:12:21 +0200
- changeset 429
- 3d8235c96a27
- parent 419
- b5d6cb88d05d
- child 434
- 38ee262e8b94
- permissions
- -rw-r--r--
add documentation to allocator.h
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 void *cxMalloc(CxAllocator allocator, size_t n);
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 */
135 void *cxRealloc(CxAllocator allocator, void *mem, size_t n);
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 */
152 int cxReallocate(CxAllocator allocator, void **mem, size_t n);
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 */
162 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n);
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 */
172 void cxFree(CxAllocator allocator, void *mem);
174 #ifdef __cplusplus
175 } /* extern "C" */
176 #endif
178 #endif /* UCX_ALLOCATOR_H */
