Fixed-size block allocator with O(1) alloc/free and proper task-blocking semantics. More...

#include <stk_memory_blockpool.h>

Inheritance diagram for stk::memory::BlockMemoryPool:

Collaboration diagram for stk::memory::BlockMemoryPool:

Classes
struct	MemoryBlock
	Intrusive free-list node overlaid on the first word of every free block. More...

Public Member Functions
	BlockMemoryPool (size_t capacity, size_t raw_block_size, uint8_t storage, size_t storage_size, const char name=nullptr)
	Construct a pool backed by caller-supplied (external) storage.
	BlockMemoryPool (size_t capacity, size_t raw_block_size, const char *name=nullptr)
	Construct a pool with heap-allocated storage.
STK_VIRT_DTOR	~BlockMemoryPool ()
	Destructor.
void *	TimedAlloc (Timeout timeout_ticks=WAIT_INFINITE)
	Allocate one block, blocking until one becomes available or the timeout expires.
EWaitResult	TimedAllocEx (void **block, Timeout timeout_ticks=WAIT_INFINITE)
	Allocate one block, preserving the full wait outcome.
template<typename T>
T *	TimedAllocT (Timeout timeout_ticks=WAIT_INFINITE)
	Allocate one typed block, blocking until one becomes available or the timeout expires.
void *	Alloc ()
	Allocate one block, blocking indefinitely until one is available.
template<typename T>
T *	AllocT ()
	Allocate one typed block, blocking indefinitely until one is available.
void *	TryAlloc ()
	Non-blocking allocation attempt.
template<typename T>
T *	TryAllocT ()
	Non-blocking typed allocation attempt.
bool	Free (void *ptr)
	Return a previously allocated block to the pool.
bool	IsStorageValid () const
	Verify that the backing storage is valid and the pool is ready for use.
size_t	GetCapacity () const
	Get the total block capacity of the pool.
size_t	GetBlockSize () const
	Get the aligned block size used internally by the allocator.
size_t	GetUsedCount () const
	Get the number of currently allocated (outstanding) blocks.
size_t	GetFreeCount () const
	Get the number of free (available) blocks.
bool	IsFull () const
	Check whether all blocks are currently allocated (pool exhausted).
bool	IsEmpty () const
	Check whether all blocks are free (no outstanding allocations).
void	SetTraceName (const char *name)
	Set name.
const char *	GetTraceName () const
	Get name.

Static Public Member Functions
static constexpr size_t	AlignBlockSize (size_t raw_size)
	Round a raw block size up to the nearest multiple of `BLOCK_ALIGN`.

Static Public Attributes
static const size_t	CAPACITY_MAX = 0xFFFEU
	Max capacity supported (number of blocks).

Private Member Functions
	STK_NONCOPYABLE_CLASS (BlockMemoryPool)
void	BuildFreeList ()
	Initialise the intrusive free-list across `m_storage`.
void *	PopFreeList ()
	Pop the head block from the free-list, increment `m_used_count`, and return it.

Private Attributes
uint8_t *	m_storage
	flat byte array holding all N blocks (owned or external)
MemoryBlock *	m_free_list
	head of the intrusive free-list (nullptr when pool is empty)
sync::ConditionVariable	m_cv
	signalled by Free() to wake one task blocked in TimedAlloc()
size_t	m_block_size
	aligned block size in bytes (>= BLOCK_ALIGN)
size_t	m_capacity
	total number of blocks
size_t	m_used_count
	number of blocks currently allocated (outstanding)
bool	m_storage_owned
	true -> storage is heap-allocated; free in destructor

Static Private Attributes
static const size_t	BLOCK_ALIGN = static_cast<size_t>(sizeof(MemoryBlock))
	Minimum block alignment in bytes: `sizeof(MemoryBlock)`.

Detailed Description

Fixed-size block allocator with O(1) alloc/free and proper task-blocking semantics.

BlockMemoryPool provides a deterministic, fragmentation-free allocator for scenarios where the same block size is repeatedly allocated and released - such as packet buffers, sensor sample records, or task-local state objects.

The pool uses an intrusive singly-linked free-list inside the storage array. When a block is free, its first sizeof(void*) bytes hold a pointer to the next free block; no separate metadata array is needed. Alloc and Free are therefore O(1) with a minimal critical section.

Memory layout (pool storage, contiguous):

[ block_0 | block_1 | ... | block_{n-1} ]
^                                       ^
m_storage                         (m_storage + n * m_block_size)

At construction all blocks are chained: block_i->next = block_{i+1},
last->next = nullptr. m_free_list points to block_0.

