Variable-size (first-fit) allocator with block coalescing and proper task-blocking semantics. More...

#include <stk_memory_bytepool.h>

Inheritance diagram for stk::memory::BytePool:

Collaboration diagram for stk::memory::BytePool:

Classes
struct	BlockHeader
	Header preceding every block (free or used) inside the pool area. More...

Public Member Functions
	BytePool (uint8_t storage, size_t storage_size, const char name=nullptr)
	Construct a pool backed by caller-supplied (external) storage.
	BytePool (size_t storage_size, const char *name=nullptr)
	Construct a pool with heap-allocated storage.
STK_VIRT_DTOR	~BytePool ()
	Destructor.
EWaitResult	TimedAllocEx (void **block, size_t size, Timeout timeout_ticks=WAIT_INFINITE)
	Allocate a block, preserving the full wait outcome.
void *	TimedAlloc (size_t size, Timeout timeout_ticks=WAIT_INFINITE)
	Allocate a block, blocking until memory becomes available or the timeout expires.
template<typename T>
T *	TimedAllocT (Timeout timeout_ticks=WAIT_INFINITE)
	Allocate one typed block, blocking until memory becomes available or the timeout expires.
void *	Alloc (size_t size)
	Allocate a block, blocking indefinitely until memory is available.
template<typename T>
T *	AllocT ()
	Allocate one typed block, blocking indefinitely until memory is available.
void *	TryAlloc (size_t size)
	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.
void	GetInfo (size_t &available, size_t &largest, size_t &fragments) const
	Collect pool statistics.
bool	IsStorageValid () const
	Verify that the backing storage is valid and the pool is ready for use.
size_t	GetSize () const
	Get the total size of the managed (aligned) area in bytes, headers included.
size_t	GetMaxRequest () const
	Get the largest request that can ever succeed on this pool.
void	SetTraceName (const char *name)
	Set name.
const char *	GetTraceName () const
	Get name.

Static Public Member Functions
static constexpr size_t	AlignSize (size_t raw_size)
	Round a size up to the nearest multiple of the block alignment (8 bytes).
static constexpr size_t	RequiredSize (size_t payload_size)
	Compute the pool space consumed by a single allocation of payload_size bytes.

Static Public Attributes
static const size_t	HEADER_SIZE = 8U
	Size of the per-block header in bytes.

Private Member Functions
	STK_NONCOPYABLE_CLASS (BytePool)
void	Init ()
	Align the area and create the initial single free block.
bool	IsSane (const BlockHeader *h) const
	Check that the header h (which must be inside the pool) looks intact.
void	Coalesce (BlockHeader *h)
	Merge h (a free block) with the free blocks that directly follow it.
void *	FindFree (size_t need)
	Find (and claim) the first free block that can hold need bytes.
bool	IsBlockStart (const BlockHeader *h) const
	Check that h is the header of an existing block (walks the list from the start).

Static Private Member Functions
static BlockHeader *	Next (const BlockHeader *h)
	Get the header of the block that follows h.
static void	AccountRun (size_t run, size_t &available, size_t &largest, size_t &fragments)
	Add one free run of run bytes (headers included) to the statistics.

Private Attributes
uint8_t *	m_storage
	raw storage as supplied or allocated (before alignment)
BlockHeader *	m_first
	first block header (aligned), nullptr if the pool is invalid
BlockHeader *	m_end
	one past the last block (aligned), nullptr if the pool is invalid
sync::ConditionVariable	m_cv
	signalled by Free() to wake tasks blocked in TimedAlloc()
size_t	m_storage_size
	size of the raw storage in bytes
bool	m_storage_owned
	true -> storage is heap-allocated; free in destructor

Static Private Attributes
static const size_t	BLOCK_ALIGN = 8U
	Payload alignment and block size granularity in bytes.
static const size_t	MIN_BLOCK_SIZE = (HEADER_SIZE + BLOCK_ALIGN)
	Smallest block: a header plus the minimum payload (`BLOCK_ALIGN`).
static const size_t	POOL_SIZE_MAX = static_cast<size_t>(0xFFFFFFF8UL)
	Largest managed area: block sizes are stored as 32-bit values.
static const uint32_t	STATE_FREE = 0x46524545UL
	"FREE"
static const uint32_t	STATE_USED = 0x55534544UL
	"USED"
static const uint32_t	STATE_NONE = 0x00000000UL
	stale header absorbed by a merge

Detailed Description

Variable-size (first-fit) allocator with block coalescing and proper task-blocking semantics.

BytePool manages a single contiguous memory area and hands out blocks of arbitrary size from it. It is the counterpart of BlockMemoryPool for workloads where allocation sizes vary (message payloads, strings, protocol frames), at the price of a non-constant allocation time and the possibility of fragmentation.

