|
| 1 | +/* |
| 2 | + * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems. |
| 3 | + * |
| 4 | + * Source: https://github.com/SuperTinyKernel-RTOS |
| 5 | + * |
| 6 | + * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved. |
| 7 | + * License: MIT License, see LICENSE for a full text. |
| 8 | + */ |
| 9 | + |
| 10 | +#ifndef STK_MEMORY_ALLOCATOR_H_ |
| 11 | +#define STK_MEMORY_ALLOCATOR_H_ |
| 12 | + |
| 13 | +#include "stk_defs.h" |
| 14 | + |
| 15 | +/*! \def STK_MEMORY_PLACEMENTNEW |
| 16 | + \brief When defined as 1, placement new C++ operator is enabled for memory::MemoryAllocator. |
| 17 | + \see memory::MemoryAllocator::AllocateOneT, memory::MemoryAllocator::AllocateArrayT |
| 18 | +*/ |
| 19 | +#ifndef STK_MEMORY_PLACEMENT_NEW |
| 20 | + #define STK_MEMORY_PLACEMENT_NEW 1 |
| 21 | +#endif |
| 22 | + |
| 23 | +#if STK_MEMORY_PLACEMENT_NEW |
| 24 | +#include <type_traits> |
| 25 | +#include <new> |
| 26 | +#endif |
| 27 | + |
| 28 | +/*! \file stk_memory_allocator.h |
| 29 | + \brief Weak declaration of memory allocator: stk::memory::MemoryAllocator. |
| 30 | +*/ |
| 31 | + |
| 32 | +namespace stk { |
| 33 | +namespace memory { |
| 34 | + |
| 35 | +/*! \class MemoryAllocator |
| 36 | + \brief Memory allocator for allocating dynamic memory. |
| 37 | + \note STK does not use dynamic memory allocation but some auxiliary classes may provide such |
| 38 | + functionality for convenience. In this case you must provide your own implementation |
| 39 | + of MemoryAllocator::Allocate() and MemoryAllocator::Free(). By default STK does not |
| 40 | + provide any implementation, therefore you will get a linker error if these two functions |
| 41 | + are left unimplemented. |
| 42 | +
|
| 43 | + Example of your trivial implementation: |
| 44 | + \code |
| 45 | + void *MemoryAllocator::Allocate(size_t size) |
| 46 | + { |
| 47 | + return malloc(size); |
| 48 | + } |
| 49 | + void MemoryAllocator::Free(void *ptr) |
| 50 | + { |
| 51 | + free(ptr); |
| 52 | + } |
| 53 | + \endcode |
| 54 | +*/ |
| 55 | +struct MemoryAllocator |
| 56 | +{ |
| 57 | + /*! \brief Allocate the memory chunk. |
| 58 | + \param[in] size: Size of the memory chunk. |
| 59 | + \return Pointer to the allocated memory chunk, nullptr if allocator failed to allocate it. |
| 60 | + */ |
| 61 | + static void *Allocate(size_t size) __stk_weak; |
| 62 | + |
| 63 | + /*! \brief Free the memory chunk. |
| 64 | + \param[in] ptr: Pointer to the memory chunk. nullptr is allowed and results in noop. |
| 65 | + */ |
| 66 | + static void Free(void *ptr) __stk_weak; |
| 67 | + |
| 68 | +#if STK_MEMORY_PLACEMENT_NEW |
| 69 | + |
| 70 | + /*! \brief Allocate a single element and construct it in-place. |
| 71 | + \param[in] args: Constructor arguments forwarded to TElement. |
| 72 | + \return Pointer to the constructed element, nullptr if allocation failed. |
| 73 | + \note Pair with FreeOneT<TElement>() to properly invoke the destructor. |
| 74 | + */ |
| 75 | + template <typename TElement, typename... TArgs> |
| 76 | + static inline TElement *AllocateOneT(TArgs &&...args) |
| 77 | + { |
| 78 | + STK_ASSERT(Allocate != nullptr); |
| 79 | + |
| 80 | + TElement *ptr = reinterpret_cast<TElement *>(Allocate(sizeof(TElement))); |
| 81 | + if (ptr != nullptr) |
| 82 | + { |
| 83 | + if (!std::is_trivially_constructible<TElement, TArgs...>()) |
| 84 | + new (ptr) TElement(static_cast<TArgs &&>(args)...); |
| 85 | + } |
| 86 | + |
| 87 | + return ptr; |
| 88 | + } |
| 89 | + |
| 90 | + /*! \brief Allocate an array of elements and default/copy-construct each one. |
| 91 | + \param[in] count: Number of elements to allocate. |
| 92 | + \param[in] args: Constructor arguments forwarded to every element. |
| 93 | + \return Pointer to the first element, nullptr if allocation failed or count is 0. |
| 94 | + \note Pair with FreeArrayT<TElement>() passing the same count to properly invoke destructors. |
| 95 | + */ |
| 96 | + template <typename TElement, typename... TArgs> |
| 97 | + static inline TElement *AllocateArrayT(size_t count, TArgs &&...args) |
| 98 | + { |
| 99 | + if (count == 0) |
| 100 | + return nullptr; |
| 101 | + |
| 102 | + STK_ASSERT(Allocate != nullptr); |
| 103 | + |
| 104 | + TElement *ptr = reinterpret_cast<TElement *>(Allocate(count * sizeof(TElement))); |
| 105 | + if (ptr != nullptr) |
| 106 | + { |
| 107 | + if (!std::is_trivially_constructible<TElement, TArgs...>()) |
| 108 | + { |
| 109 | + for (size_t i = 0; i < count; ++i) |
| 110 | + new (&ptr[i]) TElement(static_cast<TArgs &&>(args)...); |
| 111 | + } |
| 112 | + } |
| 113 | + |
| 114 | + return ptr; |
| 115 | + } |
| 116 | + |
| 117 | + /*! \brief Destroy and free a single element allocated via AllocateOne(). |
| 118 | + \param[in] ptr: Pointer to the element. nullptr is allowed and results in noop. |
| 119 | + */ |
| 120 | + template <typename TElement> |
| 121 | + static inline void FreeOneT(TElement *ptr) |
| 122 | + { |
| 123 | + STK_ASSERT(Free != nullptr); |
| 124 | + |
| 125 | + if (ptr != nullptr) |
| 126 | + { |
| 127 | + if (!std::is_trivially_destructible<TElement>()) |
| 128 | + ptr->~TElement(); |
| 129 | + |
| 130 | + Free(ptr); |
| 131 | + } |
| 132 | + } |
| 133 | + |
| 134 | + /*! \brief Destroy and free an array allocated via AllocateT(). |
| 135 | + \param[in] ptr: Pointer to the first element. nullptr is allowed and results in noop. |
| 136 | + \param[in] count: Number of elements (must match the count passed to AllocateT()). |
| 137 | + */ |
| 138 | + template <typename TElement> |
| 139 | + static inline void FreeArrayT(TElement *ptr, size_t count) |
| 140 | + { |
| 141 | + STK_ASSERT(Free != nullptr); |
| 142 | + |
| 143 | + if (ptr != nullptr) |
| 144 | + { |
| 145 | + if (!std::is_trivially_destructible<TElement>()) |
| 146 | + { |
| 147 | + // destroy in reverse order (mirrors stack unwinding) |
| 148 | + for (size_t i = count; i > 0; --i) |
| 149 | + ptr[i - 1].~TElement(); |
| 150 | + } |
| 151 | + |
| 152 | + Free(ptr); |
| 153 | + } |
| 154 | + } |
| 155 | + |
| 156 | +#endif // STK_MEMORY_PLACEMENT_NEW |
| 157 | +}; |
| 158 | + |
| 159 | +} // namespace memory |
| 160 | +} // namespace stk |
| 161 | + |
| 162 | +#endif /* STK_MEMORY_ALLOCATOR_H_ */ |
0 commit comments