Two storage modes** mirror the CMSIS osMemoryPoolAttr_t mp_mem / mp_size fields and allow fully static (zero-heap) deployments:

Mode	Constructor	Frees storage?
External storage	`BlockMemoryPool(cap, blksz, buf, bufsz [, name])`	No - caller
Heap storage	`BlockMemoryPool(cap, blksz [, name])`	Yes - dtor

Blocking semantics**: TimedAlloc() suspends the calling task via a ConditionVariable until Free() returns a block, or the timeout expires. This replaces the spin-yield polling loop that was used in the old CMSIS wrapper, giving up the CPU completely while blocked instead of burning cycles.

ISR safety**: TryAlloc() and Free() are ISR-safe (guarded by a critical section). Alloc() and TimedAlloc() with a non-zero timeout must only be called from task context.

// -----------------------------------------------------------------------
// Example 1 - native STK usage with zero-heap external storage
// -----------------------------------------------------------------------
static const uint32_t PKT_COUNT = 8U;
static const uint32_t PKT_SIZE  = sizeof(Packet);
 
alignas(sizeof(void *)) static uint8_t
    g_PktStorage[PKT_COUNT * stk::memory::BlockMemoryPool::AlignBlockSize(PKT_SIZE)];
 
stk::memory::BlockMemoryPool g_PktPool(PKT_COUNT, PKT_SIZE,
                                       g_PktStorage, sizeof(g_PktStorage));
 
void ISR_Receiver() {
    void *blk = g_PktPool.TryAlloc();       // ISR-safe, non-blocking
    if (blk) {
        FillPacket(static_cast<Packet *>(blk));
        g_ParseQueue.Write(blk, NO_WAIT);
    }
}
 
void Task_Parser() {
    void *blk = nullptr;
    if (g_ParseQueue.Read(blk)) {
        Parse(static_cast<Packet *>(blk));
        g_PktPool.Free(blk);                // O(1), wakes one blocked allocator
    }
}

See also: sync::ConditionVariable, sync::Semaphore, sync::Pipe

Note: Blocking alloc paths require the kernel to be compiled with KERNEL_SYNC. TryAlloc() and Free() are always available regardless of kernel mode.

Definition at line 96 of file stk_memory_blockpool.h.

Constructor & Destructor Documentation

◆ BlockMemoryPool() [1/2]

stk::memory::BlockMemoryPool::BlockMemoryPool	(	size_t	capacity,
		size_t	raw_block_size,
		uint8_t *	storage,
		size_t	storage_size,
		const char *	name = nullptr )

inlineexplicit

Construct a pool backed by caller-supplied (external) storage.

The pool references storage directly without taking ownership. The caller must keep the buffer alive for the entire lifetime of this object. The storage is not freed on destruction.

Parameters

[in]	capacity	Total number of blocks the pool can hold.
[in]	raw_block_size	Requested per-block size in bytes. Rounded up internally to `AlignBlockSize(raw_block_size)`.
[in]	storage	Pointer to a caller-owned byte buffer. Must be aligned to at least `sizeof(void)` and sized to hold at least `capacity` AlignBlockSize(raw_block_size) bytes. Asserted at construction time.
[in]	storage_size	Size of storage in bytes (used for the size assertion).
[in]	name	Optional name forwarded to `ITraceable::SetTraceName()`.

Note: Mirrors the mp_mem / mp_size path in osMemoryPoolNew().; ISR-unsafe (must be called from task or init context).

Definition at line 352 of file stk_memory_blockpool.h.

: m_storage(storage),
  m_free_list(nullptr),
  m_block_size(AlignBlockSize(raw_block_size)),
  m_capacity(capacity),
  m_used_count(0U),
  m_storage_owned(false)
{
    STK_ASSERT(capacity > 0U);
    STK_ASSERT(capacity <= CAPACITY_MAX);
    STK_ASSERT(raw_block_size > 0U);
    STK_ASSERT(storage != nullptr);
 
    // API contract: caller-supplied buffer must be large enough
    STK_ASSERT(storage_size >= (capacity * m_block_size));
 
    // in Release builds we ensure capacity which fits storage size, in Debug build the assertion above will be hit
    if ((capacity * m_block_size) > storage_size)
    {
        m_capacity = storage_size / m_block_size;
    }
 
#if STK_SYNC_DEBUG_NAMES
    SetTraceName(name);
#else
    STK_UNUSED(name);
#endif
 
    BuildFreeList();
}

References AlignBlockSize(), BuildFreeList(), CAPACITY_MAX, m_block_size, m_capacity, m_free_list, m_storage, m_storage_owned, m_used_count, stk::ITraceable::SetTraceName(), STK_ASSERT, and STK_UNUSED.