The pool keeps an implicit block list inside the storage area. Every block (free or used) is preceded by an 8-byte header holding the total block size and a state marker. Blocks are laid out back to back, so the next block is always found at header + size and no separate metadata is required.

Memory layout (pool storage, contiguous):

[ hdr | payload ][ hdr | payload (free) ][ hdr | payload ] ...
^                                                          ^
m_first                                                    m_end

Payload pointers returned to the caller are aligned to \c BLOCK_ALIGN (8 bytes).

Allocation policy**: first-fit. While scanning, adjacent free blocks are merged, so a failed scan always leaves the pool fully coalesced. A found block is split when the remainder is large enough to hold a header and a minimum payload.

Freeing**: the block is marked free and merged with the free blocks that follow it. Merging with a free block that precedes it is done lazily by the next scan, so every free run is always reported and allocated as a single block.

Two storage modes** allow fully static (zero-heap) deployments:

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

Blocking semantics**: TimedAlloc() suspends the calling task via a ConditionVariable until enough contiguous memory is released by Free(), or the timeout expires. All waiters are woken on every Free() (their requests differ in size, so waking only one could leave a satisfiable request sleeping); each re-checks its own request and goes back to sleep if it still does not fit. The original timeout is converted to an absolute deadline so repeated wake-ups never extend it.

ISR safety**: TryAlloc() and Free() may be called from an ISR (guarded by a critical section) but, unlike BlockMemoryPool, their execution time is not constant: it is proportional to the number of blocks scanned. Do not use them from time-critical ISRs on pools with many blocks. Alloc() and TimedAlloc() with a non-zero timeout must only be called from task context.

// -----------------------------------------------------------------------
// Example - zero-heap external storage
// -----------------------------------------------------------------------
alignas(8) static uint8_t g_Heap[4096];
 
stk::memory::BytePool g_Pool(g_Heap, sizeof(g_Heap));
 
void Task_Producer() {
    char *msg = static_cast<char *>(g_Pool.TimedAlloc(64, 100)); // wait up to 100 ticks
    if (msg) {
        Format(msg, 64);
        g_Queue.Write(msg, NO_WAIT);
    }
}
 
void Task_Consumer() {
    void *msg = nullptr;
    if (g_Queue.Read(msg)) {
        Send(static_cast<const char *>(msg));
        g_Pool.Free(msg);                   // wakes blocked allocators
    }
}

See also: BlockMemoryPool, sync::ConditionVariable

Note: Blocking alloc paths require the kernel to be compiled with KERNEL_SYNC. TryAlloc() and Free() are always available regardless of kernel mode.; A request larger than GetMaxRequest() can never succeed and fails immediately instead of blocking forever.; Large requests may be starved by a stream of small ones: freed memory is not reserved for the longest-waiting task.

Definition at line 105 of file stk_memory_bytepool.h.

Constructor & Destructor Documentation

◆ BytePool() [1/2]

stk::memory::BytePool::BytePool	(	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. A misaligned start address is corrected internally (the unaligned head and tail bytes are not used).

Parameters

[in]	storage	Pointer to a caller-owned byte buffer. Should be aligned to `BLOCK_ALIGN` (8 bytes) to avoid wasting bytes.
[in]	storage_size	Size of storage in bytes. Must be large enough to hold at least one header and a minimum payload; otherwise `IsStorageValid()` returns `false`.
[in]	name	Optional name forwarded to `ITraceable::SetTraceName()`.

Note: ISR-unsafe (must be called from task or init context).

Definition at line 390 of file stk_memory_bytepool.h.

: m_storage(storage),
  m_first(nullptr),
  m_end(nullptr),
  m_cv(),
  m_storage_size(storage_size),
  m_storage_owned(false)
{
    STK_ASSERT(storage != nullptr);
    STK_ASSERT(storage_size >= MIN_BLOCK_SIZE);
 
#if STK_SYNC_DEBUG_NAMES
    SetTraceName(name);
#else
    STK_UNUSED(name);
#endif
 
    Init();
}

References Init(), m_cv, m_end, m_first, m_storage, m_storage_owned, m_storage_size, MIN_BLOCK_SIZE, 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:

◆ BytePool() [2/2]

stk::memory::BytePool::BytePool	(	size_t	storage_size,
		const char *	name = nullptr )

inlineexplicit

Construct a pool with heap-allocated storage.

Allocates a flat byte buffer of storage_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]	storage_size	Size of the pool area in bytes (headers included).
[in]	name	Optional name forwarded to `ITraceable::SetTraceName()`.

Note: ISR-unsafe.

Definition at line 411 of file stk_memory_bytepool.h.

