1 /*************************************************************************************************** 2 3 Zyan Core Library (Zycore-C) 4 5 Original Author : Florian Bernd 6 7 * Permission is hereby granted, free of charge, to any person obtaining a copy 8 * of this software and associated documentation files (the "Software"), to deal 9 * in the Software without restriction, including without limitation the rights 10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 * copies of the Software, and to permit persons to whom the Software is 12 * furnished to do so, subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included in all 15 * copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 25 ***************************************************************************************************/ 26 27 /** 28 * @file 29 * @brief 30 */ 31 32 #ifndef ZYCORE_ALLOCATOR_H 33 #define ZYCORE_ALLOCATOR_H 34 35 #include <Zycore/Status.h> 36 #include <Zycore/Types.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /* ============================================================================================== */ 43 /* Enums and types */ 44 /* ============================================================================================== */ 45 46 struct ZyanAllocator_; 47 48 /** 49 * Defines the `ZyanAllocatorAllocate` function prototype. 50 * 51 * @param allocator A pointer to the `ZyanAllocator` instance. 52 * @param p Receives a pointer to the first memory block sufficient to hold an 53 * array of `n` elements with a size of `element_size`. 54 * @param element_size The size of a single element. 55 * @param n The number of elements to allocate storage for. 56 * 57 * @return A zyan status code. 58 * 59 * This prototype is used for the `allocate()` and `reallocate()` functions. 60 * 61 * The result of the `reallocate()` function is undefined, if `p` does not point to a memory block 62 * previously obtained by `(re-)allocate()`. 63 */ 64 typedef ZyanStatus (*ZyanAllocatorAllocate)(struct ZyanAllocator_* allocator, void** p, 65 ZyanUSize element_size, ZyanUSize n); 66 67 /** 68 * Defines the `ZyanAllocatorDeallocate` function prototype. 69 * 70 * @param allocator A pointer to the `ZyanAllocator` instance. 71 * @param p The pointer obtained from `(re-)allocate()`. 72 * @param element_size The size of a single element. 73 * @param n The number of elements earlier passed to `(re-)allocate()`. 74 * 75 * @return A zyan status code. 76 */ 77 typedef ZyanStatus (*ZyanAllocatorDeallocate)(struct ZyanAllocator_* allocator, void* p, 78 ZyanUSize element_size, ZyanUSize n); 79 80 /** 81 * Defines the `ZyanAllocator` struct. 82 * 83 * This is the base class for all custom allocator implementations. 84 * 85 * All fields in this struct should be considered as "private". Any changes may lead to unexpected 86 * behavior. 87 */ 88 typedef struct ZyanAllocator_ 89 { 90 /** 91 * The allocate function. 92 */ 93 ZyanAllocatorAllocate allocate; 94 /** 95 * The reallocate function. 96 */ 97 ZyanAllocatorAllocate reallocate; 98 /** 99 * The deallocate function. 100 */ 101 ZyanAllocatorDeallocate deallocate; 102 } ZyanAllocator; 103 104 /* ============================================================================================== */ 105 /* Exported functions */ 106 /* ============================================================================================== */ 107 108 /** 109 * Initializes the given `ZyanAllocator` instance. 110 * 111 * @param allocator A pointer to the `ZyanAllocator` instance. 112 * @param allocate The allocate function. 113 * @param reallocate The reallocate function. 114 * @param deallocate The deallocate function. 115 * 116 * @return A zyan status code. 117 */ 118 ZYCORE_EXPORT ZyanStatus ZyanAllocatorInit(ZyanAllocator* allocator, ZyanAllocatorAllocate allocate, 119 ZyanAllocatorAllocate reallocate, ZyanAllocatorDeallocate deallocate); 120 121 #ifndef ZYAN_NO_LIBC 122 123 /** 124 * Returns the default `ZyanAllocator` instance. 125 * 126 * @return A pointer to the default `ZyanAllocator` instance. 127 * 128 * The default allocator uses the default memory manager to allocate memory on the heap. 129 * 130 * You should in no case modify the returned allocator instance to avoid unexpected behavior. 131 */ 132 ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanAllocator* ZyanAllocatorDefault(void); 133 134 #endif // ZYAN_NO_LIBC 135 136 /* ============================================================================================== */ 137 138 #ifdef __cplusplus 139 } 140 #endif 141 142 #endif /* ZYCORE_ALLOCATOR_H */ 143