Referenced by STK_NONCOPYABLE_CLASS().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ BlockMemoryPool() [2/2]

stk::memory::BlockMemoryPool::BlockMemoryPool	(	size_t	capacity,
		size_t	raw_block_size,
		const char *	name = nullptr )

inlineexplicit

Construct a pool with heap-allocated storage.

Allocates a flat byte buffer of capacity * AlignBlockSize(raw_block_size) bytes via MemoryAllocator::AllocateArrayT (non-throwing). When exceptions are disabled (embedded default), check IsStorageValid() immediately after construction to detect allocation failure before first use.

Parameters

[in]	capacity	Total number of blocks.
[in]	raw_block_size	Requested per-block size in bytes.
[in]	name	Optional name forwarded to `ITraceable::SetTraceName()`.

Note: Mirrors the heap-fallback path in osMemoryPoolNew().; ISR-unsafe.

Definition at line 385 of file stk_memory_blockpool.h.

: m_storage(MemoryAllocator::AllocateArrayT<uint8_t>(capacity * AlignBlockSize(raw_block_size))),
  m_free_list(nullptr),
  m_block_size(AlignBlockSize(raw_block_size)),
  m_capacity(capacity),
  m_used_count(0U),
  m_storage_owned(true)
{
    STK_ASSERT(capacity > 0U);
    STK_ASSERT(capacity <= CAPACITY_MAX);
    STK_ASSERT(raw_block_size > 0U);
 
#if STK_SYNC_DEBUG_NAMES
    SetTraceName(name);
#else
    STK_UNUSED(name);
#endif
 
    if (m_storage != nullptr)
    {
        BuildFreeList();
    }
    // else: m_free_list remains nullptr; caller must check IsStorageValid()
}

References AlignBlockSize(), BuildFreeList(), CAPACITY_MAX, m_block_size, m_capacity, m_free_list, m_storage, m_storage_owned, m_used_count, stk::ITraceable::SetTraceName(), STK_ASSERT, and STK_UNUSED.

Here is the call graph for this function:

◆ ~BlockMemoryPool()

stk::memory::BlockMemoryPool::~BlockMemoryPool ( )

inline

Destructor.

Frees heap-allocated storage if m_storage_owned is true. External storage is never touched.

Note: Destroying the pool while tasks are blocked in Alloc() or TimedAlloc() is a logical error (dangling waiters). An assertion is triggered in debug builds inside the ConditionVariable destructor.; MISRA deviation: [STK-DEV-005] Rule 10-3-2.

Definition at line 411 of file stk_memory_blockpool.h.

{
    // ConditionVariable destructor asserts the wait list is empty
#if STK_MEMORY_PLACEMENT_NEW
    if (m_storage_owned)
    {
        MemoryAllocator::FreeArrayT(m_storage, (m_capacity * m_block_size));
        m_storage = nullptr;
    }
#endif
}

References stk::memory::MemoryAllocator::FreeArrayT(), m_block_size, m_capacity, m_storage, and m_storage_owned.

Referenced by tx_block_pool_delete().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ AlignBlockSize()

constexpr size_t stk::memory::BlockMemoryPool::AlignBlockSize ( size_t raw_size )

inlinestaticconstexpr

Round a raw block size up to the nearest multiple of BLOCK_ALIGN.

Enforces a minimum of BLOCK_ALIGN so the free-list link always fits inside every free block without extra metadata.

Parameters

[in] raw_size Requested block size in bytes.

Returns: Aligned block size in bytes (>= BLOCK_ALIGN).

Note: Use this to compute the required external storage buffer size:
uint8_t buf[N * BlockMemoryPool::AlignBlockSize(sizeof(MyType))];

Definition at line 158 of file stk_memory_blockpool.h.

    {
        return Max(BLOCK_ALIGN, (raw_size + (BLOCK_ALIGN - 1U)) & ~(BLOCK_ALIGN - 1U));
    }

References BLOCK_ALIGN, and stk::Max().

Referenced by BlockMemoryPool(), BlockMemoryPool(), MsgBufSlotCount(), osMemoryPoolNew(), stk_blockpool_create_static(), tx_block_pool_create(), xMessageBufferCreateStatic(), xMessageBufferCreateStaticWithCallback(), and xMessageBufferCreateWithCallback().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Alloc()

void * stk::memory::BlockMemoryPool::Alloc ( )

inline

Allocate one block, blocking indefinitely until one is available.

Returns: Pointer to an uninitialized block. Returns nullptr only if the wait was cancelled via IKernel::CancelTaskWait(); never on timeout (there is none). Use TimedAllocEx() if cancellation must be told apart from other failures.