: m_storage(MemoryAllocator::AllocateArrayT<uint8_t>(storage_size)),
  m_first(nullptr),
  m_end(nullptr),
  m_cv(),
  m_storage_size(storage_size),
  m_storage_owned(true)
{
    STK_ASSERT(storage_size >= MIN_BLOCK_SIZE);
 
#if STK_SYNC_DEBUG_NAMES
    SetTraceName(name);
#else
    STK_UNUSED(name);
#endif
 
    // else: m_first remains nullptr; caller must check IsStorageValid()
    Init();
}

References Init(), m_cv, m_end, m_first, m_storage, m_storage_owned, m_storage_size, MIN_BLOCK_SIZE, stk::ITraceable::SetTraceName(), STK_ASSERT, and STK_UNUSED.

Here is the call graph for this function:

◆ ~BytePool()

stk::memory::BytePool::~BytePool ( )

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 432 of file stk_memory_bytepool.h.

{
    // ConditionVariable destructor asserts the wait list is empty
#if STK_MEMORY_PLACEMENT_NEW
    if (m_storage_owned && (m_storage != nullptr))
    {
        MemoryAllocator::FreeArrayT(m_storage, m_storage_size);
        m_storage = nullptr;
    }
#endif
 
    m_first = nullptr;
    m_end   = nullptr;
}

References stk::memory::MemoryAllocator::FreeArrayT(), m_end, m_first, m_storage, m_storage_owned, and m_storage_size.

Here is the call graph for this function:

Member Function Documentation

◆ AccountRun()

void stk::memory::BytePool::AccountRun	(	size_t	run,
		size_t &	available,
		size_t &	largest,
		size_t &	fragments )

inlinestaticprivate

Add one free run of run bytes (headers included) to the statistics.

Definition at line 802 of file stk_memory_bytepool.h.

{
    if (run != 0U)
    {
        const size_t payload = (run - HEADER_SIZE);
 
        available += payload;
        ++fragments;
 
        if (payload > largest)
        {
            largest = payload;
        }
    }
}

References HEADER_SIZE.

Referenced by GetInfo().

Here is the caller graph for this function:

◆ AlignSize()

constexpr size_t stk::memory::BytePool::AlignSize ( size_t raw_size )

inlinestaticconstexpr

Round a size up to the nearest multiple of the block alignment (8 bytes).

Parameters

[in] raw_size Size in bytes.

Returns: Aligned size in bytes.

Definition at line 157 of file stk_memory_bytepool.h.

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

References BLOCK_ALIGN.

Referenced by Init(), and RequiredSize().

Here is the caller graph for this function:

◆ Alloc()

void * stk::memory::BytePool::Alloc ( size_t size )

inline

Allocate a block, blocking indefinitely until memory is available.

Parameters

[in] size Requested payload size in bytes.

Returns: Pointer to an uninitialized block. Returns nullptr only if the wait was cancelled via IKernel::CancelTaskWait() or the request is invalid (never on timeout). Use TimedAllocEx() to tell these apart.

Warning: ISR-unsafe.

Definition at line 566 of file stk_memory_bytepool.h.

{
    return TimedAlloc(size, WAIT_INFINITE);
}

References TimedAlloc(), and stk::WAIT_INFINITE.

Here is the call graph for this function:

◆ AllocT()

template<typename T>

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

inline

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

Returns: Typed pointer, or nullptr (see Alloc()).

Warning: ISR-unsafe.

Definition at line 572 of file stk_memory_bytepool.h.

{
    return TimedAllocT<T>(WAIT_INFINITE);
}

References TimedAllocT(), and stk::WAIT_INFINITE.

Here is the call graph for this function:

◆ Coalesce()

void stk::memory::BytePool::Coalesce ( BlockHeader * h )

inlineprivate

Merge h (a free block) with the free blocks that directly follow it.

Note: Critical section must be held.

Definition at line 735 of file stk_memory_bytepool.h.

{
    for (BlockHeader *n = Next(h); (n < m_end) && (n->state == STATE_FREE) && IsSane(n); n = Next(h))
    {
        h->size += n->size;
 
        // wipe the absorbed header so it can never be mistaken for a live block
        n->state = STATE_NONE;
        n->size  = 0U;
    }
}

References IsSane(), m_end, Next(), stk::memory::BytePool::BlockHeader::size, STATE_FREE, and STATE_NONE.

Referenced by FindFree(), and Free().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ FindFree()

void * stk::memory::BytePool::FindFree ( size_t need )

inlineprivate

Find (and claim) the first free block that can hold need bytes.

Parameters

[in] need Total block size including header (already aligned).

Returns: Payload pointer, or nullptr if no free block is large enough.

Note: Critical section must be held. Coalesces every free run it passes.

Definition at line 747 of file stk_memory_bytepool.h.

