1.1 --- a/src/cx/allocator.h Sun Sep 26 15:26:43 2021 +0200 1.2 +++ b/src/cx/allocator.h Sun Sep 26 16:12:21 2021 +0200 1.3 @@ -25,6 +25,10 @@ 1.4 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 1.5 * POSSIBILITY OF SUCH DAMAGE. 1.6 */ 1.7 +/** 1.8 + * \file allocator.h 1.9 + * Interface for custom allocators. 1.10 + */ 1.11 1.12 #ifndef UCX_ALLOCATOR_H 1.13 #define UCX_ALLOCATOR_H 1.14 @@ -35,29 +39,136 @@ 1.15 extern "C" { 1.16 #endif 1.17 1.18 +/** 1.19 + * The class definition for an allocator. 1.20 + */ 1.21 typedef struct { 1.22 + /** 1.23 + * Allocate \p n bytes of memory. 1.24 + * 1.25 + * @param data the allocator's data 1.26 + * @param n the number of bytes 1.27 + * @return a pointer to the allocated memory 1.28 + */ 1.29 void *(*malloc)(void *data, size_t n); 1.30 + 1.31 + /** 1.32 + * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. 1.33 + * This function may return the same pointer that was passed to it, if moving the memory 1.34 + * was not necessary. 1.35 + * 1.36 + * \note Re-allocating a block allocated by a different allocator is undefined. 1.37 + * 1.38 + * @param data the allocator's data 1.39 + * @param mem pointer to the previously allocated block 1.40 + * @param n the new size in bytes 1.41 + * @return a pointer to the re-allocated memory 1.42 + */ 1.43 void *(*realloc)(void *data, void *mem, size_t n); 1.44 + 1.45 + /** 1.46 + * Allocate \p nelem elements of \p n bytes each, all initialized to zero. 1.47 + * 1.48 + * @param data the allocator's data 1.49 + * @param nelem the number of elements 1.50 + * @param n the size of each element in bytes 1.51 + * @return a pointer to the allocated memory 1.52 + */ 1.53 void *(*calloc)(void *data, size_t nelem, size_t n); 1.54 - void(*free)(void *data, void *mem); 1.55 + 1.56 + /** 1.57 + * Free a block allocated by this allocator. 1.58 + * 1.59 + * \note Freeing a block of a different allocator is undefined. 1.60 + * 1.61 + * @param data the allocator's data 1.62 + * @param mem a pointer to the block to free 1.63 + */ 1.64 + void (*free)(void *data, void *mem); 1.65 } cx_allocator_class; 1.66 1.67 +/** 1.68 + * Structure holding the data for an allocator. 1.69 + */ 1.70 struct cx_allocator_s { 1.71 + /** 1.72 + * A pointer to the instance of the allocator class. 1.73 + */ 1.74 cx_allocator_class *cl; 1.75 + /** 1.76 + * A pointer to the data this allocator uses. 1.77 + */ 1.78 void *data; 1.79 }; 1.80 + 1.81 +/** 1.82 + * High-Level type alias for the allocator type. 1.83 + */ 1.84 typedef struct cx_allocator_s *CxAllocator; 1.85 1.86 +/** 1.87 + * A default allocator using standard library malloc() etc. 1.88 + */ 1.89 extern CxAllocator cxDefaultAllocator; 1.90 1.91 +/** 1.92 + * Allocate \p n bytes of memory. 1.93 + * 1.94 + * @param allocator the allocator 1.95 + * @param n the number of bytes 1.96 + * @return a pointer to the allocated memory 1.97 + */ 1.98 void *cxMalloc(CxAllocator allocator, size_t n); 1.99 1.100 +/** 1.101 + * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. 1.102 + * This function may return the same pointer that was passed to it, if moving the memory 1.103 + * was not necessary. 1.104 + * 1.105 + * \note Re-allocating a block allocated by a different allocator is undefined. 1.106 + * 1.107 + * @param allocator the allocator 1.108 + * @param mem pointer to the previously allocated block 1.109 + * @param n the new size in bytes 1.110 + * @return a pointer to the re-allocated memory 1.111 + */ 1.112 void *cxRealloc(CxAllocator allocator, void *mem, size_t n); 1.113 1.114 +/** 1.115 + * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. 1.116 + * This function acts like cxRealloc() using the pointer pointed to by \p mem. 1.117 + * On success, the pointer is changed to the new location (in case the 1.118 + * 1.119 + * \note Re-allocating a block allocated by a different allocator is undefined. 1.120 + * 1.121 + * \par Error handling 1.122 + * \c errno will be set, if the underlying realloc function does so. 1.123 + * 1.124 + * @param allocator the allocator 1.125 + * @param mem pointer to the pointer to allocated block 1.126 + * @param n the new size in bytes 1.127 + * @return zero on success, non-zero on failure 1.128 + */ 1.129 int cxReallocate(CxAllocator allocator, void **mem, size_t n); 1.130 1.131 +/** 1.132 + * Allocate \p nelem elements of \p n bytes each, all initialized to zero. 1.133 + * 1.134 + * @param allocator the allocator 1.135 + * @param nelem the number of elements 1.136 + * @param n the size of each element in bytes 1.137 + * @return a pointer to the allocated memory 1.138 + */ 1.139 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n); 1.140 1.141 +/** 1.142 + * Free a block allocated by this allocator. 1.143 + * 1.144 + * \note Freeing a block of a different allocator is undefined. 1.145 + * 1.146 + * @param allocator the allocator 1.147 + * @param mem a pointer to the block to free 1.148 + */ 1.149 void cxFree(CxAllocator allocator, void *mem); 1.150 1.151 #ifdef __cplusplus