Warning: ISR-unsafe.

Definition at line 514 of file stk_memory_blockpool.h.

{
    return TimedAlloc(WAIT_INFINITE);
}

References TimedAlloc(), and stk::WAIT_INFINITE.

Referenced by stk_blockpool_alloc().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ AllocT()

template<typename T>

T * stk::memory::BlockMemoryPool::AllocT ( )

inline

Allocate one typed block, blocking indefinitely until one is available.

Returns: Typed pointer. Returns nullptr only if the wait was cancelled (see Alloc()).

Warning: ISR-unsafe.

Definition at line 520 of file stk_memory_blockpool.h.

{
    return TimedAllocT<T>(WAIT_INFINITE);
}

References TimedAllocT(), and stk::WAIT_INFINITE.

Here is the call graph for this function:

◆ BuildFreeList()

void stk::memory::BlockMemoryPool::BuildFreeList ( )

inlineprivate

Initialise the intrusive free-list across m_storage.

Links blocks in reverse order so after the loop m_free_list points to block_0 (lowest address), giving ascending allocation order. Each free block stores a pointer to the next free block in its own first sizeof(MemoryBlock) bytes - zero extra metadata.

Definition at line 610 of file stk_memory_blockpool.h.

{
    STK_ASSERT((hw::PtrToWord(m_storage) % BLOCK_ALIGN) == 0U);
 
    m_free_list  = nullptr;
    m_used_count = 0U;
 
    // Link blocks in reverse order so m_free_list ends up pointing at block_0
    // (lowest address), giving ascending allocation order.
    for (size_t i = m_capacity; i-- > 0U; )
    {
        MemoryBlock *const blk = hw::WordToPtr<MemoryBlock>(hw::PtrToWord(m_storage) + (i * m_block_size));
 
        blk->next   = m_free_list;
        m_free_list = blk;
    }
}

References BLOCK_ALIGN, m_block_size, m_capacity, m_free_list, m_storage, m_used_count, stk::memory::BlockMemoryPool::MemoryBlock::next, stk::hw::PtrToWord(), STK_ASSERT, and stk::hw::WordToPtr().

Referenced by BlockMemoryPool(), and BlockMemoryPool().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Free()

bool stk::memory::BlockMemoryPool::Free ( void * ptr )

inline

Return a previously allocated block to the pool.

Pushes the block back onto the free-list head in O(1) and wakes exactly one task blocked inside Alloc() or TimedAlloc(), if any, so it can re-check for a free block. Under contention from TryAlloc() (including from another task or an ISR racing in before the woken task is scheduled), that task may find the block already taken and continue waiting rather than being guaranteed one on this wake.

Parameters

[in] ptr Pointer previously returned by Alloc(), TimedAlloc(), or TryAlloc(). Must not be nullptr and must belong to this pool instance. Bounds and alignment are validated; failures trigger an assertion in debug builds and return false in release builds.

Returns: true - block successfully returned. false - ptr is nullptr, out of range, or misaligned; each case indicates a caller logic error.

Note: ISR-safe.

Warning: Double-free is not detected and will silently corrupt the free-list. Null the pointer after Free() to prevent this.

Definition at line 540 of file stk_memory_blockpool.h.

{
    bool success = false;
 
    if (ptr != nullptr)
    {
        // bounds check: ptr must be in range [m_storage, m_storage + capacity * block_size)
        const Word pt = hw::PtrToWord(ptr);
        const Word lo = hw::PtrToWord(m_storage);
        const Word hi = lo + (m_capacity * m_block_size);
 
        if ((pt < lo) || (pt >= hi))
        {
            STK_ASSERT(false); // API contract: ptr does not belong to this pool
        }
        // alignment check: ptr must be at the start of a block boundary
        else if ((static_cast<size_t>(pt - lo) % m_block_size) != 0U)
        {
            STK_ASSERT(false); // API contract: ptr is misaligned (not a block start)
        }
        else
        {
            const sync::ScopedCriticalSection cs_;
 
            if (m_used_count == 0U)
            {
                STK_ASSERT(false); // pool is already fully free - definite double-free
            }
            else
            {
            #if defined(_DEBUG) || defined(DEBUG)
                bool is_double_free = false;
 
                // O(n) double-free detection: walk the free-list and check if ptr is already on it,
                // only active in debug builds - compiles away completely in release
                for (const MemoryBlock *node = m_free_list; (node != nullptr); node = node->next)
                {
                    if (node == reinterpret_cast<const MemoryBlock *>(ptr))
                    {
                        STK_ASSERT(false); // double-free: ptr is already on the free-list
                        is_double_free = true;
                        break;
                    }
                }
 
                if (!is_double_free)
            #endif
                {
                    // push block onto free-list head (O(1))
                    auto *const blk = reinterpret_cast<MemoryBlock *>(ptr);
                    blk->next       = m_free_list;
                    m_free_list     = blk;
                    m_used_count    = (m_used_count - 1U);
 
                    // wake one blocked allocator - true scheduler wait, no spin-yield
                    m_cv.NotifyOne_CS();
                    
                    success = true;
                }
            }
        }
    }
 
    return success;
}