{
    void *result = nullptr;
 
    for (BlockHeader *h = m_first; (h != nullptr) && (h < m_end) && (result == nullptr); h = Next(h))
    {
        if (!IsSane(h))
        {
            STK_ASSERT(false); // pool metadata is corrupted (payload overrun?)
            break;
        }
 
        if (h->state == STATE_FREE)
        {
            Coalesce(h);
 
            if (h->size >= need)
            {
                const size_t rest = (h->size - need);
 
                // split off the tail if it can form a valid block of its own
                if (rest >= MIN_BLOCK_SIZE)
                {
                    BlockHeader *const tail = reinterpret_cast<BlockHeader *>(reinterpret_cast<uint8_t *>(h) + need);
                    tail->size  = static_cast<uint32_t>(rest);
                    tail->state = STATE_FREE;
 
                    h->size = static_cast<uint32_t>(need);
                }
 
                h->state = STATE_USED;
                result   = (h + 1);
            }
        }
    }
 
    return result;
}

References Coalesce(), IsSane(), m_end, m_first, MIN_BLOCK_SIZE, Next(), stk::memory::BytePool::BlockHeader::size, stk::memory::BytePool::BlockHeader::state, STATE_FREE, STATE_USED, and STK_ASSERT.

Referenced by TimedAllocEx().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Free()

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

inline

Return a previously allocated block to the pool.

Marks the block free, merges it with the free blocks that follow it and wakes all tasks blocked inside Alloc() or TimedAlloc() so each can re-check its own request. A woken task may find that the memory was taken by a racing TryAlloc() and continue waiting.

Parameters

[in] ptr Pointer previously returned by an allocation function of this pool instance. Must not be nullptr. Range, alignment and the block state marker are validated; failures trigger an assertion in debug builds and return false in release builds. In debug builds the pointer is additionally verified to be the start of a real block.

Returns: true - block successfully returned. false - ptr is nullptr, does not belong to this pool, is misaligned or the block is not in use (double-free); each case indicates a caller logic error.

Note: ISR-safe (see TryAlloc()).

Warning: Double-free detection relies on the block header and is reliable only until the freed memory is handed out again. Null the pointer after Free().

Definition at line 592 of file stk_memory_bytepool.h.

{
    bool success = false;
 
    if ((ptr != nullptr) && (m_first != nullptr))
    {
        // bounds check: payload must be in range [m_first + HEADER_SIZE, m_end)
        const Word pt = hw::PtrToWord(ptr);
        const Word lo = hw::PtrToWord(m_first);
        const Word hi = hw::PtrToWord(m_end);
 
        if ((pt < (lo + HEADER_SIZE)) || (pt >= hi))
        {
            STK_ASSERT(false); // API contract: ptr does not belong to this pool
        }
        // alignment check: payloads always start on a BLOCK_ALIGN boundary relative to the area start
        else if ((static_cast<size_t>(pt - lo) % BLOCK_ALIGN) != 0U)
        {
            STK_ASSERT(false); // API contract: ptr is misaligned (not a payload start)
        }
        else
        {
            const sync::ScopedCriticalSection cs_;
 
            BlockHeader *const h = (reinterpret_cast<BlockHeader *>(ptr) - 1);
 
            if (h->state != STATE_USED)
            {
                STK_ASSERT(false); // block is not in use - double-free or foreign pointer
            }
            else
            {
                bool is_block = true;
 
            #if defined(_DEBUG) || defined(DEBUG)
                // O(n) validation that ptr really is the start of a block (and not an address
                // inside some payload which happens to look like a header), only active in
                // debug builds - compiles away completely in release
                is_block = IsBlockStart(h);
                STK_ASSERT(is_block);
            #endif
 
                if (is_block && IsSane(h))
                {
                    h->state = STATE_FREE;
 
                    // merge with the free blocks that follow; the ones that precede are merged by the next scan
                    Coalesce(h);
 
                    // memory became available: waiters have different request sizes, so all of
                    // them must re-evaluate (waking only one could leave a satisfiable request asleep)
                    m_cv.NotifyAll_CS();
 
                    success = true;
                }
            }
        }
    }
 
    return success;
}

References BLOCK_ALIGN, Coalesce(), HEADER_SIZE, IsBlockStart(), IsSane(), m_cv, m_end, m_first, stk::hw::PtrToWord(), stk::memory::BytePool::BlockHeader::state, STATE_FREE, STATE_USED, and STK_ASSERT.

Here is the call graph for this function:

◆ GetInfo()

void stk::memory::BytePool::GetInfo	(	size_t &	available,
		size_t &	largest,
		size_t &	fragments ) const

inline

Collect pool statistics.

Walks the block list under a critical section, so the three values are mutually consistent. Adjacent free blocks are counted as one fragment.

Parameters

[out]	available	Total payload bytes that can still be allocated, summed over all free fragments (a single request can use at most largest of them).
[out]	largest	Payload size of the largest free fragment, i.e. the biggest request that would succeed right now.
[out]	fragments	Number of free fragments (1 means no external fragmentation).

