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 Namespace Reference

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. More...

Namespaces

namespace  detail

Classes

struct  MemoryAllocator
 Memory allocator for allocating dynamic memory. More...
class  PoolPtr
 Minimal move-only owning pointer for an object that lives in a memory pool. More...
class  BlockMemoryPool
 Fixed-size block allocator with O(1) alloc/free and proper task-blocking semantics. More...
class  StaticBlockPool
 Fixed-size block pool that owns its storage: no heap, no separately declared (and possibly mis-sized or misaligned) buffer, everything is computed at compile time. More...
class  BytePool
 Variable-size (first-fit) allocator with block coalescing and proper task-blocking semantics. More...
class  StaticBytePool
 Variable-size pool that owns its storage: no heap and no separately declared, possibly misaligned buffer. More...

Typedefs

template<typename T, size_t N>
using StaticBlockPoolFor
 Pool of N blocks sized and aligned for objects of type T.

Detailed Description

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.

ISR SAFETY GUIDELINES:

Special care must be taken when calling memory methods from within an Interrupt Service Routine (ISR).

As a general rule, methods that can cause the caller to block or sleep are STRICTLY FORBIDDEN in ISRs.

Primitive ISR Safe Methods
BlockMemoryPool TryAlloc(), TryAllocT(), TimedAlloc(NO_WAIT), TimedAllocT(NO_WAIT), TimedAllocEx(NO_WAIT), Free(), TryNewT(), TimedNewT(NO_WAIT), TryMakeT(), DeleteT(), GetStats(), query methods
BytePool TryAlloc(), TryAllocT(), TimedAlloc(NO_WAIT), TimedAllocT(NO_WAIT), TimedAllocEx(NO_WAIT), Free(), TryNewT(), TimedNewT(NO_WAIT), TryMakeT(), DeleteT(), GetInfo(), GetStats(), query methods
StaticBlockPool, StaticBytePool Same as the pool they derive from (BlockMemoryPool, BytePool)
PoolPtr Get(), Release(), Reset(), operator bool, destructor
MemoryAllocator IsAvailable(); Allocate(), Free(), GetStats() and everything built on them only if the backend (Weak) implementation is ISR safe (the default one is)

NOTE:

  • Query methods: IsStorageValid(), GetCapacity(), GetBlockSize(), GetBlockAlignment(), GetUsedCount(), GetFreeCount(), GetPeakUsedCount(), GetAllocFailCount(), IsFull(), IsEmpty() (BlockMemoryPool) and IsStorageValid(), GetSize(), GetMaxRequest(), GetPeakUsedSize(), GetAllocFailCount(), GetMaxScanLength() (BytePool) are all ISR safe.
  • TimedAlloc, TimedAllocT, TimedAllocEx, TimedNewT: ISR safe only with NO_WAIT, which is equivalent to the corresponding Try method. Any other timeout, WAIT_INFINITE included, suspends the caller on a ConditionVariable and is never ISR safe. Alloc(), AllocT(), NewT() and MakeT() always block.
  • TryNewT(), TimedNewT(NO_WAIT), TryMakeT(), DeleteT(), PoolPtr: ISR safe only if the constructor and destructor of the object are.
  • BlockMemoryPool: Allocation and release take constant time (O(1)) inside a minimal critical section.
  • BytePool: TryAlloc() and Free() are ISR safe but their execution time is proportional to the number of blocks scanned (not constant), and GetInfo() walks the whole pool (O(n)). Avoid them in time-critical ISRs on pools with many blocks; GetMaxScanLength() reports the longest walk (the worst-case time the critical section was held) observed on the real workload. GetStats() is O(1).
  • Constructors and destructors of the pools are never ISR safe (init or task context only). The heap-storage constructors additionally call MemoryAllocator::Allocate().
  • MemoryAllocator: Allocate(), Free() and GetStats() are checked front-end wrappers that forward to the weak backend hooks MemoryAllocator::Weak::Allocate(), Weak::Free() and Weak::GetStats(). STK does not implement the hooks; whether the front-end (and the typed and aligned helpers or the global new and delete override that rely on it) may be called from an ISR is defined by your backend implementation. stk_memory_allocator_default.h, which is not included by this header (it defines the hooks: include it in exactly one translation unit), is ISR safe. stk_memory_allocator_malloc.h follows the same inclusion rule but depends on the C library malloc, so it is ISR safe only if your C library is.
  • Blocking methods rely on the kernel being compiled with KERNEL_SYNC; TryAlloc() and Free() are always available.

WARNING:

  • Calling a blocking method from an ISR is a usage error. In debug build STK_ASSERT will break code execution; in release build the call fails immediately (nullptr or WAIT_RESULT_FAIL is returned, the caller is never suspended), so the allocation is lost.

Typedef Documentation

◆ StaticBlockPoolFor

template<typename T, size_t N>
using stk::memory::StaticBlockPoolFor
Initial value:
StaticBlockPool<sizeof(T), N,
static const size_t ALIGN_DEFAULT
Default block alignment in bytes (see STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT).
Fixed-size block pool that owns its storage: no heap, no separately declared (and possibly mis-sized ...

Pool of N blocks sized and aligned for objects of type T.

Definition at line 1070 of file stk_memory_blockpool.h.