References m_block_size, m_capacity, m_cv, m_free_list, m_storage, m_used_count, stk::memory::BlockMemoryPool::MemoryBlock::next, stk::hw::PtrToWord(), and STK_ASSERT.

Referenced by stk_blockpool_free(), tx_block_release(), xMessageBufferReceive(), xMessageBufferReceiveFromISR(), xMessageBufferReset(), xMessageBufferResetFromISR(), xMessageBufferSend(), and xMessageBufferSendFromISR().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetBlockSize()

size_t stk::memory::BlockMemoryPool::GetBlockSize ( ) const

inline

Get the aligned block size used internally by the allocator.

Equal to AlignBlockSize(raw_block_size) passed at construction. Always >= BLOCK_ALIGN. Matches osMemoryPoolGetBlockSize().

Returns: Aligned block size in bytes.

Note: ISR-safe.

Definition at line 279 of file stk_memory_blockpool.h.

279{ return m_block_size; }

References m_block_size.

Referenced by osMemoryPoolGetBlockSize(), and stk_blockpool_get_block_size().

Here is the caller graph for this function:

◆ GetCapacity()

size_t stk::memory::BlockMemoryPool::GetCapacity ( ) const

inline

Get the total block capacity of the pool.

Returns: Maximum number of blocks that can be simultaneously allocated. Matches osMemoryPoolGetCapacity().

Note: ISR-safe.

Definition at line 271 of file stk_memory_blockpool.h.

271{ return m_capacity; }

References m_capacity.

Referenced by stk_blockpool_get_capacity(), and tx_block_pool_info_get().

Here is the caller graph for this function:

◆ GetFreeCount()

size_t stk::memory::BlockMemoryPool::GetFreeCount ( ) const

inline

Get the number of free (available) blocks.

Returns: Point-in-time snapshot of GetCapacity() - GetUsedCount(). Matches osMemoryPoolGetSpace().

Note: ISR-safe.

Definition at line 293 of file stk_memory_blockpool.h.

293{ return (m_capacity - m_used_count); }

References m_capacity, and m_used_count.

Referenced by IsFull(), stk_blockpool_get_free_count(), and tx_block_pool_info_get().

Here is the caller graph for this function:

◆ GetTraceName()

const char * stk::ITraceable::GetTraceName ( ) const

inlineinherited

Get name.

Returns: Name string, or NULL if not set or if STK_SYNC_DEBUG_NAMES is 0.

Definition at line 582 of file stk_common.h.

    {
    #if STK_SYNC_DEBUG_NAMES
        return m_trace_name;
    #else
        return nullptr;
    #endif
    }

◆ GetUsedCount()

size_t stk::memory::BlockMemoryPool::GetUsedCount ( ) const

inline

Get the number of currently allocated (outstanding) blocks.

Returns: Point-in-time snapshot. Matches osMemoryPoolGetCount().

Note: May be stale immediately after return in a multi-task environment.; ISR-safe on targets where an aligned size_t read is a single instruction.

Definition at line 286 of file stk_memory_blockpool.h.

286{ return m_used_count; }

References m_used_count.

Referenced by stk_blockpool_get_used_count().

Here is the caller graph for this function:

◆ IsEmpty()

bool stk::memory::BlockMemoryPool::IsEmpty ( ) const

inline

Check whether all blocks are free (no outstanding allocations).

Returns: true if no blocks are currently allocated.

Note: ISR-safe.

Definition at line 305 of file stk_memory_blockpool.h.

305{ return (m_used_count == 0U); }

References m_used_count.

Referenced by stk_blockpool_is_empty().

Here is the caller graph for this function:

◆ IsFull()

bool stk::memory::BlockMemoryPool::IsFull ( ) const

inline

Check whether all blocks are currently allocated (pool exhausted).

Returns: true if no blocks are available for allocation.

Note: ISR-safe.

Definition at line 299 of file stk_memory_blockpool.h.

299{ return (GetFreeCount() == 0U); }

stk::memory::BlockMemoryPool::GetFreeCount

size_t GetFreeCount() const

