universe@391: /* universe@391: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. universe@391: * universe@391: * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. universe@391: * universe@391: * Redistribution and use in source and binary forms, with or without universe@391: * modification, are permitted provided that the following conditions are met: universe@391: * universe@391: * 1. Redistributions of source code must retain the above copyright universe@391: * notice, this list of conditions and the following disclaimer. universe@391: * universe@391: * 2. Redistributions in binary form must reproduce the above copyright universe@391: * notice, this list of conditions and the following disclaimer in the universe@391: * documentation and/or other materials provided with the distribution. universe@391: * universe@391: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" universe@391: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE universe@391: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE universe@391: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE universe@391: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR universe@391: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF universe@391: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS universe@391: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN universe@391: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) universe@391: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE universe@391: * POSSIBILITY OF SUCH DAMAGE. universe@391: */ universe@429: /** universe@429: * \file allocator.h universe@429: * Interface for custom allocators. universe@429: */ universe@391: universe@391: #ifndef UCX_ALLOCATOR_H universe@391: #define UCX_ALLOCATOR_H universe@391: universe@391: #include universe@391: universe@415: #ifdef __cplusplus universe@415: extern "C" { universe@415: #endif universe@415: universe@429: /** universe@429: * The class definition for an allocator. universe@429: */ universe@396: typedef struct { universe@429: /** universe@429: * Allocate \p n bytes of memory. universe@429: * universe@429: * @param data the allocator's data universe@429: * @param n the number of bytes universe@429: * @return a pointer to the allocated memory universe@429: */ universe@405: void *(*malloc)(void *data, size_t n); universe@429: universe@429: /** universe@429: * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. universe@429: * This function may return the same pointer that was passed to it, if moving the memory universe@429: * was not necessary. universe@429: * universe@429: * \note Re-allocating a block allocated by a different allocator is undefined. universe@429: * universe@429: * @param data the allocator's data universe@429: * @param mem pointer to the previously allocated block universe@429: * @param n the new size in bytes universe@429: * @return a pointer to the re-allocated memory universe@429: */ universe@405: void *(*realloc)(void *data, void *mem, size_t n); universe@429: universe@429: /** universe@429: * Allocate \p nelem elements of \p n bytes each, all initialized to zero. universe@429: * universe@429: * @param data the allocator's data universe@429: * @param nelem the number of elements universe@429: * @param n the size of each element in bytes universe@429: * @return a pointer to the allocated memory universe@429: */ universe@405: void *(*calloc)(void *data, size_t nelem, size_t n); universe@429: universe@429: /** universe@429: * Free a block allocated by this allocator. universe@429: * universe@429: * \note Freeing a block of a different allocator is undefined. universe@429: * universe@429: * @param data the allocator's data universe@429: * @param mem a pointer to the block to free universe@429: */ universe@429: void (*free)(void *data, void *mem); universe@396: } cx_allocator_class; universe@396: universe@429: /** universe@429: * Structure holding the data for an allocator. universe@429: */ universe@394: struct cx_allocator_s { universe@429: /** universe@429: * A pointer to the instance of the allocator class. universe@429: */ universe@396: cx_allocator_class *cl; universe@429: /** universe@429: * A pointer to the data this allocator uses. universe@429: */ universe@397: void *data; universe@391: }; universe@429: universe@429: /** universe@429: * High-Level type alias for the allocator type. universe@429: */ universe@397: typedef struct cx_allocator_s *CxAllocator; universe@391: universe@429: /** universe@429: * A default allocator using standard library malloc() etc. universe@429: */ universe@391: extern CxAllocator cxDefaultAllocator; universe@391: universe@429: /** universe@429: * Allocate \p n bytes of memory. universe@429: * universe@429: * @param allocator the allocator universe@429: * @param n the number of bytes universe@429: * @return a pointer to the allocated memory universe@429: */ universe@397: void *cxMalloc(CxAllocator allocator, size_t n); universe@397: universe@429: /** universe@429: * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. universe@429: * This function may return the same pointer that was passed to it, if moving the memory universe@429: * was not necessary. universe@429: * universe@429: * \note Re-allocating a block allocated by a different allocator is undefined. universe@429: * universe@429: * @param allocator the allocator universe@429: * @param mem pointer to the previously allocated block universe@429: * @param n the new size in bytes universe@429: * @return a pointer to the re-allocated memory universe@429: */ universe@397: void *cxRealloc(CxAllocator allocator, void *mem, size_t n); universe@397: universe@429: /** universe@429: * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. universe@429: * This function acts like cxRealloc() using the pointer pointed to by \p mem. universe@429: * On success, the pointer is changed to the new location (in case the universe@429: * universe@429: * \note Re-allocating a block allocated by a different allocator is undefined. universe@429: * universe@429: * \par Error handling universe@429: * \c errno will be set, if the underlying realloc function does so. universe@429: * universe@429: * @param allocator the allocator universe@429: * @param mem pointer to the pointer to allocated block universe@429: * @param n the new size in bytes universe@429: * @return zero on success, non-zero on failure universe@429: */ universe@414: int cxReallocate(CxAllocator allocator, void **mem, size_t n); universe@414: universe@429: /** universe@429: * Allocate \p nelem elements of \p n bytes each, all initialized to zero. universe@429: * universe@429: * @param allocator the allocator universe@429: * @param nelem the number of elements universe@429: * @param n the size of each element in bytes universe@429: * @return a pointer to the allocated memory universe@429: */ universe@397: void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n); universe@397: universe@429: /** universe@429: * Free a block allocated by this allocator. universe@429: * universe@429: * \note Freeing a block of a different allocator is undefined. universe@429: * universe@429: * @param allocator the allocator universe@429: * @param mem a pointer to the block to free universe@429: */ universe@397: void cxFree(CxAllocator allocator, void *mem); universe@391: universe@415: #ifdef __cplusplus universe@415: } /* extern "C" */ universe@415: #endif universe@415: universe@393: #endif /* UCX_ALLOCATOR_H */