Mercurial > hg > ucx / file comparison

comparison: src/cx/allocator.h

src/cx/allocator.h

changeset 1085
b8e0b4130cc3
parent 985
68754c7de906
child 1087
128324af5164
equal deleted inserted replaced
1084:0bcd71d2615a 1085:b8e0b4130cc3
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 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 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE. 26 * POSSIBILITY OF SUCH DAMAGE.
27 */ 27 */
28 /** 28 /**
29 * \file allocator.h 29 * @file allocator.h
30 * Interface for custom allocators. 30 * Interface for custom allocators.
31 */ 31 */
32 32
33 #ifndef UCX_ALLOCATOR_H 33 #ifndef UCX_ALLOCATOR_H
34 #define UCX_ALLOCATOR_H 34 #define UCX_ALLOCATOR_H
44 */ 44 */
45 typedef struct { 45 typedef struct {
46 /** 46 /**
47 * The allocator's malloc() implementation. 47 * The allocator's malloc() implementation.
48 */ 48 */
49 cx_attr_nonnull
50 cx_attr_nodiscard cx_attr_allocsize(2)
51 void *(*malloc)( 49 void *(*malloc)(
52 void *data, 50 void *data,
53 size_t n 51 size_t n
54 ); 52 );
55 53
56 /** 54 /**
57 * The allocator's realloc() implementation. 55 * The allocator's realloc() implementation.
58 */ 56 */
59 cx_attr_nodiscard
60 cx_attr_allocsize(3)
61 void *(*realloc)( 57 void *(*realloc)(
62 void *data, 58 void *data,
63 void *mem, 59 void *mem,
64 size_t n 60 size_t n
65 ); 61 );
66 62
67 /** 63 /**
68 * The allocator's calloc() implementation. 64 * The allocator's calloc() implementation.
69 */ 65 */
70 cx_attr_nodiscard
71 cx_attr_allocsize(2, 3)
72 void *(*calloc)( 66 void *(*calloc)(
73 void *data, 67 void *data,
74 size_t nelem, 68 size_t nelem,
75 size_t n 69 size_t n
76 ); 70 );
77 71
78 /** 72 /**
79 * The allocator's free() implementation. 73 * The allocator's free() implementation.
80 */ 74 */
81 cx_attr_nonnull_arg(1)
82 void (*free)( 75 void (*free)(
83 void *data, 76 void *data,
84 void *mem 77 void *mem
85 ); 78 );
86 } cx_allocator_class; 79 } cx_allocator_class;
111 104
112 /** 105 /**
113 * Function pointer type for destructor functions. 106 * Function pointer type for destructor functions.
114 * 107 *
115 * A destructor function deallocates possible contents and MAY free the memory 108 * A destructor function deallocates possible contents and MAY free the memory
116 * pointed to by \p memory. Read the documentation of the respective function 109 * pointed to by @p memory. Read the documentation of the respective function
117 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in 110 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
118 * that particular implementation. 111 * that particular implementation.
119 * 112 *
120 * @param memory a pointer to the object to destruct 113 * @param memory a pointer to the object to destruct
121 */ 114 */
123 116
124 /** 117 /**
125 * Function pointer type for destructor functions. 118 * Function pointer type for destructor functions.
126 * 119 *
127 * A destructor function deallocates possible contents and MAY free the memory 120 * A destructor function deallocates possible contents and MAY free the memory
128 * pointed to by \p memory. Read the documentation of the respective function 121 * pointed to by @p memory. Read the documentation of the respective function
129 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in 122 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
130 * that particular implementation. 123 * that particular implementation.
131 * 124 *
132 * @param data an optional pointer to custom data 125 * @param data an optional pointer to custom data
133 * @param memory a pointer to the object to destruct 126 * @param memory a pointer to the object to destruct
139 132
140 /** 133 /**
141 * Re-allocate a previously allocated block and changes the pointer in-place, 134 * Re-allocate a previously allocated block and changes the pointer in-place,
142 * if necessary. 135 * if necessary.
143 * 136 *
144 * \par Error handling 137 * @par Error handling
145 * \c errno will be set by realloc() on failure. 138 * @c errno will be set by realloc() on failure.
146 * 139 *
147 * @param mem pointer to the pointer to allocated block 140 * @param mem pointer to the pointer to allocated block
148 * @param n the new size in bytes 141 * @param n the new size in bytes
149 * @return zero on success, non-zero on failure 142 * @retval zero success
143 * @retval non-zero failure
144 * @see cx_reallocatearray()
150 */ 145 */
151 cx_attr_nonnull 146 cx_attr_nonnull
152 cx_attr_nodiscard 147 cx_attr_nodiscard
153 int cx_reallocate( 148 int cx_reallocate(
154 void **mem, 149 void **mem,
157 152
158 /** 153 /**
159 * Re-allocate a previously allocated block and changes the pointer in-place, 154 * Re-allocate a previously allocated block and changes the pointer in-place,
160 * if necessary. 155 * if necessary.
161 * 156 *
162 * The size is calculated by multiplying \p nemb and \p size. 157 * The size is calculated by multiplying @p nemb and @p size.
163 * 158 *
164 * \par Error handling 159 * @par Error handling
165 * \c errno will be set by realloc() on failure or when the multiplication of 160 * @c errno will be set by realloc() on failure or when the multiplication of
166 * \p nmemb and \p size overflows. 161 * @p nmemb and @p size overflows.
167 * 162 *
168 * @param mem pointer to the pointer to allocated block 163 * @param mem pointer to the pointer to allocated block
169 * @param nmemb the number of elements 164 * @param nmemb the number of elements
170 * @param size the size of each element 165 * @param size the size of each element
171 * @return zero on success, non-zero on failure 166 * @retval zero success
167 * @retval non-zero failure
168 * @see cx_reallocate()
172 */ 169 */
173 cx_attr_nonnull 170 cx_attr_nonnull
174 cx_attr_nodiscard 171 cx_attr_nodiscard
175 int cx_reallocatearray( 172 int cx_reallocatearray(
176 void **mem, 173 void **mem,
180 177
181 /** 178 /**
182 * Re-allocate a previously allocated block and changes the pointer in-place, 179 * Re-allocate a previously allocated block and changes the pointer in-place,
183 * if necessary. 180 * if necessary.
184 * 181 *
185 * \par Error handling 182 * @par Error handling
186 * \c errno will be set by realloc() on failure. 183 * @c errno will be set by realloc() on failure.
187 * 184 *
188 * @param mem pointer to the pointer to allocated block 185 * @param mem (@c void**) pointer to the pointer to allocated block
189 * @param n the new size in bytes 186 * @param n (@c size_t) the new size in bytes
190 * @return zero on success, non-zero on failure 187 * @retval zero success
188 * @retval non-zero failure
189 * @see cx_reallocatearray()
191 */ 190 */
192 #define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n) 191 #define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n)
193 192
194 /** 193 /**
195 * Re-allocate a previously allocated block and changes the pointer in-place, 194 * Re-allocate a previously allocated block and changes the pointer in-place,
196 * if necessary. 195 * if necessary.
197 * 196 *
198 * The size is calculated by multiplying \p nemb and \p size. 197 * The size is calculated by multiplying @p nemb and @p size.
199 * 198 *
200 * \par Error handling 199 * @par Error handling
201 * \c errno will be set by realloc() on failure or when the multiplication of 200 * @c errno will be set by realloc() on failure or when the multiplication of
202 * \p nmemb and \p size overflows. 201 * @p nmemb and @p size overflows.
203 * 202 *
204 * @param mem pointer to the pointer to allocated block 203 * @param mem (@c void**) pointer to the pointer to allocated block
205 * @param nmemb the number of elements 204 * @param nmemb (@c size_t) the number of elements
206 * @param size the size of each element 205 * @param size (@c size_t) the size of each element
207 * @return zero on success, non-zero on failure 206 * @retval zero success
207 * @retval non-zero failure
208 */ 208 */
209 #define cx_reallocatearray(mem, nmemb, size) \ 209 #define cx_reallocatearray(mem, nmemb, size) \
210 cx_reallocatearray((void**)(mem), nmemb, size) 210 cx_reallocatearray((void**)(mem), nmemb, size)
211 211
212 /** 212 /**
213 * Free a block allocated by this allocator. 213 * Free a block allocated by this allocator.
214 * 214 *
215 * \note Freeing a block of a different allocator is undefined. 215 * @note Freeing a block of a different allocator is undefined.
216 * 216 *
217 * @param allocator the allocator 217 * @param allocator the allocator
218 * @param mem a pointer to the block to free 218 * @param mem a pointer to the block to free
219 */ 219 */
220 cx_attr_nonnull_arg(1) 220 cx_attr_nonnull_arg(1)
222 const CxAllocator *allocator, 222 const CxAllocator *allocator,
223 void *mem 223 void *mem
224 ); 224 );
225 225
226 /** 226 /**
227 * Allocate \p n bytes of memory. 227 * Allocate @p n bytes of memory.
228 * 228 *
229 * @param allocator the allocator 229 * @param allocator the allocator
230 * @param n the number of bytes 230 * @param n the number of bytes
231 * @return a pointer to the allocated memory 231 * @return a pointer to the allocated memory
232 */ 232 */
239 const CxAllocator *allocator, 239 const CxAllocator *allocator,
240 size_t n 240 size_t n
241 ); 241 );
242 242
243 /** 243 /**
244 * Re-allocate the previously allocated block in \p mem, making the new block 244 * Re-allocate the previously allocated block in @p mem, making the new block
245 * \p n bytes long. 245 * @p n bytes long.
246 * This function may return the same pointer that was passed to it, if moving 246 * This function may return the same pointer that was passed to it, if moving
247 * the memory was not necessary. 247 * the memory was not necessary.
248 * 248 *
249 * \note Re-allocating a block allocated by a different allocator is undefined. 249 * @note Re-allocating a block allocated by a different allocator is undefined.
250 * 250 *
251 * @param allocator the allocator 251 * @param allocator the allocator
252 * @param mem pointer to the previously allocated block 252 * @param mem pointer to the previously allocated block
253 * @param n the new size in bytes 253 * @param n the new size in bytes
254 * @return a pointer to the re-allocated memory 254 * @return a pointer to the re-allocated memory
262 void *mem, 262 void *mem,
263 size_t n 263 size_t n
264 ); 264 );
265 265
266 /** 266 /**
267 * Re-allocate the previously allocated block in \p mem, making the new block 267 * Re-allocate the previously allocated block in @p mem, making the new block
268 * \p n bytes long. 268 * @p n bytes long.
269 * This function may return the same pointer that was passed to it, if moving 269 * This function may return the same pointer that was passed to it, if moving
270 * the memory was not necessary. 270 * the memory was not necessary.
271 * 271 *
272 * The size is calculated by multiplying \p nemb and \p size. 272 * The size is calculated by multiplying @p nemb and @p size.
273 * If that multiplication overflows, this function returns \c NULL and \c errno 273 * If that multiplication overflows, this function returns @c NULL and @c errno
274 * will be set. 274 * will be set.
275 * 275 *
276 * \note Re-allocating a block allocated by a different allocator is undefined. 276 * @note Re-allocating a block allocated by a different allocator is undefined.
277 * 277 *
278 * @param allocator the allocator 278 * @param allocator the allocator
279 * @param mem pointer to the previously allocated block 279 * @param mem pointer to the previously allocated block
280 * @param nmemb the number of elements 280 * @param nmemb the number of elements
281 * @param size the size of each element 281 * @param size the size of each element
293 ); 293 );
294 294
295 /** 295 /**
296 * Re-allocate a previously allocated block and changes the pointer in-place, 296 * Re-allocate a previously allocated block and changes the pointer in-place,
297 * if necessary. 297 * if necessary.
298 * This function acts like cxRealloc() using the pointer pointed to by \p mem. 298 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
299 * 299 *
300 * \note Re-allocating a block allocated by a different allocator is undefined. 300 * @note Re-allocating a block allocated by a different allocator is undefined.
301 * 301 *
302 * \par Error handling 302 * @par Error handling
303 * \c errno will be set, if the underlying realloc function does so. 303 * @c errno will be set, if the underlying realloc function does so.
304 * 304 *
305 * @param allocator the allocator 305 * @param allocator the allocator
306 * @param mem pointer to the pointer to allocated block 306 * @param mem pointer to the pointer to allocated block
307 * @param n the new size in bytes 307 * @param n the new size in bytes
308 * @return zero on success, non-zero on failure 308 * @retval zero success
309 * @retval non-zero failure
309 */ 310 */
310 cx_attr_nodiscard 311 cx_attr_nodiscard
311 cx_attr_nonnull 312 cx_attr_nonnull
312 int cxReallocate( 313 int cxReallocate(
313 const CxAllocator *allocator, 314 const CxAllocator *allocator,
316 ); 317 );
317 318
318 /** 319 /**
319 * Re-allocate a previously allocated block and changes the pointer in-place, 320 * Re-allocate a previously allocated block and changes the pointer in-place,
320 * if necessary. 321 * if necessary.
321 * This function acts like cxRealloc() using the pointer pointed to by \p mem. 322 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
322 * 323 *
323 * \note Re-allocating a block allocated by a different allocator is undefined. 324 * @note Re-allocating a block allocated by a different allocator is undefined.
324 * 325 *
325 * \par Error handling 326 * @par Error handling
326 * \c errno will be set, if the underlying realloc function does so. 327 * @c errno will be set, if the underlying realloc function does so.
327 * 328 *
328 * @param allocator the allocator 329 * @param allocator (@c const @c CxAllocator*) the allocator
329 * @param mem pointer to the pointer to allocated block 330 * @param mem (@c void**) pointer to the pointer to allocated block
330 * @param n the new size in bytes 331 * @param n (@c size_t) the new size in bytes
331 * @return zero on success, non-zero on failure 332 * @retval zero success
333 * @retval non-zero failure
332 */ 334 */
333 #define cxReallocate(allocator, mem, n) \ 335 #define cxReallocate(allocator, mem, n) \
334 cxReallocate(allocator, (void**)(mem), n) 336 cxReallocate(allocator, (void**)(mem), n)
335 337
336 /** 338 /**
337 * Re-allocate a previously allocated block and changes the pointer in-place, 339 * Re-allocate a previously allocated block and changes the pointer in-place,
338 * if necessary. 340 * if necessary.
339 * This function acts like cxReallocArray() using the pointer pointed to 341 * This function acts like cxReallocArray() using the pointer pointed to
340 * by \p mem. 342 * by @p mem.
341 * 343 *
342 * \note Re-allocating a block allocated by a different allocator is undefined. 344 * @note Re-allocating a block allocated by a different allocator is undefined.
343 * 345 *
344 * \par Error handling 346 * @par Error handling
345 * \c errno will be set, if the underlying realloc function does so or the 347 * @c errno will be set, if the underlying realloc function does so or the
346 * multiplication of \p nmemb and \p size overflows. 348 * multiplication of @p nmemb and @p size overflows.
347 * 349 *
348 * @param allocator the allocator 350 * @param allocator the allocator
349 * @param mem pointer to the pointer to allocated block 351 * @param mem pointer to the pointer to allocated block
350 * @param nmemb the number of elements 352 * @param nmemb the number of elements
351 * @param size the size of each element 353 * @param size the size of each element
352 * @return zero on success, non-zero on failure 354 * @retval zero success
355 * @retval non-zero on failure
353 */ 356 */
354 cx_attr_nodiscard 357 cx_attr_nodiscard
355 cx_attr_nonnull 358 cx_attr_nonnull
356 int cxReallocateArray( 359 int cxReallocateArray(
357 const CxAllocator *allocator, 360 const CxAllocator *allocator,
362 365
363 /** 366 /**
364 * Re-allocate a previously allocated block and changes the pointer in-place, 367 * Re-allocate a previously allocated block and changes the pointer in-place,
365 * if necessary. 368 * if necessary.
366 * This function acts like cxReallocArray() using the pointer pointed to 369 * This function acts like cxReallocArray() using the pointer pointed to
367 * by \p mem. 370 * by @p mem.
368 * 371 *
369 * \note Re-allocating a block allocated by a different allocator is undefined. 372 * @note Re-allocating a block allocated by a different allocator is undefined.
370 * 373 *
371 * \par Error handling 374 * @par Error handling
372 * \c errno will be set, if the underlying realloc function does so or the 375 * @c errno will be set, if the underlying realloc function does so or the
373 * multiplication of \p nmemb and \p size overflows. 376 * multiplication of @p nmemb and @p size overflows.
374 * 377 *
375 * @param allocator the allocator 378 * @param allocator (@c const @c CxAllocator*) the allocator
376 * @param mem pointer to the pointer to allocated block 379 * @param mem (@c void**) pointer to the pointer to allocated block
377 * @param nmemb the number of elements 380 * @param nmemb (@c size_t) the number of elements
378 * @param size the size of each element 381 * @param size (@c size_t) the size of each element
379 * @return zero on success, non-zero on failure 382 * @retval zero success
383 * @retval non-zero failure
380 */ 384 */
381 #define cxReallocateArray(allocator, mem, nmemb, size) \ 385 #define cxReallocateArray(allocator, mem, nmemb, size) \
382 cxReallocateArray(allocator, (void**) (mem), nmemb, size) 386 cxReallocateArray(allocator, (void**) (mem), nmemb, size)
383 387
384 /** 388 /**
385 * Allocate \p nelem elements of \p n bytes each, all initialized to zero. 389 * Allocate @p nelem elements of @p n bytes each, all initialized to zero.
386 * 390 *
387 * @param allocator the allocator 391 * @param allocator the allocator
388 * @param nelem the number of elements 392 * @param nelem the number of elements
389 * @param n the size of each element in bytes 393 * @param n the size of each element in bytes
390 * @return a pointer to the allocated memory 394 * @return a pointer to the allocated memory

Mercurial Repository: ucx

mercurial