SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk_memory_allocator.h File Reference

Memory allocator front-end with checked API and its weak backend hooks: stk::memory::MemoryAllocator. More...

#include "stk_defs.h"
#include <type_traits>
#include <new>
Include dependency graph for stk_memory_allocator.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  stk::memory::MemoryAllocator
 Memory allocator for allocating dynamic memory. More...
struct  stk::memory::MemoryAllocator::Stats
 Snapshot of the memory allocator's statistics. More...
struct  stk::memory::MemoryAllocator::Weak
 Weak backend hooks of the allocator: the part that the application (or one of the stk_memory_allocator_*.h headers) implements. More...
class  stk::memory::PoolPtr< T, TPool >
 Minimal move-only owning pointer for an object that lives in a memory pool. More...

Namespaces

namespace  stk
 Namespace of STK package.
namespace  stk::memory
 Memory-related primitives: fixed-size block pool, variable-size byte pool, zero-heap pool variants, pool-aware object helpers (PoolPtr) and the general-purpose allocator interface.

Macros

#define STK_MEMORY_PLACEMENT_NEW   (1)
 When defined as 1, placement new C++ operator is enabled for memory::MemoryAllocator and for the NewT/DeleteT helpers of the memory pools.
#define STK_MEMORY_NO_HEAP   (0)
 When defined as 1, nothing in the memory module references memory::MemoryAllocator::Allocate() or memory::MemoryAllocator::Free(): the heap-storage constructors of the pools and the MemoryAllocator typed/aligned helpers are removed from the build. Use it to prove (and enforce) a zero-heap configuration, e.g. for safety audits. Pools remain usable with external storage (including StaticBlockPool and StaticBytePool).
#define STK_MEMORY_HAS_HEAP   (1)
 Derived (do not define): 1 if heap-backed features are compiled in.
#define STK_MEMORY_POOL_CHECKS   (0)
 When 1, memory pools perform expensive diagnostics: O(n) double-free detection, payload fill patterns (0xCD on allocation, 0xDD on free) and block-start validation. Defaults to 1 if _DEBUG or DEBUG is defined, otherwise 0. Because those macros are not reliably defined by embedded toolchains (e.g. -Og), define this one explicitly in your build system to control the behavior.
#define STK_MEMORY_OVERRIDE_NEW_DELETE   (0)
 When defined as 1, the global C++ operator new / new[] / delete / delete[] (all standard variants: throwing, std::nothrow, sized, and the C++17 over-aligned ones) are replaced with versions that use MemoryAllocator::Allocate() / Free() (/ AllocateAligned() / FreeAligned()), so plain new, delete, std::string, std::vector, std::make_unique etc. draw from STK's allocator. Disabled by default.
#define STK_MIN_ALIGNMENT   (stk::Max<size_t>(alignof(std::max_align_t), STK_STACK_MEMORY_ALIGN))
 Minimum alignment (bytes) guaranteed for pointers returned by Allocate().

Detailed Description

Memory allocator front-end with checked API and its weak backend hooks: stk::memory::MemoryAllocator.

Definition in file stk_memory_allocator.h.

Macro Definition Documentation

◆ STK_MEMORY_HAS_HEAP

#define STK_MEMORY_HAS_HEAP   (1)

Derived (do not define): 1 if heap-backed features are compiled in.

Definition at line 40 of file stk_memory_allocator.h.

◆ STK_MEMORY_NO_HEAP

#define STK_MEMORY_NO_HEAP   (0)

When defined as 1, nothing in the memory module references memory::MemoryAllocator::Allocate() or memory::MemoryAllocator::Free(): the heap-storage constructors of the pools and the MemoryAllocator typed/aligned helpers are removed from the build. Use it to prove (and enforce) a zero-heap configuration, e.g. for safety audits. Pools remain usable with external storage (including StaticBlockPool and StaticBytePool).

Note
Independent from STK_MEMORY_PLACEMENT_NEW, which only controls availability of placement new.

Definition at line 33 of file stk_memory_allocator.h.

◆ STK_MEMORY_OVERRIDE_NEW_DELETE

#define STK_MEMORY_OVERRIDE_NEW_DELETE   (0)

When defined as 1, the global C++ operator new / new[] / delete / delete[] (all standard variants: throwing, std::nothrow, sized, and the C++17 over-aligned ones) are replaced with versions that use MemoryAllocator::Allocate() / Free() (/ AllocateAligned() / FreeAligned()), so plain new, delete, std::string, std::vector, std::make_unique etc. draw from STK's allocator. Disabled by default.

Behavior follows the C++ standard where the platform allows it:

  • new(0) returns a unique non-null pointer;
  • on failure the installed std::new_handler is called and the allocation retried until it succeeds or there is no handler;
  • then throwing new throws std::bad_alloc, or - when exceptions are disabled (typical for embedded) - invokes the no-return hook STK_MEMORY_NEW_OOM_ACTION() (default std::terminate(), same as libstdc++); the std::nothrow forms return nullptr.
    Note
    The replacement functions are emitted weak in every translation unit that includes this header with the macro enabled (the standard forbids inline replacements), so it is safe to enable the macro in the build system. A strong definition of any of these operators elsewhere in the program takes precedence.
    Subject to the MemoryAllocator contract (thread-safety, no ISR use unless your implementation allows it). The backend MemoryAllocator::Weak::Allocate() must not itself use new (infinite recursion). Requires heap support (STK_MEMORY_NO_HEAP must be 0).

Definition at line 83 of file stk_memory_allocator.h.

◆ STK_MEMORY_PLACEMENT_NEW

#define STK_MEMORY_PLACEMENT_NEW   (1)

When defined as 1, placement new C++ operator is enabled for memory::MemoryAllocator and for the NewT/DeleteT helpers of the memory pools.

See also
memory::MemoryAllocator::AllocateOneT, memory::MemoryAllocator::AllocateArrayT

Definition at line 21 of file stk_memory_allocator.h.

◆ STK_MEMORY_POOL_CHECKS

#define STK_MEMORY_POOL_CHECKS   (0)

When 1, memory pools perform expensive diagnostics: O(n) double-free detection, payload fill patterns (0xCD on allocation, 0xDD on free) and block-start validation. Defaults to 1 if _DEBUG or DEBUG is defined, otherwise 0. Because those macros are not reliably defined by embedded toolchains (e.g. -Og), define this one explicitly in your build system to control the behavior.

Definition at line 56 of file stk_memory_allocator.h.

◆ STK_MIN_ALIGNMENT

#define STK_MIN_ALIGNMENT   (stk::Max<size_t>(alignof(std::max_align_t), STK_STACK_MEMORY_ALIGN))

Minimum alignment (bytes) guaranteed for pointers returned by Allocate().

Defaults to the larger of the toolchain's fundamental alignment (alignof(std::max_align_t)) and the platform stack alignment (STK_STACK_MEMORY_ALIGN, 16 on RISC-V). Can be overridden in stk_config.h when the underlying allocator guarantees more. Overriding to a smaller value is rejected at compile time.

Definition at line 183 of file stk_memory_allocator.h.