Get the number of free (available) blocks.

Definition stk_memory_blockpool.h:293

References GetFreeCount().

Referenced by stk_blockpool_is_full().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ IsStorageValid()

bool stk::memory::BlockMemoryPool::IsStorageValid ( ) const

inline

Verify that the backing storage is valid and the pool is ready for use.

Always true for pools constructed with external storage. For heap-constructed pools, false if operator new failed. Must be checked after the heap constructor when operating without exceptions (the typical embedded configuration).

Returns: true if the pool is ready for use.

Note: ISR-safe.

Definition at line 264 of file stk_memory_blockpool.h.

264{ return (m_storage != nullptr); }

References m_storage.

Referenced by osMemoryPoolNew(), stk_blockpool_is_storage_valid(), and xMessageBufferCreate().

Here is the caller graph for this function:

◆ PopFreeList()

void * stk::memory::BlockMemoryPool::PopFreeList ( )

inlineprivate

Pop the head block from the free-list, increment m_used_count, and return it.

Note: Caller must hold a critical section and ensure m_free_list != nullptr.

Definition at line 628 of file stk_memory_blockpool.h.

{
    STK_ASSERT(m_used_count < m_capacity);
 
    MemoryBlock *const blk = m_free_list;
 
    m_free_list  = blk->next;
    m_used_count = (m_used_count + 1U);
 
    return blk;
}

References m_capacity, m_free_list, m_used_count, stk::memory::BlockMemoryPool::MemoryBlock::next, and STK_ASSERT.

Referenced by TimedAllocEx().

Here is the caller graph for this function:

◆ SetTraceName()

void stk::ITraceable::SetTraceName ( const char * name )

inlineinherited

Set name.

Parameters

[in] name Null-terminated string or NULL.

Note: If STK_SYNC_DEBUG_NAMES is 0 then calling this function has no effect.

Definition at line 570 of file stk_common.h.

    {
    #if STK_SYNC_DEBUG_NAMES
        m_trace_name = name;
    #else
        STK_UNUSED(name);
    #endif
    }

References STK_UNUSED.

Referenced by stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BytePool::BytePool(), stk::memory::BytePool::BytePool(), tx_block_pool_create(), tx_event_flags_create(), tx_mutex_create(), tx_queue_create(), and tx_semaphore_create().

Here is the caller graph for this function:

◆ STK_NONCOPYABLE_CLASS()

stk::memory::BlockMemoryPool::STK_NONCOPYABLE_CLASS ( BlockMemoryPool )

private

References BlockMemoryPool().

Here is the call graph for this function:

◆ TimedAlloc()

void * stk::memory::BlockMemoryPool::TimedAlloc ( Timeout timeout_ticks = WAIT_INFINITE )

inline

Allocate one block, blocking until one becomes available or the timeout expires.

If the pool is empty the calling task is suspended via the internal ConditionVariable and woken by the next Free() call. On return the caller owns the block and must eventually return it via Free().

Parameters

[in] timeout_ticks Maximum time to wait (ticks). WAIT_INFINITE - block indefinitely (default). NO_WAIT - return nullptr immediately if pool is empty (identical to TryAlloc(); ISR-safe).

Returns: Pointer to an uninitialized block of at least GetBlockSize() bytes, or nullptr if the timeout expired or the wait was cancelled via IKernel::CancelTaskWait() before a block became available.

Note: Collapses timeout and cancellation. Use TimedAllocEx() to tell them apart.

Warning: ISR-safe only when timeout_ticks = NO_WAIT; ISR-unsafe otherwise.

Definition at line 494 of file stk_memory_blockpool.h.

{
    void *block = nullptr;
 
    if (TimedAllocEx(&block, timeout_ticks) != WAIT_RESULT_SIGNAL)
    {
        block = nullptr;
    }
 
    return block;
}

References TimedAllocEx(), and stk::WAIT_RESULT_SIGNAL.

Referenced by Alloc(), stk_blockpool_timed_alloc(), TimedAllocT(), TryAlloc(), xMessageBufferSend(), and xMessageBufferSendFromISR().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TimedAllocEx()

EWaitResult stk::memory::BlockMemoryPool::TimedAllocEx	(	void **	block,
		Timeout	timeout_ticks = WAIT_INFINITE )

inline

Allocate one block, preserving the full wait outcome.

Identical to TimedAlloc(), except the caller gets the raw EWaitResult so a cancellation (via IKernel::CancelTaskWait()) can be distinguished from a timeout. Mirrors sync::Event::WaitEx().

Parameters

