src/cx/allocator.h@1e3cb39815f8
src/cx/allocator.h
Tue, 05 Oct 2021 12:25:23 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Tue, 05 Oct 2021 12:25:23 +0200
- changeset 465
- 1e3cb39815f8
- parent 461
- 005c2791c2e2
- child 484
- 9e6900b1cf9d
- permissions
- -rw-r--r--
remove redundant documentation for function pointers
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 * The allocator's malloc() implementation.
48 */
49 void *(*malloc)(void *data, size_t n);
51 /**
52 * The allocator's realloc() implementation.
53 */
54 void *(*realloc)(void *data, void *mem, size_t n)
55 __attribute__((__warn_unused_result__));
57 /**
58 * The allocator's calloc() implementation.
59 */
60 void *(*calloc)(void *data, size_t nelem, size_t n);
62 /**
63 * The allocator's free() implementation.
64 */
65 void (*free)(void *data, void *mem)
66 __attribute__((__nonnull__));
67 } cx_allocator_class;
69 /**
70 * Structure holding the data for an allocator.
71 */
72 struct cx_allocator_s {
73 /**
74 * A pointer to the instance of the allocator class.
75 */
76 cx_allocator_class *cl;
77 /**
78 * A pointer to the data this allocator uses.
79 */
80 void *data;
81 };
83 /**
84 * High-Level type alias for the allocator type.
85 */
86 typedef struct cx_allocator_s *CxAllocator;
88 /**
89 * A default allocator using standard library malloc() etc.
90 */
91 extern CxAllocator cxDefaultAllocator;
93 /**
94 * Allocate \p n bytes of memory.
95 *
96 * @param allocator the allocator
97 * @param n the number of bytes
98 * @return a pointer to the allocated memory
99 */
100 void *cxMalloc(CxAllocator allocator, size_t n)
101 __attribute__((__malloc__))
102 __attribute__((__alloc_size__(2)));
104 /**
105 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
106 * This function may return the same pointer that was passed to it, if moving the memory
107 * was not necessary.
108 *
109 * \note Re-allocating a block allocated by a different allocator is undefined.
110 *
111 * @param allocator the allocator
112 * @param mem pointer to the previously allocated block
113 * @param n the new size in bytes
114 * @return a pointer to the re-allocated memory
115 */
116 void *cxRealloc(CxAllocator allocator, void *mem, size_t n)
117 __attribute__((__warn_unused_result__))
118 __attribute__((__alloc_size__(3)));
120 /**
121 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
122 * This function acts like cxRealloc() using the pointer pointed to by \p mem.
123 * On success, the pointer is changed to the new location (in case the
124 *
125 * \note Re-allocating a block allocated by a different allocator is undefined.
126 *
127 * \par Error handling
128 * \c errno will be set, if the underlying realloc function does so.
129 *
130 * @param allocator the allocator
131 * @param mem pointer to the pointer to allocated block
132 * @param n the new size in bytes
133 * @return zero on success, non-zero on failure
134 */
135 int cxReallocate(CxAllocator allocator, void **mem, size_t n)
136 __attribute__((__nonnull__));
138 /**
139 * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
140 *
141 * @param allocator the allocator
142 * @param nelem the number of elements
143 * @param n the size of each element in bytes
144 * @return a pointer to the allocated memory
145 */
146 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n)
147 __attribute__((__malloc__))
148 __attribute__((__alloc_size__(2, 3)));
150 /**
151 * Free a block allocated by this allocator.
152 *
153 * \note Freeing a block of a different allocator is undefined.
154 *
155 * @param allocator the allocator
156 * @param mem a pointer to the block to free
157 */
158 void cxFree(CxAllocator allocator, void *mem)
159 __attribute__((__nonnull__));
161 #ifdef __cplusplus
162 } /* extern "C" */
163 #endif
165 #endif /* UCX_ALLOCATOR_H */
