/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file allocator.h
* Interface for custom allocators.
*/
#ifndef UCX_ALLOCATOR_H
#define UCX_ALLOCATOR_H
#include "common.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* The class definition for an allocator.
*/
typedef struct {
/**
* The allocator's malloc() implementation.
*/
void *(*malloc)(void *data, size_t n);
/**
* The allocator's realloc() implementation.
*/
void *(*realloc)(void *data, void *mem, size_t n);
/**
* The allocator's calloc() implementation.
*/
void *(*calloc)(void *data, size_t nmemb, size_t size);
/**
* The allocator's free() implementation.
*/
void (*free)(void *data, void *mem);
} cx_allocator_class;
/**
* Structure holding the data for an allocator.
*/
struct cx_allocator_s {
/**
* A pointer to the instance of the allocator class.
*/
cx_allocator_class *cl;
/**
* A pointer to the data this allocator uses.
*/
void *data;
};
/**
* High-Level type alias for the allocator type.
*/
typedef struct cx_allocator_s CxAllocator;
/**
* A pre-defined allocator using standard library malloc() etc.
*/
CX_EXPORT extern const CxAllocator * const cxStdlibAllocator;
/**
* The default allocator that is used by UCX.
* Initialized with cxStdlibAllocator, but you may change it.
*/
CX_EXPORT extern const CxAllocator * cxDefaultAllocator;
/**
* Function pointer type for destructor functions.
*
* A destructor function deallocates possible contents and MAY free the memory
* pointed to by @p memory. Read the documentation of the respective function
* pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
* that particular implementation.
*
* @param memory a pointer to the object to destruct
*/
typedef void (*cx_destructor_func)(void *memory);
/**
* Function pointer type for destructor functions.
*
* A destructor function deallocates possible contents and MAY free the memory
* pointed to by @p memory. Read the documentation of the respective function
* pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in
* that particular implementation.
*
* @param data an optional pointer to custom data
* @param memory a pointer to the object to destruct
*/
typedef void (*cx_destructor_func2)(void *data, void *memory);
/**
* Function pointer type for clone functions.
*
* A clone function is supposed to create a deep copy of the memory pointed to
* by the @p source pointer.
* If the @p target pointer is non-null, the clone function is supposed to store
* the copy into that memory region.
* Otherwise, the clone function shall use the specified @p allocator to create
* a new object.
*
* The return value of a clone function is always a pointer to the target
* memory region, or @c NULL if any allocation failed.
* A clone function SHOULD NOT fail for any other reason than an allocation
* failure.
*
* @param target the target memory or @c NULL, if memory shall be allocated
* @param source the source memory
* @param allocator the allocator that shall be used
* @param data optional additional data
* @return either the specified @p target, a pointer to the allocated memory,
* or @c NULL, if any error occurred
*/
typedef void*(cx_clone_func)(void *target, const void *source,
const CxAllocator *allocator, void *data);
/**
* Returns the system's memory page size.
*
* If the page size cannot be retrieved from the system,
* a default of 4096 bytes is assumed.
*
* @return the system's memory page size in bytes
*/
cx_attr_nodiscard
CX_EXPORT unsigned long cx_system_page_size(void);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
*
* @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
*
* @par Error handling
* @c errno will be set by realloc() on failure.
*
* @param mem pointer to the pointer to allocated block
* @param n the new size in bytes
* @retval zero success
* @retval non-zero failure
* @see cx_reallocatearray()
*/
cx_attr_nonnull cx_attr_nodiscard
CX_EXPORT int cx_reallocate_(void **mem, size_t n);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
*
* The size is calculated by multiplying @p nemb and @p size.
*
* @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
*
* @par Error handling
* @c errno will be set by realloc() on failure or when the multiplication of
* @p nmemb and @p size overflows.
*
* @param mem pointer to the pointer to allocated block
* @param nmemb the number of elements
* @param size the size of each element
* @retval zero success
* @retval non-zero failure
* @see cx_reallocate()
*/
cx_attr_nonnull cx_attr_nodiscard
CX_EXPORT int cx_reallocatearray_(void **mem, size_t nmemb, size_t size);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
*
* @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
*
* @par Error handling
* @c errno will be set by realloc() on failure.
*
* @param mem (@c void**) pointer to the pointer to allocated block
* @param n (@c size_t) the new size in bytes
* @retval zero success
* @retval non-zero failure
* @see cx_reallocatearray()
*/
#define cx_reallocate(mem, n) cx_reallocate_((void**)(mem), n)
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
*
* The size is calculated by multiplying @p nemb and @p size.
*
* @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
*
* @par Error handling
* @c errno will be set by realloc() on failure or when the multiplication of
* @p nmemb and @p size overflows.
*
* @param mem (@c void**) pointer to the pointer to allocated block
* @param nmemb (@c size_t) the number of elements
* @param size (@c size_t) the size of each element
* @retval zero success
* @retval non-zero failure
*/
#define cx_reallocatearray(mem, nmemb, size) \
cx_reallocatearray_((void**)(mem), nmemb, size)
/**
* Allocates memory and sets every byte to zero.
*
* @param n (@c size_t) the number of bytes
* @return (@c void*) a pointer to the allocated memory
*/
#define cx_zalloc(n) calloc(1, n)
/**
* Free a block allocated by this allocator.
*
* @note Freeing a block of a different allocator is undefined.
*
* @param allocator the allocator
* @param mem a pointer to the block to free
*/
cx_attr_nonnull_arg(1)
CX_EXPORT void cxFree(const CxAllocator *allocator, void *mem);
/**
* Allocate @p n bytes of memory.
*
* @param allocator the allocator
* @param n the number of bytes
* @return a pointer to the allocated memory
*/
cx_attr_nodiscard cx_attr_nonnull
cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
CX_EXPORT void *cxMalloc(const CxAllocator *allocator, size_t n);
/**
* Reallocate the previously allocated block in @p mem, making the new block
* @p n bytes long.
* This function may return the same pointer passed to it if moving
* the memory was not necessary.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @param allocator the allocator
* @param mem pointer to the previously allocated block
* @param n the new size in bytes
* @return a pointer to the reallocated memory
*/
cx_attr_nodiscard cx_attr_nonnull_arg(1)
cx_attr_dealloc_ucx cx_attr_allocsize(3)
CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
/**
* Reallocate the previously allocated block in @p mem, making the new block
* @p n bytes long.
* This function may return the same pointer passed to it if moving
* the memory was not necessary.
*
* The size is calculated by multiplying @p nemb and @p size.
* If that multiplication overflows, this function returns @c NULL, and @c errno
* will be set.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @param allocator the allocator
* @param mem pointer to the previously allocated block
* @param nmemb the number of elements
* @param size the size of each element
* @return a pointer to the reallocated memory
*/
cx_attr_nodiscard cx_attr_nonnull_arg(1)
cx_attr_dealloc_ucx cx_attr_allocsize(3, 4)
CX_EXPORT void *cxReallocArray(const CxAllocator *allocator,
void *mem, size_t nmemb, size_t size);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
* This function acts like cxRealloc() using the pointer pointed to by @p mem.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @par Error handling
* @c errno will be set if the underlying realloc function does so.
*
* @param allocator the allocator
* @param mem pointer to the pointer to allocated block
* @param n the new size in bytes
* @retval zero success
* @retval non-zero failure
*/
cx_attr_nodiscard cx_attr_nonnull
CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
* This function acts like cxRealloc() using the pointer pointed to by @p mem.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @par Error handling
* @c errno will be set if the underlying realloc function does so.
*
* @param allocator (@c CxAllocator*) the allocator
* @param mem (@c void**) pointer to the pointer to allocated block
* @param n (@c size_t) the new size in bytes
* @retval zero success
* @retval non-zero failure
*/
#define cxReallocate(allocator, mem, n) \
cxReallocate_(allocator, (void**)(mem), n)
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
* This function acts like cxReallocArray() using the pointer pointed to
* by @p mem.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @par Error handling
* @c errno will be set, if the underlying realloc function does so or the
* multiplication of @p nmemb and @p size overflows.
*
* @param allocator the allocator
* @param mem pointer to the pointer to allocated block
* @param nmemb the number of elements
* @param size the size of each element
* @retval zero success
* @retval non-zero on failure
*/
cx_attr_nodiscard cx_attr_nonnull
CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator,
void **mem, size_t nmemb, size_t size);
/**
* Reallocate a previously allocated block and changes the pointer in-place,
* if necessary.
* This function acts like cxReallocArray() using the pointer pointed to
* by @p mem.
*
* @note Re-allocating a block allocated by a different allocator is undefined.
*
* @par Error handling
* @c errno will be set, if the underlying realloc function does so or the
* multiplication of @p nmemb and @p size overflows.
*
* @param allocator (@c CxAllocator*) the allocator
* @param mem (@c void**) pointer to the pointer to allocated block
* @param nmemb (@c size_t) the number of elements
* @param size (@c size_t) the size of each element
* @retval zero success
* @retval non-zero failure
*/
#define cxReallocateArray(allocator, mem, nmemb, size) \
cxReallocateArray_(allocator, (void**) (mem), nmemb, size)
/**
* Allocate @p nmemb elements of @p n bytes each, all initialized to zero.
*
* @param allocator the allocator
* @param nmemb the number of elements
* @param size the size of each element in bytes
* @return a pointer to the allocated memory
*/
cx_attr_nonnull_arg(1) cx_attr_nodiscard
cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
/**
* Allocate @p n bytes of memory and sets every byte to zero.
*
* @param allocator the allocator
* @param n the number of bytes
* @return a pointer to the allocated memory
*/
cx_attr_nodiscard cx_attr_nonnull
cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
/**
* Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
*/
#define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
*/
#define cxZallocDefault(...) cxZalloc(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
*/
#define cxCallocDefault(...) cxCalloc(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
*/
#define cxReallocDefault(...) cxRealloc(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
*/
#define cxReallocateDefault(...) cxReallocate(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
*/
#define cxReallocateArrayDefault(...) cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
*/
#define cxReallocArrayDefault(...) cxReallocArray(cxDefaultAllocator, __VA_ARGS__)
/**
* Convenience function that invokes cxFree() with the cxDefaultAllocator.
*/
CX_EXPORT void cxFreeDefault(void *mem);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // UCX_ALLOCATOR_H