Note: ISR-safe, but O(n) in the number of blocks.

Definition at line 658 of file stk_memory_bytepool.h.

{
    available = 0U;
    largest   = 0U;
    fragments = 0U;
 
    if (m_first != nullptr)
    {
        const sync::ScopedCriticalSection cs_;
 
        size_t run = 0U; // length of the current run of adjacent free blocks
 
        for (const BlockHeader *h = m_first; (h < m_end); h = Next(h))
        {
            if (!IsSane(h))
            {
                STK_ASSERT(false); // pool metadata is corrupted (payload overrun?)
                break;
            }
 
            if (h->state == STATE_FREE)
            {
                run += h->size;
            }
            else
            {
                AccountRun(run, available, largest, fragments);
                run = 0U;
            }
        }
 
        AccountRun(run, available, largest, fragments);
    }
}

References AccountRun(), IsSane(), m_end, m_first, Next(), STATE_FREE, and STK_ASSERT.

Referenced by tx_byte_pool_info_get().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetMaxRequest()

size_t stk::memory::BytePool::GetMaxRequest ( ) const

inline

Get the largest request that can ever succeed on this pool.

Equals the payload of a single block spanning the entire pool.

Returns: Maximum payload size in bytes, or 0 if the storage is invalid.

Note: ISR-safe.

Definition at line 302 of file stk_memory_bytepool.h.

    {
        const size_t size = GetSize();
        return ((size >= MIN_BLOCK_SIZE) ? (size - HEADER_SIZE) : 0U);
    }

References GetSize(), HEADER_SIZE, and MIN_BLOCK_SIZE.

Referenced by TimedAllocEx().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetSize()

size_t stk::memory::BytePool::GetSize ( ) const

inline

Get the total size of the managed (aligned) area in bytes, headers included.

Returns: Managed area size in bytes, or 0 if the storage is invalid.

Note: ISR-safe.

Definition at line 291 of file stk_memory_bytepool.h.

    {
        return ((m_first != nullptr) ? static_cast<size_t>(
            reinterpret_cast<const uint8_t *>(m_end) - reinterpret_cast<const uint8_t *>(m_first)) : 0U);
    }

References m_end, and m_first.

Referenced by GetMaxRequest().

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
    }

◆ Init()

void stk::memory::BytePool::Init ( )

inlineprivate

Align the area and create the initial single free block.

Note: Leaves m_first and m_end as nullptr if the area is unusable.

Definition at line 697 of file stk_memory_bytepool.h.

{
    static_assert(sizeof(BlockHeader) == HEADER_SIZE, "BlockHeader must be exactly HEADER_SIZE bytes");
 
    if (m_storage != nullptr)
    {
        // align the area start to BLOCK_ALIGN and trim its size to a multiple of BLOCK_ALIGN
        const size_t addr   = static_cast<size_t>(hw::PtrToWord(m_storage));
        const size_t shift  = (AlignSize(addr) - addr);
        size_t       usable = ((m_storage_size > shift) ? ((m_storage_size - shift) & ~(BLOCK_ALIGN - 1U)) : 0U);
 
        // block sizes are 32-bit: a larger area would be wasted beyond this limit
        if (usable > POOL_SIZE_MAX)
        {
            usable = POOL_SIZE_MAX;
        }
 
        if (usable >= MIN_BLOCK_SIZE)
        {
            m_first = hw::WordToPtr<BlockHeader>(hw::PtrToWord(m_storage) + shift);
            m_end   = hw::WordToPtr<BlockHeader>(hw::PtrToWord(m_first) + usable);
 
            m_first->size  = static_cast<uint32_t>(usable);
            m_first->state = STATE_FREE;
        }
    }
}

References AlignSize(), BLOCK_ALIGN, HEADER_SIZE, m_end, m_first, m_storage, m_storage_size, MIN_BLOCK_SIZE, POOL_SIZE_MAX, stk::hw::PtrToWord(), STATE_FREE, and stk::hw::WordToPtr().

Referenced by BytePool(), and BytePool().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ IsBlockStart()

bool stk::memory::BytePool::IsBlockStart ( const BlockHeader * h ) const

inlineprivate

Check that h is the header of an existing block (walks the list from the start).

Note: Critical section must be held. O(n), used by debug builds only.

Definition at line 786 of file stk_memory_bytepool.h.

{
    bool found = false;
 
    for (const BlockHeader *b = m_first; (b != nullptr) && (b <= h) && (b < m_end) && IsSane(b); b = Next(b))
    {
        if (b == h)
        {
            found = true;
            break;
        }
    }
 
    return found;
}

References IsSane(), m_end, m_first, and Next().

Referenced by Free().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ IsSane()

bool stk::memory::BytePool::IsSane ( const BlockHeader * h ) const