[out]	block	Receives the allocated block on `WAIT_RESULT_SIGNAL`, `nullptr` on any other result. Must not be `nullptr`.
[in]	timeout_ticks	Same as `TimedAlloc()`.

Returns: WAIT_RESULT_SIGNAL - a block was allocated (immediately or after waiting), WAIT_RESULT_TIMEOUT - no block became available before the timeout (or NO_WAIT was passed on an empty pool); a block freed at the very moment the timeout expired is still returned as SIGNAL, WAIT_RESULT_CANCELED - the wait was cancelled, nothing was allocated, WAIT_RESULT_FAIL - invalid arguments or the kernel rejected the wait.

Warning: ISR-safe only when timeout_ticks = NO_WAIT; ISR-unsafe otherwise.

Definition at line 427 of file stk_memory_blockpool.h.

{
    EWaitResult result = WAIT_RESULT_FAIL;
 
    STK_ASSERT(block != nullptr); // API contract: output pointer must be valid
 
    if (block == nullptr)
    {
        // result is WAIT_RESULT_FAIL already, so noop
    }
    else if (hw::IsInsideISR() && (timeout_ticks != NO_WAIT))
    {
        STK_ASSERT(false); // API contract: ISR callers must pass NO_WAIT / use TryAlloc()
        *block = nullptr;
    }
    else
    {
        sync::ScopedCriticalSection cs_;
 
        const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
 
        // capture an absolute deadline once, before entering the wait loop; a different
        // allocator (TryAlloc() from another task or an ISR) can steal the just-freed
        // block between NotifyOne_CS() and this task re-acquiring the critical section
        // (Mesa-style wakeup, not a direct handoff - see Free()'s note), so re-passing
        // the original timeout_ticks on each retry would silently restart it;
        // kept as 64-bit Ticks (not truncated to Timeout) so it can't wrap on long uptimes
        const Ticks deadline = (timed_wait ? (GetTicks() + static_cast<Ticks>(timeout_ticks)) : 0);
 
        *block = nullptr;
        result = WAIT_RESULT_SIGNAL; // fast path: a block is already available
 
        while (m_free_list == nullptr)
        {
            Timeout remaining = timeout_ticks;
            if (timed_wait)
            {
                const Ticks left = (deadline - GetTicks());
                remaining = ((left > 0) ? static_cast<Timeout>(left) : NO_WAIT);
            }
 
            // Atomically release the critical section, suspend the task, and
            // re-acquire before returning - no CPU cycles wasted while waiting.
            result = m_cv.WaitEx(cs_, remaining);
            if (result != WAIT_RESULT_SIGNAL)
            {
                break; // timeout, cancellation or kernel failure: report as is
            }
        }
 
        // timeout raced with a Free(): the lock was re-acquired and a block is available,
        // so honor it instead of reporting a failure (cancellation is never overridden)
        if ((result == WAIT_RESULT_TIMEOUT) && (m_free_list != nullptr))
        {
            result = WAIT_RESULT_SIGNAL;
        }
 
        // only allocate a block if the wait ended in a signal (or none was needed)
        if (result == WAIT_RESULT_SIGNAL)
        {
            *block = PopFreeList();
        }
    }
 
    return result;
}

References stk::GetTicks(), stk::hw::IsInsideISR(), m_cv, m_free_list, stk::NO_WAIT, PopFreeList(), STK_ASSERT, stk::WAIT_INFINITE, stk::WAIT_RESULT_FAIL, stk::WAIT_RESULT_SIGNAL, and stk::WAIT_RESULT_TIMEOUT.

Referenced by TimedAlloc(), and tx_block_allocate().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TimedAllocT()

template<typename T>

T * stk::memory::BlockMemoryPool::TimedAllocT ( Timeout timeout_ticks = WAIT_INFINITE )

inline

Allocate one typed block, blocking until one becomes available or the timeout expires.

Thin typed wrapper around TimedAlloc(). Asserts that sizeof(T) fits within the aligned block size chosen at construction.

Parameters

[in] timeout_ticks Maximum time to wait (ticks). Same semantics as TimedAlloc().

Returns: Typed pointer, or nullptr if the timeout expired.

Warning: ISR-safe only when timeout_ticks = NO_WAIT; ISR-unsafe otherwise.

Definition at line 507 of file stk_memory_blockpool.h.

{
    STK_ASSERT(sizeof(T) <= m_block_size); // API contract: block size should larger or equal to object's size
 
    return static_cast<T *>(TimedAlloc(timeout_ticks));
}

References m_block_size, STK_ASSERT, and TimedAlloc().

Referenced by AllocT(), and TryAllocT().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TryAlloc()

void * stk::memory::BlockMemoryPool::TryAlloc ( )

inline

