Mercurial > hg > dav / file comparison

comparison: ucx/cx/allocator.h

ucx/cx/allocator.h

branch
dav-2
changeset 891
4d58cbcc9efa
parent 889
42cdbf9bbd49
equal deleted inserted replaced
890:e77ccf1c4bb3 891:4d58cbcc9efa
140 * @param allocator the allocator that shall be used 140 * @param allocator the allocator that shall be used
141 * @param data optional additional data 141 * @param data optional additional data
142 * @return either the specified @p target, a pointer to the allocated memory, 142 * @return either the specified @p target, a pointer to the allocated memory,
143 * or @c NULL, if any error occurred 143 * or @c NULL, if any error occurred
144 */ 144 */
145 typedef void*(cx_clone_func)(void *target, const void *source, 145 typedef void*(*cx_clone_func)(void *target, const void *source,
146 const CxAllocator *allocator, void *data); 146 const CxAllocator *allocator, void *data);
147 147
148 /** 148 /**
149 * Reallocate a previously allocated block and changes the pointer in-place, 149 * Returns the system's memory page size.
150 * if necessary. 150 *
151 * 151 * If the page size cannot be retrieved from the system,
152 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator. 152 * a default of 4096 bytes is assumed.
153 * 153 *
154 * @par Error handling 154 * @return the system's memory page size in bytes
155 * @c errno will be set by realloc() on failure. 155 */
156 cx_attr_nodiscard
157 CX_EXPORT unsigned long cx_system_page_size(void);
158
159 /**
160 * Reallocate a previously allocated block.
161 *
162 * Internal function - do not use.
156 * 163 *
157 * @param mem pointer to the pointer to allocated block 164 * @param mem pointer to the pointer to allocated block
158 * @param n the new size in bytes 165 * @param n the new size in bytes
159 * @retval zero success 166 * @retval zero success
160 * @retval non-zero failure 167 * @retval non-zero failure
162 */ 169 */
163 cx_attr_nonnull cx_attr_nodiscard 170 cx_attr_nonnull cx_attr_nodiscard
164 CX_EXPORT int cx_reallocate_(void **mem, size_t n); 171 CX_EXPORT int cx_reallocate_(void **mem, size_t n);
165 172
166 /** 173 /**
167 * Reallocate a previously allocated block and changes the pointer in-place, 174 * Reallocate a previously allocated block.
168 * if necessary. 175 *
169 * 176 * Internal function - do not use.
170 * The size is calculated by multiplying @p nemb and @p size.
171 *
172 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
173 *
174 * @par Error handling
175 * @c errno will be set by realloc() on failure or when the multiplication of
176 * @p nmemb and @p size overflows.
177 * 177 *
178 * @param mem pointer to the pointer to allocated block 178 * @param mem pointer to the pointer to allocated block
179 * @param nmemb the number of elements 179 * @param nmemb the number of elements
180 * @param size the size of each element 180 * @param size the size of each element
181 * @retval zero success 181 * @retval zero success
259 * This function may return the same pointer passed to it if moving 259 * This function may return the same pointer passed to it if moving
260 * the memory was not necessary. 260 * the memory was not necessary.
261 * 261 *
262 * @note Re-allocating a block allocated by a different allocator is undefined. 262 * @note Re-allocating a block allocated by a different allocator is undefined.
263 * 263 *
264 * @attention This function is bug-prone. Consider using cxReallocate().
265 *
264 * @param allocator the allocator 266 * @param allocator the allocator
265 * @param mem pointer to the previously allocated block 267 * @param mem pointer to the previously allocated block
266 * @param n the new size in bytes 268 * @param n the new size in bytes
267 * @return a pointer to the reallocated memory 269 * @return a pointer to the reallocated memory
268 */ 270 */
269 cx_attr_nodiscard cx_attr_nonnull_arg(1) 271 cx_attr_nodiscard cx_attr_nonnull_arg(1)
270 cx_attr_dealloc_ucx cx_attr_allocsize(3) 272 cx_attr_dealloc_ucx cx_attr_allocsize(3)
271 CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n); 273 CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
272 274
273 /** 275 /**
274 * Reallocate the previously allocated block in @p mem, making the new block 276 * Reallocate the previously allocated block in @p mem.
275 * @p n bytes long. 277 *
276 * This function may return the same pointer passed to it if moving 278 * This function may return the same pointer passed to it if moving
277 * the memory was not necessary. 279 * the memory was not necessary.
278 * 280 *
279 * The size is calculated by multiplying @p nemb and @p size. 281 * The size is calculated by multiplying @p nemb and @p size.
280 * If that multiplication overflows, this function returns @c NULL, and @c errno 282 * If that multiplication overflows, this function returns @c NULL, and @c errno
281 * will be set. 283 * will be set.
282 * 284 *
283 * @note Re-allocating a block allocated by a different allocator is undefined. 285 * @note Re-allocating a block allocated by a different allocator is undefined.
286 *
287 * @attention This function is bug-prone. Consider using cxReallocateArray().
284 * 288 *
285 * @param allocator the allocator 289 * @param allocator the allocator
286 * @param mem pointer to the previously allocated block 290 * @param mem pointer to the previously allocated block
287 * @param nmemb the number of elements 291 * @param nmemb the number of elements
288 * @param size the size of each element 292 * @param size the size of each element
292 cx_attr_dealloc_ucx cx_attr_allocsize(3, 4) 296 cx_attr_dealloc_ucx cx_attr_allocsize(3, 4)
293 CX_EXPORT void *cxReallocArray(const CxAllocator *allocator, 297 CX_EXPORT void *cxReallocArray(const CxAllocator *allocator,
294 void *mem, size_t nmemb, size_t size); 298 void *mem, size_t nmemb, size_t size);
295 299
296 /** 300 /**
301 * Reallocate a previously allocated block.
302 *
303 * Internal function - do not use.
304 *
305 * @param allocator the allocator
306 * @param mem pointer to the pointer to allocated block
307 * @param n the new size in bytes
308 * @retval zero success
309 * @retval non-zero failure
310 */
311 cx_attr_nodiscard cx_attr_nonnull
312 CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
313
314 /**
297 * Reallocate a previously allocated block and changes the pointer in-place, 315 * Reallocate a previously allocated block and changes the pointer in-place,
298 * if necessary. 316 * if necessary.
299 * This function acts like cxRealloc() using the pointer pointed to by @p mem. 317 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
300 * 318 *
301 * @note Re-allocating a block allocated by a different allocator is undefined. 319 * @note Re-allocating a block allocated by a different allocator is undefined.
302 * 320 *
303 * @par Error handling 321 * @par Error handling
304 * @c errno will be set if the underlying realloc function does so. 322 * @c errno will be set if the underlying realloc function does so.
305 * 323 *
306 * @param allocator the allocator
307 * @param mem pointer to the pointer to allocated block
308 * @param n the new size in bytes
309 * @retval zero success
310 * @retval non-zero failure
311 */
312 cx_attr_nodiscard cx_attr_nonnull
313 CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
314
315 /**
316 * Reallocate a previously allocated block and changes the pointer in-place,
317 * if necessary.
318 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
319 *
320 * @note Re-allocating a block allocated by a different allocator is undefined.
321 *
322 * @par Error handling
323 * @c errno will be set if the underlying realloc function does so.
324 *
325 * @param allocator (@c CxAllocator*) the allocator 324 * @param allocator (@c CxAllocator*) the allocator
326 * @param mem (@c void**) pointer to the pointer to allocated block 325 * @param mem (@c void**) pointer to the pointer to allocated block
327 * @param n (@c size_t) the new size in bytes 326 * @param n (@c size_t) the new size in bytes
328 * @retval zero success 327 * @retval zero success
329 * @retval non-zero failure 328 * @retval non-zero failure
330 */ 329 */
331 #define cxReallocate(allocator, mem, n) \ 330 #define cxReallocate(allocator, mem, n) \
332 cxReallocate_(allocator, (void**)(mem), n) 331 cxReallocate_(allocator, (void**)(mem), n)
332
333 /**
334 * Reallocate a previously allocated block.
335 *
336 * Internal function - do not use.
337 *
338 * @param allocator the allocator
339 * @param mem pointer to the pointer to allocated block
340 * @param nmemb the number of elements
341 * @param size the size of each element
342 * @retval zero success
343 * @retval non-zero on failure
344 */
345 cx_attr_nodiscard cx_attr_nonnull
346 CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator,
347 void **mem, size_t nmemb, size_t size);
333 348
334 /** 349 /**
335 * Reallocate a previously allocated block and changes the pointer in-place, 350 * Reallocate a previously allocated block and changes the pointer in-place,
336 * if necessary. 351 * if necessary.
337 * This function acts like cxReallocArray() using the pointer pointed to 352 * This function acts like cxReallocArray() using the pointer pointed to
341 * 356 *
342 * @par Error handling 357 * @par Error handling
343 * @c errno will be set, if the underlying realloc function does so or the 358 * @c errno will be set, if the underlying realloc function does so or the
344 * multiplication of @p nmemb and @p size overflows. 359 * multiplication of @p nmemb and @p size overflows.
345 * 360 *
346 * @param allocator the allocator 361 * @param allocator (@c CxAllocator*) the allocator
347 * @param mem pointer to the pointer to allocated block 362 * @param mem (@c void**) pointer to the pointer to allocated block
363 * @param nmemb (@c size_t) the number of elements
364 * @param size (@c size_t) the size of each element
365 * @retval zero success
366 * @retval non-zero failure
367 */
368 #define cxReallocateArray(allocator, mem, nmemb, size) \
369 cxReallocateArray_(allocator, (void**) (mem), nmemb, size)
370
371 /**
372 * Allocate @p nmemb elements of @p size bytes each, all initialized to zero.
373 *
374 * @param allocator the allocator
348 * @param nmemb the number of elements 375 * @param nmemb the number of elements
349 * @param size the size of each element 376 * @param size the size of each element in bytes
350 * @retval zero success 377 * @return a pointer to the allocated memory
351 * @retval non-zero on failure 378 */
379 cx_attr_nonnull_arg(1) cx_attr_nodiscard
380 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
381 CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
382
383 /**
384 * Allocate @p n bytes of memory and sets every byte to zero.
385 *
386 * @param allocator the allocator
387 * @param n the number of bytes
388 * @return a pointer to the allocated memory
352 */ 389 */
353 cx_attr_nodiscard cx_attr_nonnull 390 cx_attr_nodiscard cx_attr_nonnull
354 CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator, 391 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
355 void **mem, size_t nmemb, size_t size); 392 CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
393
394 /**
395 * Allocate @p n bytes of memory.
396 *
397 * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
398 *
399 * @param n (@c size_t) the number of bytes
400 * @return (@c void*) a pointer to the allocated memory
401 */
402 #define cxMallocDefault(n) cxMalloc(cxDefaultAllocator, n)
403
404 /**
405 * Allocate @p n bytes of memory and sets every byte to zero.
406 *
407 * Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
408 *
409 * @param n (@c size_t) the number of bytes
410 * @return (@c void*) a pointer to the allocated memory
411 */
412 #define cxZallocDefault(n) cxZalloc(cxDefaultAllocator, n)
413
414 /**
415 * Allocate @p nmemb elements of @p size bytes each, all initialized to zero.
416 *
417 * Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
418 *
419 * @param nmemb (@c size_t) the number of elements
420 * @param size (@c size_t) the size of each element in bytes
421 * @return (@c void*) a pointer to the allocated memory
422 */
423 #define cxCallocDefault(nmemb, size) cxCalloc(cxDefaultAllocator, nmemb, size)
424
425 /**
426 * Reallocate the previously allocated block in @p mem.
427 *
428 * This function may return the same pointer passed to it if moving
429 * the memory was not necessary.
430 *
431 * Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
432 *
433 * @attention This function is bug-prone. Consider using cxReallocateDefault().
434 *
435 * @param mem (@c void*) pointer to the previously allocated block
436 * @param n (@c size_t) the new size in bytes
437 * @return (@c void*) a pointer to the reallocated memory
438 */
439 #define cxReallocDefault(mem, n) cxRealloc(cxDefaultAllocator, mem, n)
440
441 /**
442 * Reallocate a previously allocated block and changes the pointer in-place,
443 * if necessary.
444 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
445 *
446 * Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
447 *
448 * @note Re-allocating a block allocated by a different allocator is undefined.
449 *
450 * @par Error handling
451 * @c errno will be set if the underlying realloc function does so.
452 *
453 * @param mem (@c void**) pointer to the pointer to allocated block
454 * @param n (@c size_t) the new size in bytes
455 * @retval zero success
456 * @retval non-zero failure
457 */
458 #define cxReallocateDefault(mem, n) cxReallocate(cxDefaultAllocator, mem, n)
356 459
357 /** 460 /**
358 * Reallocate a previously allocated block and changes the pointer in-place, 461 * Reallocate a previously allocated block and changes the pointer in-place,
359 * if necessary. 462 * if necessary.
360 * This function acts like cxReallocArray() using the pointer pointed to 463 * This function acts like cxReallocArray() using the pointer pointed to
361 * by @p mem. 464 * by @p mem.
362 * 465 *
466 * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
467 *
363 * @note Re-allocating a block allocated by a different allocator is undefined. 468 * @note Re-allocating a block allocated by a different allocator is undefined.
364 * 469 *
365 * @par Error handling 470 * @par Error handling
366 * @c errno will be set, if the underlying realloc function does so or the 471 * @c errno will be set, if the underlying realloc function does so or the
367 * multiplication of @p nmemb and @p size overflows. 472 * multiplication of @p nmemb and @p size overflows.
368 * 473 *
369 * @param allocator (@c CxAllocator*) the allocator
370 * @param mem (@c void**) pointer to the pointer to allocated block 474 * @param mem (@c void**) pointer to the pointer to allocated block
371 * @param nmemb (@c size_t) the number of elements 475 * @param nmemb (@c size_t) the number of elements
372 * @param size (@c size_t) the size of each element 476 * @param size (@c size_t) the size of each element
373 * @retval zero success 477 * @retval zero success
374 * @retval non-zero failure 478 * @retval non-zero failure
375 */ 479 */
376 #define cxReallocateArray(allocator, mem, nmemb, size) \ 480 #define cxReallocateArrayDefault(mem, nmemb, size) \
377 cxReallocateArray_(allocator, (void**) (mem), nmemb, size) 481 cxReallocateArray(cxDefaultAllocator, mem, nmemb, size)
378 482
379 /** 483 /**
380 * Allocate @p nmemb elements of @p n bytes each, all initialized to zero. 484 * Reallocate the previously allocated block in @p mem.
381 * 485 *
382 * @param allocator the allocator
383 * @param nmemb the number of elements
384 * @param size the size of each element in bytes
385 * @return a pointer to the allocated memory
386 */
387 cx_attr_nonnull_arg(1) cx_attr_nodiscard
388 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
389 CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
390
391 /**
392 * Allocate @p n bytes of memory and sets every byte to zero.
393 *
394 * @param allocator the allocator
395 * @param n the number of bytes
396 * @return a pointer to the allocated memory
397 */
398 cx_attr_nodiscard cx_attr_nonnull
399 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
400 CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
401
402 /**
403 * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
404 */
405 #define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)
406 /**
407 * Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
408 */
409 #define cxZallocDefault(...) cxZalloc(cxDefaultAllocator, __VA_ARGS__)
410 /**
411 * Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
412 */
413 #define cxCallocDefault(...) cxCalloc(cxDefaultAllocator, __VA_ARGS__)
414 /**
415 * Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
416 */
417 #define cxReallocDefault(...) cxRealloc(cxDefaultAllocator, __VA_ARGS__)
418 /**
419 * Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
420 */
421 #define cxReallocateDefault(...) cxReallocate(cxDefaultAllocator, __VA_ARGS__)
422 /**
423 * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
424 */
425 #define cxReallocateArrayDefault(...) cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)
426 /**
427 * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator. 486 * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
428 */ 487 *
429 #define cxReallocArrayDefault(...) cxReallocArray(cxDefaultAllocator, __VA_ARGS__) 488 * This function may return the same pointer passed to it if moving
430 /** 489 * the memory was not necessary.
431 * Convenience macro that invokes cxFree() with the cxDefaultAllocator. 490 *
432 */ 491 * The size is calculated by multiplying @p nemb and @p size.
433 #define cxFreeDefault(...) cxFree(cxDefaultAllocator, __VA_ARGS__) 492 * If that multiplication overflows, this function returns @c NULL, and @c errno
493 * will be set.
494 *
495 * @note Re-allocating a block allocated by a different allocator is undefined.
496 *
497 * @attention This function is bug-prone. Consider using cxReallocateArrayDefault().
498 *
499 * @param mem (@c void*) pointer to the previously allocated block
500 * @param nmemb (@c size_t) the number of elements
501 * @param size (@c size_t) the size of each element
502 * @return (@c void*) a pointer to the reallocated memory
503 */
504 #define cxReallocArrayDefault(mem, nmemb, size) cxReallocArray(cxDefaultAllocator, mem, nmemb, size)
505
506 /**
507 * Free a block of memory.
508 *
509 * Convenience function that invokes cxFree() with the cxDefaultAllocator.
510 *
511 * @param mem the memory to deallocate
512 */
513 CX_EXPORT void cxFreeDefault(void *mem);
434 514
435 #ifdef __cplusplus 515 #ifdef __cplusplus
436 } // extern "C" 516 } // extern "C"
437 #endif 517 #endif
438 518

Mercurial Repository: dav

mercurial