inlineprivate

Check that the header h (which must be inside the pool) looks intact.

Verifies the state marker, the size granularity and that the block does not extend beyond the pool end. Protects the list walkers from endless loops and out-of-bounds reads if a caller overruns a payload.

Definition at line 725 of file stk_memory_bytepool.h.

{
    const bool state_ok = ((h->state == STATE_FREE) || (h->state == STATE_USED));
 
    return (state_ok &&
            (h->size >= MIN_BLOCK_SIZE) &&
            ((h->size % BLOCK_ALIGN) == 0U) &&
            (static_cast<size_t>(reinterpret_cast<const uint8_t *>(m_end) - reinterpret_cast<const uint8_t *>(h)) >= h->size));
}

References BLOCK_ALIGN, m_end, MIN_BLOCK_SIZE, stk::memory::BytePool::BlockHeader::size, stk::memory::BytePool::BlockHeader::state, STATE_FREE, and STATE_USED.

Referenced by Coalesce(), FindFree(), Free(), GetInfo(), and IsBlockStart().

Here is the caller graph for this function:

◆ IsStorageValid()

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

inline

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

Always true for pools constructed with sufficiently large external storage. For heap-constructed pools, false if the allocation failed. false as well if the supplied area is too small to hold even a single block.

Returns: true if the pool is ready for use.

Note: ISR-safe.

Definition at line 285 of file stk_memory_bytepool.h.

285{ return (m_first != nullptr); }

References m_first.

◆ Next()

BlockHeader * stk::memory::BytePool::Next ( const BlockHeader * h )

inlinestaticprivate

Get the header of the block that follows h.

Note: The result may equal m_end, which must not be dereferenced.

Definition at line 345 of file stk_memory_bytepool.h.

    {
        return reinterpret_cast<BlockHeader *>(const_cast<uint8_t *>(reinterpret_cast<const uint8_t *>(h)) + h->size);
    }

References stk::memory::BytePool::BlockHeader::size.

Referenced by Coalesce(), FindFree(), GetInfo(), and IsBlockStart().

Here is the caller graph for this function:

◆ RequiredSize()

constexpr size_t stk::memory::BytePool::RequiredSize ( size_t payload_size )

inlinestaticconstexpr

Compute the pool space consumed by a single allocation of payload_size bytes.

Equals the aligned payload plus the block header. Use it to size external storage, adding the value for every block that must be alive at the same time:

alignas(8) uint8_t buf[BytePool::RequiredSize(128) * 4 + BytePool::RequiredSize(512)];

stk::memory::BytePool::RequiredSize

static constexpr size_t RequiredSize(size_t payload_size)

Compute the pool space consumed by a single allocation of payload_size bytes.

Definition stk_memory_bytepool.h:171

Parameters

[in] payload_size Requested payload size in bytes.

Returns: Space in bytes taken from the pool.

Definition at line 171 of file stk_memory_bytepool.h.

    {
        return (AlignSize(payload_size) + HEADER_SIZE);
    }

References AlignSize(), and HEADER_SIZE.

Referenced by TimedAllocEx(), and tx_byte_pool_create().

Here is the call graph for this function:

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::BytePool::STK_NONCOPYABLE_CLASS ( BytePool )

private

References BytePool().

Here is the call graph for this function:

◆ TimedAlloc()

void * stk::memory::BytePool::TimedAlloc	(	size_t	size,
		Timeout	timeout_ticks = WAIT_INFINITE )

inline

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

Parameters

[in]	size	Requested payload size in bytes.
[in]	timeout_ticks	Maximum time to wait (ticks). Same semantics as `TimedAllocEx()`.

Returns: Pointer to an uninitialized block of at least size bytes aligned to 8 bytes, or nullptr on timeout, cancellation or invalid arguments.

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 546 of file stk_memory_bytepool.h.

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

References TimedAllocEx(), and stk::WAIT_RESULT_SIGNAL.

Referenced by Alloc(), TimedAllocT(), and TryAlloc().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TimedAllocEx()

EWaitResult stk::memory::BytePool::TimedAllocEx	(	void **	block,
		size_t	size,
		Timeout	timeout_ticks = WAIT_INFINITE )

inline

Allocate a block, preserving the full wait outcome.

Searches for a free block of at least size bytes. If none exists the calling task is suspended via the internal ConditionVariable and re-tries after every Free() until the request is satisfied, the timeout expires or the wait is cancelled. The timeout is a total budget, not per wake-up.

Parameters

[out]	block	Receives the allocated block on `WAIT_RESULT_SIGNAL`, `nullptr` on any other result. Must not be `nullptr`.
[in]	size	Requested payload size in bytes (must be > 0 and <= `GetMaxRequest()`).
[in]	timeout_ticks	Maximum time to wait (ticks). `WAIT_INFINITE` - block indefinitely (default). `NO_WAIT` - fail immediately if no suitable block exists (ISR-safe).