Non-blocking allocation attempt.

Returns a block immediately if the pool is not empty, or nullptr if all blocks are currently allocated. Never suspends the calling task.

Returns: Pointer to an uninitialized block, or nullptr if the pool is empty.

Note: ISR-safe.

Definition at line 525 of file stk_memory_blockpool.h.

{
    return TimedAlloc(NO_WAIT);
}

References stk::NO_WAIT, and TimedAlloc().

Referenced by stk_blockpool_try_alloc().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TryAllocT()

template<typename T>

T * stk::memory::BlockMemoryPool::TryAllocT ( )

inline

Non-blocking typed allocation attempt.

Returns a typed pointer immediately if the pool is not empty, or nullptr if all blocks are currently allocated. Never suspends the calling task.

Returns: Typed pointer, or nullptr if the pool is empty.

Note: ISR-safe.

Definition at line 531 of file stk_memory_blockpool.h.

{
    return TimedAllocT<T>(NO_WAIT);
}

References stk::NO_WAIT, and TimedAllocT().

Here is the call graph for this function:

Member Data Documentation

◆ BLOCK_ALIGN

const size_t stk::memory::BlockMemoryPool::BLOCK_ALIGN = static_cast<size_t>(sizeof(MemoryBlock))

staticprivate

Minimum block alignment in bytes: sizeof(MemoryBlock).

Ensures the intrusive free-list pointer stored in the first word of every free block is naturally aligned on all supported STK targets.

Definition at line 324 of file stk_memory_blockpool.h.

Referenced by AlignBlockSize(), and BuildFreeList().

◆ CAPACITY_MAX

const size_t stk::memory::BlockMemoryPool::CAPACITY_MAX = 0xFFFEU

static

Max capacity supported (number of blocks).

Definition at line 101 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), and tx_block_pool_create().

◆ m_block_size

size_t stk::memory::BlockMemoryPool::m_block_size

private

aligned block size in bytes (>= BLOCK_ALIGN)

Definition at line 342 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), Free(), GetBlockSize(), TimedAllocT(), and ~BlockMemoryPool().

◆ m_capacity

size_t stk::memory::BlockMemoryPool::m_capacity

private

total number of blocks

Definition at line 343 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), Free(), GetCapacity(), GetFreeCount(), PopFreeList(), and ~BlockMemoryPool().

◆ m_cv

sync::ConditionVariable stk::memory::BlockMemoryPool::m_cv

private

signalled by Free() to wake one task blocked in TimedAlloc()

Definition at line 341 of file stk_memory_blockpool.h.

Referenced by Free(), and TimedAllocEx().

◆ m_free_list

MemoryBlock* stk::memory::BlockMemoryPool::m_free_list

private

head of the intrusive free-list (nullptr when pool is empty)

Definition at line 340 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), Free(), PopFreeList(), and TimedAllocEx().

◆ m_storage

uint8_t* stk::memory::BlockMemoryPool::m_storage

private

flat byte array holding all N blocks (owned or external)

Definition at line 339 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), Free(), IsStorageValid(), and ~BlockMemoryPool().

◆ m_storage_owned

bool stk::memory::BlockMemoryPool::m_storage_owned

private

true -> storage is heap-allocated; free in destructor

Definition at line 345 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), and ~BlockMemoryPool().

◆ m_used_count

size_t stk::memory::BlockMemoryPool::m_used_count

private

number of blocks currently allocated (outstanding)

Definition at line 344 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), Free(), GetFreeCount(), GetUsedCount(), IsEmpty(), and PopFreeList().

The documentation for this class was generated from the following file:

stk_memory_blockpool.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BlockMemoryPool() [1/2]

◆ BlockMemoryPool() [2/2]

◆ ~BlockMemoryPool()

Member Function Documentation

◆ AlignBlockSize()

◆ Alloc()

◆ AllocT()

◆ BuildFreeList()

◆ Free()

◆ GetBlockSize()

◆ GetCapacity()

◆ GetFreeCount()

◆ GetTraceName()

◆ GetUsedCount()

◆ IsEmpty()

◆ IsFull()

◆ IsStorageValid()

◆ PopFreeList()

◆ SetTraceName()

◆ STK_NONCOPYABLE_CLASS()

◆ TimedAlloc()

◆ TimedAllocEx()

◆ TimedAllocT()

◆ TryAlloc()

◆ TryAllocT()

Member Data Documentation

◆ BLOCK_ALIGN

◆ CAPACITY_MAX

◆ m_block_size

◆ m_capacity

◆ m_cv

◆ m_free_list

◆ m_storage

◆ m_storage_owned

◆ m_used_count