Returns: WAIT_RESULT_SIGNAL - a block was allocated (immediately or after waiting), WAIT_RESULT_TIMEOUT - no suitable block became available before the timeout (or NO_WAIT was passed); a block freed at the very moment the timeout expired is still returned as SIGNAL, WAIT_RESULT_CANCELED - the wait was cancelled via IKernel::CancelTaskWait(), WAIT_RESULT_FAIL - invalid arguments (block is nullptr, size is 0 or exceeds GetMaxRequest(), no valid storage) or the kernel rejected the wait.

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

Definition at line 451 of file stk_memory_bytepool.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
    {
        *block = nullptr;
 
        if (hw::IsInsideISR() && (timeout_ticks != NO_WAIT))
        {
            STK_ASSERT(false); // API contract: ISR callers must pass NO_WAIT / use TryAlloc()
        }
        else if ((size == 0U) || (size > GetMaxRequest()))
        {
            // result is WAIT_RESULT_FAIL: such a request can never succeed, so do not block on it
        }
        else
        {
            sync::ScopedCriticalSection cs_;
 
            // safe from overflow: size <= GetMaxRequest() <= POOL_SIZE_MAX - HEADER_SIZE
            const size_t need = RequiredSize(size);
 
            const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
 
            // capture an absolute deadline once, before entering the wait loop; every Free()
            // wakes all waiters (Mesa-style, not a direct handoff) and a woken task may have
            // to wait again, 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);
 
            void *ptr = FindFree(need); // fast path: a suitable block is already available
            result = WAIT_RESULT_SIGNAL;
 
            while (ptr == nullptr)
            {
                Timeout remaining = timeout_ticks;
 
                if (timeout_ticks == NO_WAIT)
                {
                    result = WAIT_RESULT_TIMEOUT; // no waiting requested (ISR-safe path)
                    break;
                }
 
                if (timed_wait)
                {
                    const Ticks left = (deadline - GetTicks());
                    if (left <= 0)
                    {
                        result = WAIT_RESULT_TIMEOUT; // budget is spent and a scan was just made
                        break;
                    }
                    remaining = static_cast<Timeout>(left);
                }
 
                // 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) && (result != WAIT_RESULT_TIMEOUT))
                {
                    break; // cancellation or kernel failure: report as is
                }
 
                // the lock was re-acquired: re-scan regardless of the wake reason, because the memory
                // may have been released at the very moment the timeout expired (honor it instead of
                // failing), or may have been taken by someone else after the wake-up (wait again)
                ptr = FindFree(need);
                if (ptr != nullptr)
                {
                    result = WAIT_RESULT_SIGNAL;
                }
                else if (result == WAIT_RESULT_TIMEOUT)
                {
                    break;
                }
                else
                {
                    // spurious or stolen wake-up: continue waiting within the remaining budget
                }
            }
 
            *block = ptr;
        }
    }
 
    return result;
}

References FindFree(), GetMaxRequest(), stk::GetTicks(), stk::hw::IsInsideISR(), m_cv, stk::NO_WAIT, RequiredSize(), STK_ASSERT, stk::WAIT_INFINITE, stk::WAIT_RESULT_FAIL, stk::WAIT_RESULT_SIGNAL, and stk::WAIT_RESULT_TIMEOUT.

Referenced by TimedAlloc().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TimedAllocT()

template<typename T>

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

inline

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

Thin typed wrapper around TimedAlloc() for sizeof(T) bytes. The memory is uninitialized; no constructor is run. T must not require alignment above 8 bytes.

Parameters

[in] timeout_ticks Maximum time to wait (ticks).

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

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

Definition at line 559 of file stk_memory_bytepool.h.

{
    STK_ASSERT(alignof(T) <= BLOCK_ALIGN); // API contract: payload is aligned to BLOCK_ALIGN only
 
    return static_cast<T *>(TimedAlloc(sizeof(T), timeout_ticks));
}

References BLOCK_ALIGN, 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::BytePool::TryAlloc ( size_t size )

inline

Non-blocking allocation attempt.

Parameters

[in] size Requested payload size in bytes.

Returns: Pointer to an uninitialized block, or nullptr if no suitable free block exists.

Note: ISR-safe (execution time is proportional to the number of blocks scanned).

Definition at line 577 of file stk_memory_bytepool.h.

{
    return TimedAlloc(size, NO_WAIT);
}

References stk::NO_WAIT, and TimedAlloc().

Here is the call graph for this function:

◆ TryAllocT()

template<typename T>

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

inline

Non-blocking typed allocation attempt.

Returns: Typed pointer, or nullptr if no suitable free block exists.

Note: ISR-safe (see TryAlloc()).

Definition at line 583 of file stk_memory_bytepool.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::BytePool::BLOCK_ALIGN = 8U

staticprivate

Payload alignment and block size granularity in bytes.

Definition at line 322 of file stk_memory_bytepool.h.

Referenced by AlignSize(), Free(), Init(), IsSane(), and TimedAllocT().

◆ HEADER_SIZE

const size_t stk::memory::BytePool::HEADER_SIZE = 8U

static

Size of the per-block header in bytes.

Every allocation consumes HEADER_SIZE bytes of the pool in addition to its (aligned) payload.

Definition at line 112 of file stk_memory_bytepool.h.

Referenced by AccountRun(), Free(), GetMaxRequest(), Init(), and RequiredSize().

◆ m_cv

sync::ConditionVariable stk::memory::BytePool::m_cv

private

signalled by Free() to wake tasks blocked in TimedAlloc()

Definition at line 381 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), Free(), and TimedAllocEx().

◆ m_end

BlockHeader* stk::memory::BytePool::m_end

private

one past the last block (aligned), nullptr if the pool is invalid

Definition at line 380 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), Coalesce(), FindFree(), Free(), GetInfo(), GetSize(), Init(), IsBlockStart(), IsSane(), and ~BytePool().

◆ m_first

BlockHeader* stk::memory::BytePool::m_first

private

first block header (aligned), nullptr if the pool is invalid

Definition at line 379 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), FindFree(), Free(), GetInfo(), GetSize(), Init(), IsBlockStart(), IsStorageValid(), and ~BytePool().

◆ m_storage

uint8_t* stk::memory::BytePool::m_storage

private

raw storage as supplied or allocated (before alignment)

Definition at line 378 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), Init(), and ~BytePool().

◆ m_storage_owned

bool stk::memory::BytePool::m_storage_owned

private

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

Definition at line 383 of file stk_memory_bytepool.h.

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

◆ m_storage_size

size_t stk::memory::BytePool::m_storage_size

private

size of the raw storage in bytes

Definition at line 382 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), Init(), and ~BytePool().

◆ MIN_BLOCK_SIZE

const size_t stk::memory::BytePool::MIN_BLOCK_SIZE = (HEADER_SIZE + BLOCK_ALIGN)

staticprivate

Smallest block: a header plus the minimum payload (BLOCK_ALIGN).

Also the smallest remainder worth splitting off.

Definition at line 327 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), FindFree(), GetMaxRequest(), Init(), and IsSane().

◆ POOL_SIZE_MAX

const size_t stk::memory::BytePool::POOL_SIZE_MAX = static_cast<size_t>(0xFFFFFFF8UL)

staticprivate

Largest managed area: block sizes are stored as 32-bit values.

Definition at line 331 of file stk_memory_bytepool.h.

Referenced by Init().

◆ STATE_FREE

const uint32_t stk::memory::BytePool::STATE_FREE = 0x46524545UL

staticprivate

"FREE"

Definition at line 333 of file stk_memory_bytepool.h.

Referenced by Coalesce(), FindFree(), Free(), GetInfo(), Init(), and IsSane().

◆ STATE_NONE

const uint32_t stk::memory::BytePool::STATE_NONE = 0x00000000UL

staticprivate

stale header absorbed by a merge

Definition at line 335 of file stk_memory_bytepool.h.

Referenced by Coalesce().

◆ STATE_USED

const uint32_t stk::memory::BytePool::STATE_USED = 0x55534544UL

staticprivate

"USED"

Definition at line 334 of file stk_memory_bytepool.h.

Referenced by FindFree(), Free(), and IsSane().

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

stk_memory_bytepool.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BytePool() [1/2]

◆ BytePool() [2/2]

◆ ~BytePool()

Member Function Documentation

◆ AccountRun()

◆ AlignSize()

◆ Alloc()

◆ AllocT()

◆ Coalesce()

◆ FindFree()

◆ Free()

◆ GetInfo()

◆ GetMaxRequest()

◆ GetSize()

◆ GetTraceName()

◆ Init()

◆ IsBlockStart()

◆ IsSane()

◆ IsStorageValid()

◆ Next()

◆ RequiredSize()

◆ SetTraceName()

◆ STK_NONCOPYABLE_CLASS()

◆ TimedAlloc()

◆ TimedAllocEx()

◆ TimedAllocT()

◆ TryAlloc()

◆ TryAllocT()

Member Data Documentation

◆ BLOCK_ALIGN

◆ HEADER_SIZE

◆ m_cv

◆ m_end

◆ m_first

◆ m_storage

◆ m_storage_owned

◆ m_storage_size

◆ MIN_BLOCK_SIZE

◆ POOL_SIZE_MAX

◆ STATE_FREE

◆ STATE_NONE

◆ STATE_USED