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::StaticBlockPool< TBlockSize, TCapacity, TAlign > Class Template Reference

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

#include <stk_memory_blockpool.h>

Inheritance diagram for stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >:
Collaboration diagram for stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >:

Public Member Functions

 StaticBlockPool (const char *name=nullptr)
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.
template<typename T, typename... TArgs>
T * TimedNewT (Timeout timeout_ticks, TArgs &&...args)
 Allocate one block and construct a T in it (placement new), waiting up to timeout_ticks.
template<typename T, typename... TArgs>
T * NewT (TArgs &&...args)
 Allocate one block and construct a T in it, blocking indefinitely.
template<typename T, typename... TArgs>
T * TryNewT (TArgs &&...args)
 Non-blocking TimedNewT(). ISR-safe if the constructor of T is.
template<typename T>
void DeleteT (T *ptr)
 Destroy an object created with the NewT() family and return its block to the pool.
template<typename T, typename... TArgs>
PoolPtr< T, BlockMemoryPool > TryMakeT (TArgs &&...args)
 Non-blocking allocate-and-construct returning an owning PoolPtr.
template<typename T, typename... TArgs>
PoolPtr< T, BlockMemoryPool > MakeT (TArgs &&...args)
 Blocking allocate-and-construct returning an owning PoolPtr.
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 GetBlockAlignment () const
 Get the alignment (bytes) of every block.
size_t GetUsedCount () const
 Get the number of currently allocated (outstanding) blocks.
size_t GetFreeCount () const
 Get the number of free (available) blocks.
size_t GetPeakUsedCount () const
 Get the high watermark: the maximum number of blocks that were allocated at the same time.
size_t GetAllocFailCount () const
 Get the number of allocation requests that failed because the pool was exhausted (timeouts and NO_WAIT misses).
MemoryAllocator::Stats GetStats () const
 Get a consistent statistics snapshot in the same format as MemoryAllocator::GetStats().
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, size_t alignment=ALIGN_DEFAULT)
 Round a raw block size up to the nearest multiple of alignment.
static constexpr size_t BitmapBytes (size_t capacity)
 Number of bytes of the "allocated" bitmap for capacity blocks.
static constexpr size_t RequiredStorageSize (size_t capacity, size_t raw_block_size, size_t alignment=ALIGN_DEFAULT)
 Compute the size of the storage buffer required for an external-storage pool.

Static Public Attributes

static const size_t CAPACITY_MAX = 0xFFFEU
 Max capacity supported (number of blocks).
static const size_t ALIGN_DEFAULT = stk::memory::MemoryAllocator::MIN_ALIGNMENT
 Default block alignment in bytes (see STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT).

Private Member Functions

 STK_STATIC_ASSERT_DESC (TBlockSize > 0U, "block size must be greater than zero")
 STK_STATIC_ASSERT_DESC ((TCapacity > 0U) &&(TCapacity<=BlockMemoryPool::CAPACITY_MAX), "invalid capacity")
 STK_STATIC_ASSERT_DESC ((TAlign >=sizeof(void *)) &&((TAlign &(TAlign - 1U))==0U), "alignment must be a power of two not less than sizeof(void *)")
 STK_NONCOPYABLE_CLASS (BlockMemoryPool)
void Setup (size_t raw_block_size, size_t alignment)
 Align storage, trim the capacity to what fits and build the free-list.
void BuildFreeList ()
 Initialise the intrusive free-list across m_blocks.
void * PopFreeList ()
 Pop the head block from the free-list, increment m_used_count, and return it.

Static Private Member Functions

static bool IsValidAlignment (size_t alignment)
 Check an alignment value: a power of two, large enough for the free-list link.
static bool ArgsValid (size_t capacity, size_t raw_block_size, size_t alignment, size_t block_size)
 Check constructor arguments (block size overflow included).
static __stk_forceinline void Fill (void *ptr, size_t size, uint8_t value)
 Fill size bytes at ptr with value (used by diagnostics only).

Private Attributes

uint8_t m_buf [BlockMemoryPool::RequiredStorageSize(TCapacity, TBlockSize, TAlign)]
uint8_t * m_storage
 raw storage as supplied or allocated (before alignment)
uint8_t * m_blocks
 aligned start of block 0, nullptr if the pool is invalid
uint8_t * m_bitmap
 "allocated" bitmap (STK_MEMORY_BLOCKPOOL_BITMAP), otherwise unused
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_storage_size
 size of the raw storage in bytes
size_t m_block_size
 aligned block size in bytes (>= m_block_align)
size_t m_block_align
 alignment of every block in bytes
size_t m_capacity
 total number of blocks (0 if invalid)
size_t m_used_count
 number of blocks currently allocated (outstanding)
MemoryAllocator::Stats m_stats
 live statistics in bytes (blocks * block size): usage, watermark, counters
bool m_storage_owned
 true -> storage is heap-allocated; free in destructor

Static Private Attributes

static const uint8_t FILL_ALLOC = 0xCDU
 payload fill on allocation (STK_MEMORY_POOL_CHECKS)
static const uint8_t FILL_FREE = 0xDDU
 payload fill on free (STK_MEMORY_POOL_CHECKS)

Detailed Description

template<size_t TBlockSize, size_t TCapacity, size_t TAlign = BlockMemoryPool::ALIGN_DEFAULT>
class stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >

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.

Template Parameters
TBlockSizeRequested block size in bytes (e.g. sizeof(Packet)).
TCapacityNumber of blocks.
TAlignBlock alignment in bytes (power of two), default BlockMemoryPool::ALIGN_DEFAULT.
stk::memory::StaticBlockPool<sizeof(Packet), 8> g_PktPool("pkt");
Fixed-size block pool that owns its storage: no heap, no separately declared (and possibly mis-sized ...
Note
Place the object into a specific memory region (CCM, SDRAM, DMA RAM) with your toolchain's section attribute on the variable declaration.

Definition at line 1052 of file stk_memory_blockpool.h.

Constructor & Destructor Documentation

◆ StaticBlockPool()

template<size_t TBlockSize, size_t TCapacity, size_t TAlign = BlockMemoryPool::ALIGN_DEFAULT>
stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >::StaticBlockPool ( const char * name = nullptr)
inlineexplicit

Definition at line 1061 of file stk_memory_blockpool.h.

1062 : BlockMemoryPool(TCapacity, TBlockSize, this->m_buf, sizeof(this->m_buf), name, TAlign)
1063 {}
BlockMemoryPool(size_t capacity, size_t raw_block_size, uint8_t *storage, size_t storage_size, const char *name=nullptr, size_t alignment=ALIGN_DEFAULT)
Construct a pool backed by caller-supplied (external) storage.
uint8_t m_buf[BlockMemoryPool::RequiredStorageSize(TCapacity, TBlockSize, TAlign)]

Member Function Documentation

◆ AlignBlockSize()

constexpr size_t stk::memory::BlockMemoryPool::AlignBlockSize ( size_t raw_size,
size_t alignment = ALIGN_DEFAULT )
inlinestaticconstexprinherited

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

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

Parameters
[in]raw_sizeRequested block size in bytes.
[in]alignmentBlock alignment (power of two), ALIGN_DEFAULT by default.
Returns
Aligned block size in bytes (>= alignment).

Definition at line 203 of file stk_memory_blockpool.h.

204 {
205 return Max(alignment, ((raw_size + (alignment - 1U)) & ~(alignment - 1U)));
206 }
constexpr T Max(T a, T b) noexcept
Compile-time maximum of two values.
Definition stk_defs.h:758

References ALIGN_DEFAULT, and stk::Max().

Referenced by BlockMemoryPool(), BlockMemoryPool(), osMemoryPoolNew(), RequiredStorageSize(), STK_STATIC_ASSERT_DESC(), 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 ( )
inlineinherited

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() or the pool is invalid; never on timeout (there is none). Use TimedAllocEx() if cancellation must be told apart from other failures.
Warning
ISR-unsafe.

Definition at line 739 of file stk_memory_blockpool.h.

740{
742}
static constexpr Timeout WAIT_INFINITE
Timeout value: block indefinitely until the synchronization object is signaled.
Definition stk_common.h:274
void * TimedAlloc(Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, blocking until one becomes available or the timeout expires.

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 ( )
inlineinherited

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

Returns
Typed pointer. Returns nullptr only if the wait was cancelled, the pool is invalid or T does not fit (see Alloc()).
Warning
ISR-unsafe.

Definition at line 745 of file stk_memory_blockpool.h.

746{
748}
T * TimedAllocT(Timeout timeout_ticks=WAIT_INFINITE)
Allocate one typed block, blocking until one becomes available or the timeout expires.

References TimedAllocT(), and stk::WAIT_INFINITE.

Here is the call graph for this function:

◆ ArgsValid()

bool stk::memory::BlockMemoryPool::ArgsValid ( size_t capacity,
size_t raw_block_size,
size_t alignment,
size_t block_size )
inlinestaticprivateinherited

Check constructor arguments (block size overflow included).

Definition at line 467 of file stk_memory_blockpool.h.

468 {
469 return ((capacity > 0U) && (capacity <= CAPACITY_MAX) && (raw_block_size > 0U) &&
470 IsValidAlignment(alignment) && (block_size >= raw_block_size));
471 }
static const size_t CAPACITY_MAX
Max capacity supported (number of blocks).
static bool IsValidAlignment(size_t alignment)
Check an alignment value: a power of two, large enough for the free-list link.

References CAPACITY_MAX, and IsValidAlignment().

Referenced by BlockMemoryPool(), and Setup().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ BitmapBytes()

constexpr size_t stk::memory::BlockMemoryPool::BitmapBytes ( size_t capacity)
inlinestaticconstexprinherited

Number of bytes of the "allocated" bitmap for capacity blocks.

Returns
0 unless STK_MEMORY_BLOCKPOOL_BITMAP is 1.

Definition at line 211 of file stk_memory_blockpool.h.

212 {
213 return ((STK_MEMORY_BLOCKPOOL_BITMAP != 0) ? ((capacity + 7U) / 8U) : 0U);
214 }
#define STK_MEMORY_BLOCKPOOL_BITMAP
When defined as 1, BlockMemoryPool keeps one "allocated" bit per block (capacity/8 bytes,...

References STK_MEMORY_BLOCKPOOL_BITMAP.

Referenced by BlockMemoryPool(), BuildFreeList(), RequiredStorageSize(), Setup(), and STK_STATIC_ASSERT_DESC().

Here is the caller graph for this function:

◆ BuildFreeList()

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

Initialise the intrusive free-list across m_blocks.

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 975 of file stk_memory_blockpool.h.

976{
978
979 m_free_list = nullptr;
980 m_used_count = 0U;
981
982#if STK_MEMORY_BLOCKPOOL_BITMAP
983 for (size_t i = 0U; i < BitmapBytes(m_capacity); ++i)
984 {
985 m_bitmap[i] = 0U;
986 }
987#endif
988
989 // Link blocks in reverse order so m_free_list ends up pointing at block_0
990 // (lowest address), giving ascending allocation order.
991 for (size_t i = m_capacity; i-- > 0U; )
992 {
994
995 blk->next = m_free_list;
996 m_free_list = blk;
997 }
998}
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
static T * WordToPtr(Word value) noexcept
Cast a CPU register-width integer back to a pointer.
Definition stk_arch.h:232
static Word PtrToWord(T *const ptr) noexcept
Cast a pointer to a CPU register-width integer.
Definition stk_arch.h:215
uint8_t * m_bitmap
"allocated" bitmap (STK_MEMORY_BLOCKPOOL_BITMAP), otherwise unused
static constexpr size_t BitmapBytes(size_t capacity)
Number of bytes of the "allocated" bitmap for capacity blocks.
size_t m_capacity
total number of blocks (0 if invalid)
size_t m_block_align
alignment of every block in bytes
uint8_t * m_blocks
aligned start of block 0, nullptr if the pool is invalid
MemoryBlock * m_free_list
head of the intrusive free-list (nullptr when pool is empty)
size_t m_used_count
number of blocks currently allocated (outstanding)
size_t m_block_size
aligned block size in bytes (>= m_block_align)
Intrusive free-list node overlaid on the first word of every free block.

References BitmapBytes(), m_bitmap, m_block_align, m_block_size, m_blocks, m_capacity, m_free_list, m_used_count, stk::memory::BlockMemoryPool::MemoryBlock::next, stk::hw::PtrToWord(), STK_ASSERT, and stk::hw::WordToPtr().

Referenced by Setup().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ DeleteT()

template<typename T>
void stk::memory::BlockMemoryPool::DeleteT ( T * ptr)
inlineinherited

Destroy an object created with the NewT() family and return its block to the pool.

Parameters
[in]ptrObject pointer, nullptr is allowed and results in noop.
Note
ISR-safe if the destructor of T is.

Definition at line 794 of file stk_memory_blockpool.h.

795{
796 if (ptr != nullptr)
797 {
798 ptr->~T();
799
800 const bool freed = Free(ptr);
801 STK_UNUSED(freed);
802 }
803}
#define STK_UNUSED(X)
Explicitly marks a variable as unused to suppress compiler warnings.
Definition stk_defs.h:715
bool Free(void *ptr)
Return a previously allocated block to the pool.

References Free(), and STK_UNUSED.

Here is the call graph for this function:

◆ Fill()

__stk_forceinline void stk::memory::BlockMemoryPool::Fill ( void * ptr,
size_t size,
uint8_t value )
inlinestaticprivateinherited

Fill size bytes at ptr with value (used by diagnostics only).

Definition at line 493 of file stk_memory_blockpool.h.

494 {
495 STK_MEMSET(ptr, value, size);
496 }
void STK_MEMSET(void *const dest, uint8_t value, size_t size)
Implementation of STK_MEMSET.
Definition stk_arch.h:823

References __stk_forceinline, and stk::STK_MEMSET().

Referenced by Free(), and PopFreeList().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ Free()

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

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]ptrPointer 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, misaligned or already free (double-free, release-build detection requires STK_MEMORY_BLOCKPOOL_BITMAP); each case indicates a caller logic error.
Note
ISR-safe.
Warning
Without STK_MEMORY_BLOCKPOOL_BITMAP a double-free is detected only if the pool is already fully free, or in builds with STK_MEMORY_POOL_CHECKS (O(n) free-list walk); otherwise it silently corrupts the free-list. Null the pointer after Free().

Definition at line 823 of file stk_memory_blockpool.h.

824{
825 bool success = false;
826
827 if ((ptr != nullptr) && (m_blocks != nullptr))
828 {
829 // bounds check: ptr must be in range [m_blocks, m_blocks + capacity * block_size)
830 const Word pt = hw::PtrToWord(ptr);
831 const Word lo = hw::PtrToWord(m_blocks);
832 const Word hi = lo + (m_capacity * m_block_size);
833
834 if ((pt < lo) || (pt >= hi))
835 {
836 STK_ASSERT(false); // API contract: ptr does not belong to this pool
837 }
838 // alignment check: ptr must be at the start of a block boundary
839 else if ((static_cast<size_t>(pt - lo) % m_block_size) != 0U)
840 {
841 STK_ASSERT(false); // API contract: ptr is misaligned (not a block start)
842 }
843 else
844 {
845 const hw::CriticalSection::ScopedLock cs_;
846
847 if (m_used_count == 0U)
848 {
849 STK_ASSERT(false); // pool is already fully free - definite double-free
850 }
851 else
852 {
853 bool valid = true;
854
855 #if STK_MEMORY_BLOCKPOOL_BITMAP
856 // O(1) double-free detection that stays active in release builds
857 const size_t index = (static_cast<size_t>(pt - lo) / m_block_size);
858
859 if (!BitmapTest(index))
860 {
861 STK_ASSERT(false); // double-free: block is not marked as allocated
862 valid = false;
863 }
864 else
865 {
866 BitmapClear(index);
867 }
868 #elif STK_MEMORY_POOL_CHECKS
869 // O(n) double-free detection: walk the free-list and check if ptr is already on it,
870 // only active if STK_MEMORY_POOL_CHECKS is enabled - compiles away completely otherwise
871 for (const MemoryBlock *node = m_free_list; (node != nullptr); node = node->next)
872 {
873 if (node == reinterpret_cast<const MemoryBlock *>(ptr))
874 {
875 STK_ASSERT(false); // double-free: ptr is already on the free-list
876 valid = false;
877 break;
878 }
879 }
880 #endif
881
882 if (valid)
883 {
884 #if STK_MEMORY_POOL_CHECKS
885 // poison everything except the link word that is written below
886 Fill(static_cast<uint8_t *>(ptr) + sizeof(MemoryBlock), (m_block_size - sizeof(MemoryBlock)), FILL_FREE);
887 #endif
888
889 // push block onto free-list head (O(1))
890 auto *const blk = reinterpret_cast<MemoryBlock *>(ptr);
891 blk->next = m_free_list;
892 m_free_list = blk;
893 m_used_count = (m_used_count - 1U);
894 m_stats.RecordFree(m_block_size);
895
896 // wake one blocked allocator - true scheduler wait, no spin-yield
897 m_cv.NotifyOne_CS();
898
899 success = true;
900 }
901 }
902 }
903 }
904
905 return success;
906}
uintptr_t Word
Native processor word type.
Definition stk_common.h:206
static __stk_forceinline void Fill(void *ptr, size_t size, uint8_t value)
Fill size bytes at ptr with value (used by diagnostics only).
static const uint8_t FILL_FREE
payload fill on free (STK_MEMORY_POOL_CHECKS)
MemoryAllocator::Stats m_stats
live statistics in bytes (blocks * block size): usage, watermark, counters
sync::ConditionVariable m_cv
signalled by Free() to wake one task blocked in TimedAlloc()
MemoryBlock * next
next free block in the list, or nullptr if this is the last one

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

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetAllocFailCount()

size_t stk::memory::BlockMemoryPool::GetAllocFailCount ( ) const
inlineinherited

Get the number of allocation requests that failed because the pool was exhausted (timeouts and NO_WAIT misses).

Note
ISR-safe on targets where an aligned size_t read is a single instruction.

Definition at line 421 of file stk_memory_blockpool.h.

421{ return m_stats.alloc_fail_count; }

References m_stats.

Referenced by stk_blockpool_get_alloc_fail_count().

Here is the caller graph for this function:

◆ GetBlockAlignment()

size_t stk::memory::BlockMemoryPool::GetBlockAlignment ( ) const
inlineinherited

Get the alignment (bytes) of every block.

Note
ISR-safe.

Definition at line 395 of file stk_memory_blockpool.h.

395{ return m_block_align; }

References m_block_align.

Referenced by stk_blockpool_get_block_alignment().

Here is the caller graph for this function:

◆ GetBlockSize()

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

Get the aligned block size used internally by the allocator.

Equal to AlignBlockSize(raw_block_size, alignment) passed at construction. Matches osMemoryPoolGetBlockSize().

Returns
Aligned block size in bytes.
Note
ISR-safe.

Definition at line 390 of file stk_memory_blockpool.h.

390{ return m_block_size; }

References m_block_size.

Referenced by stk_blockpool_get_block_size().

Here is the caller graph for this function:

◆ GetCapacity()

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

Get the total block capacity of the pool.

Returns
Maximum number of blocks that can be simultaneously allocated. Matches osMemoryPoolGetCapacity(). Can be lower than requested if the supplied buffer was too small (debug builds assert), 0 for an invalid pool.
Note
ISR-safe.

Definition at line 382 of file stk_memory_blockpool.h.

382{ 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
inlineinherited

Get the number of free (available) blocks.

Returns
Point-in-time snapshot of GetCapacity() - GetUsedCount(). Matches osMemoryPoolGetSpace().
Note
ISR-safe.

Definition at line 409 of file stk_memory_blockpool.h.

409{ 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:

◆ GetPeakUsedCount()

size_t stk::memory::BlockMemoryPool::GetPeakUsedCount ( ) const
inlineinherited

Get the high watermark: the maximum number of blocks that were allocated at the same time.

Run your worst-case workload and use this value to size the pool.

Note
ISR-safe on targets where an aligned size_t read is a single instruction.

Definition at line 415 of file stk_memory_blockpool.h.

415{ return ((m_block_size != 0U) ? (m_stats.peak_allocated / m_block_size) : 0U); }

References m_block_size, and m_stats.

Referenced by stk_blockpool_get_peak_used_count().

Here is the caller graph for this function:

◆ GetStats()

MemoryAllocator::Stats stk::memory::BlockMemoryPool::GetStats ( ) const
inlineinherited

Get a consistent statistics snapshot in the same format as MemoryAllocator::GetStats().

All values are in bytes (blocks * block size); counters are in operations.

Returns
Stats structure.
Note
ISR-safe.

Definition at line 912 of file stk_memory_blockpool.h.

913{
914 const hw::CriticalSection::ScopedLock cs_;
915
916 return m_stats;
917}

References m_stats.

Referenced by stk_blockpool_get_stats().

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 629 of file stk_common.h.

630 {
631 #if STK_SYNC_DEBUG_NAMES
632 return m_trace_name;
633 #else
634 return nullptr;
635 #endif
636 }

◆ GetUsedCount()

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

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 402 of file stk_memory_blockpool.h.

402{ 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
inlineinherited

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

Returns
true if no blocks are currently allocated.
Note
ISR-safe.

Definition at line 440 of file stk_memory_blockpool.h.

440{ 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
inlineinherited

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

Returns
true if no blocks are available for allocation.
Note
ISR-safe.

Definition at line 434 of file stk_memory_blockpool.h.

434{ return (GetFreeCount() == 0U); }
size_t GetFreeCount() const
Get the number of free (available) blocks.

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
inlineinherited

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

false if the constructor arguments were invalid, a heap allocation failed, or the supplied buffer is too small to hold a single block. Must be checked after the heap constructor when operating without exceptions (the typical embedded configuration). An invalid pool fails every allocation immediately instead of blocking forever.

Returns
true if the pool is ready for use.
Note
ISR-safe.

Definition at line 374 of file stk_memory_blockpool.h.

374{ return ((m_blocks != nullptr) && (m_capacity != 0U)); }

References m_blocks, and m_capacity.

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

Here is the caller graph for this function:

◆ IsValidAlignment()

bool stk::memory::BlockMemoryPool::IsValidAlignment ( size_t alignment)
inlinestaticprivateinherited

Check an alignment value: a power of two, large enough for the free-list link.

Definition at line 460 of file stk_memory_blockpool.h.

461 {
462 return ((alignment >= sizeof(MemoryBlock)) && ((alignment & (alignment - 1U)) == 0U));
463 }

Referenced by ArgsValid(), and Setup().

Here is the caller graph for this function:

◆ MakeT()

template<typename T, typename... TArgs>
PoolPtr< T, BlockMemoryPool > stk::memory::BlockMemoryPool::MakeT ( TArgs &&... args)
inlineinherited

Blocking allocate-and-construct returning an owning PoolPtr.

Warning
ISR-unsafe.

Definition at line 812 of file stk_memory_blockpool.h.

813{
814 return PoolPtr<T, BlockMemoryPool>(NewT<T>(static_cast<TArgs &&>(args)...), this);
815}
T * NewT(TArgs &&...args)
Allocate one block and construct a T in it, blocking indefinitely.

References NewT().

Here is the call graph for this function:

◆ NewT()

template<typename T, typename... TArgs>
T * stk::memory::BlockMemoryPool::NewT ( TArgs &&... args)
inlineinherited

Allocate one block and construct a T in it, blocking indefinitely.

Warning
ISR-unsafe.

Definition at line 782 of file stk_memory_blockpool.h.

783{
784 return TimedNewT<T>(WAIT_INFINITE, static_cast<TArgs &&>(args)...);
785}
T * TimedNewT(Timeout timeout_ticks, TArgs &&...args)
Allocate one block and construct a T in it (placement new), waiting up to timeout_ticks.

References TimedNewT(), and stk::WAIT_INFINITE.

Referenced by MakeT().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ PopFreeList()

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

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 1000 of file stk_memory_blockpool.h.

1001{
1003
1004 MemoryBlock *const blk = m_free_list;
1005
1006 m_free_list = blk->next;
1007 m_used_count = (m_used_count + 1U);
1008
1009 m_stats.RecordAllocate(m_block_size);
1010
1011#if STK_MEMORY_BLOCKPOOL_BITMAP
1012 BitmapSet(static_cast<size_t>(hw::PtrToWord(blk) - hw::PtrToWord(m_blocks)) / m_block_size);
1013#endif
1014
1015#if STK_MEMORY_POOL_CHECKS
1017#endif
1018
1019 return blk;
1020}
static const uint8_t FILL_ALLOC
payload fill on allocation (STK_MEMORY_POOL_CHECKS)

References Fill(), FILL_ALLOC, m_block_size, m_blocks, m_capacity, m_free_list, m_stats, m_used_count, stk::memory::BlockMemoryPool::MemoryBlock::next, stk::hw::PtrToWord(), and STK_ASSERT.

Referenced by TimedAllocEx().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ RequiredStorageSize()

constexpr size_t stk::memory::BlockMemoryPool::RequiredStorageSize ( size_t capacity,
size_t raw_block_size,
size_t alignment = ALIGN_DEFAULT )
inlinestaticconstexprinherited

Compute the size of the storage buffer required for an external-storage pool.

Accounts for the aligned block size and the optional bitmap. If you cannot guarantee that the buffer is aligned to alignment add alignment - 1.

alignas(8) uint8_t buf[BlockMemoryPool::RequiredStorageSize(N, sizeof(MyType))];
static constexpr size_t RequiredStorageSize(size_t capacity, size_t raw_block_size, size_t alignment=ALIGN_DEFAULT)
Compute the size of the storage buffer required for an external-storage pool.
Parameters
[in]capacityNumber of blocks.
[in]raw_block_sizeRequested per-block size in bytes.
[in]alignmentBlock alignment (power of two), ALIGN_DEFAULT by default.
Returns
Required buffer size in bytes.

Definition at line 227 of file stk_memory_blockpool.h.

228 {
229 return ((capacity * AlignBlockSize(raw_block_size, alignment)) + BitmapBytes(capacity));
230 }
static constexpr size_t AlignBlockSize(size_t raw_size, size_t alignment=ALIGN_DEFAULT)
Round a raw block size up to the nearest multiple of alignment.

References ALIGN_DEFAULT, AlignBlockSize(), and BitmapBytes().

Referenced by stk_blockpool_create_static_ex(), and STK_STATIC_ASSERT_DESC().

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]nameNull-terminated string or NULL.
Note
If STK_SYNC_DEBUG_NAMES is 0 then calling this function has no effect.
Examples
sync/example.cpp.

Definition at line 617 of file stk_common.h.

618 {
619 #if STK_SYNC_DEBUG_NAMES
620 m_trace_name = name;
621 #else
622 STK_UNUSED(name);
623 #endif
624 }

References STK_UNUSED.

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

Here is the caller graph for this function:

◆ Setup()

void stk::memory::BlockMemoryPool::Setup ( size_t raw_block_size,
size_t alignment )
inlineprivateinherited

Align storage, trim the capacity to what fits and build the free-list.

Note
Leaves the pool invalid (m_blocks == nullptr, m_capacity == 0) if anything is wrong.

Definition at line 923 of file stk_memory_blockpool.h.

924{
925 const size_t requested = m_capacity;
926
927 m_blocks = nullptr;
928 m_bitmap = nullptr;
929 m_free_list = nullptr;
930 m_capacity = 0U;
931 m_used_count = 0U;
932
933 STK_ASSERT(requested > 0U);
934 STK_ASSERT(requested <= CAPACITY_MAX);
935 STK_ASSERT(raw_block_size > 0U);
936 STK_ASSERT(IsValidAlignment(alignment));
937
938 if (ArgsValid(requested, raw_block_size, alignment, m_block_size) && (m_storage != nullptr))
939 {
940 // align the start of the first block, the unaligned head bytes are not used
941 const size_t addr = static_cast<size_t>(hw::PtrToWord(m_storage));
942 const size_t shift = (((addr + (alignment - 1U)) & ~(alignment - 1U)) - addr);
943 const size_t usable = ((m_storage_size > shift) ? (m_storage_size - shift) : 0U);
944
945 // trim the capacity to what fits (blocks + optional bitmap); never exceeds usable, so no overflow
946 size_t n = (usable / m_block_size);
947 if (n > requested)
948 {
949 n = requested;
950 }
951
952 while ((n > 0U) && (((n * m_block_size) + BitmapBytes(n)) > usable))
953 {
954 --n;
955 }
956
957 // API contract: caller-supplied buffer must be large enough (after alignment);
958 // in Release builds the capacity is trimmed to fit instead
959 STK_ASSERT(n == requested);
960
961 if (n > 0U)
962 {
963 m_blocks = (m_storage + shift);
964 m_capacity = n;
965 m_bitmap = (m_blocks + (n * m_block_size));
966
968 }
969 }
970
971 // the real capacity is known only now (trimmed to the storage, 0 if the pool is invalid)
973}
uint8_t * m_storage
raw storage as supplied or allocated (before alignment)
size_t m_storage_size
size of the raw storage in bytes
static bool ArgsValid(size_t capacity, size_t raw_block_size, size_t alignment, size_t block_size)
Check constructor arguments (block size overflow included).
void BuildFreeList()
Initialise the intrusive free-list across m_blocks.

References ArgsValid(), BitmapBytes(), BuildFreeList(), CAPACITY_MAX, IsValidAlignment(), m_bitmap, m_block_size, m_blocks, m_capacity, m_free_list, m_stats, m_storage, m_storage_size, m_used_count, stk::hw::PtrToWord(), and STK_ASSERT.

Referenced by BlockMemoryPool(), and BlockMemoryPool().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ STK_NONCOPYABLE_CLASS()

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

References BlockMemoryPool().

Here is the call graph for this function:

◆ STK_STATIC_ASSERT_DESC() [1/3]

template<size_t TBlockSize, size_t TCapacity, size_t TAlign = BlockMemoryPool::ALIGN_DEFAULT>
stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >::STK_STATIC_ASSERT_DESC ( (TAlign >=sizeof(void *)) &&((TAlign &(TAlign - 1U))==0U) ,
"alignment must be a power of two not less than sizeof(void *)"  )
private

◆ STK_STATIC_ASSERT_DESC() [2/3]

template<size_t TBlockSize, size_t TCapacity, size_t TAlign = BlockMemoryPool::ALIGN_DEFAULT>
stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >::STK_STATIC_ASSERT_DESC ( (TCapacity > 0U) &&(TCapacity<=BlockMemoryPool::CAPACITY_MAX) ,
"invalid capacity"  )
private

◆ STK_STATIC_ASSERT_DESC() [3/3]

template<size_t TBlockSize, size_t TCapacity, size_t TAlign = BlockMemoryPool::ALIGN_DEFAULT>
stk::memory::StaticBlockPool< TBlockSize, TCapacity, TAlign >::STK_STATIC_ASSERT_DESC ( TBlockSize ,
0U ,
"block size must be greater than zero"  )
private

◆ TimedAlloc()

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

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_ticksMaximum 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, the pool is invalid (see IsStorageValid()), 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 710 of file stk_memory_blockpool.h.

711{
712 void *block = nullptr;
713
714 if (TimedAllocEx(&block, timeout_ticks) != WAIT_RESULT_SIGNAL)
715 {
716 block = nullptr;
717 }
718
719 return block;
720}
@ WAIT_RESULT_SIGNAL
The wake was caused by a signal.
Definition stk_common.h:140
EWaitResult TimedAllocEx(void **block, Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, preserving the full wait outcome.

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 )
inlineinherited

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]blockReceives the allocated block on WAIT_RESULT_SIGNAL, nullptr on any other result. Must not be nullptr.
[in]timeout_ticksSame 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, invalid pool (no usable storage) or the kernel rejected the wait.
Warning
ISR-safe only when timeout_ticks = NO_WAIT; ISR-unsafe otherwise.

Definition at line 615 of file stk_memory_blockpool.h.

616{
618
619 STK_ASSERT(block != nullptr); // API contract: output pointer must be valid
620
621 if (block == nullptr)
622 {
623 // result is WAIT_RESULT_FAIL already, so noop
624 }
625 else
626 {
627 *block = nullptr;
628
629 if ((timeout_ticks != NO_WAIT) && hw::IsInsideISR())
630 {
631 STK_ASSERT(false); // API contract: ISR callers must pass NO_WAIT / use TryAlloc()
632 }
633 else if (!IsStorageValid())
634 {
635 // result is WAIT_RESULT_FAIL: an invalid pool can never produce a block, so do not block on it
636 }
637 else
638 {
639 sync::ScopedCriticalSection cs_;
640
641 const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
642
643 // capture an absolute deadline once, before entering the wait loop; a different
644 // allocator (TryAlloc() from another task or an ISR) can steal the just-freed
645 // block between NotifyOne_CS() and this task re-acquiring the critical section
646 // (Mesa-style wakeup, not a direct handoff - see Free()'s note), so re-passing
647 // the original timeout_ticks on each retry would silently restart it;
648 // kept as 64-bit Ticks (not truncated to Timeout) so it can't wrap on long uptimes
649 const Ticks deadline = (timed_wait ? (GetTicks() + static_cast<Ticks>(timeout_ticks)) : 0);
650
651 result = WAIT_RESULT_SIGNAL; // fast path: a block is already available
652
653 while (m_free_list == nullptr)
654 {
655 Timeout remaining = timeout_ticks;
656
657 if (timeout_ticks == NO_WAIT)
658 {
659 // no waiting requested (ISR-safe path): never touch the condition variable
660 result = WAIT_RESULT_TIMEOUT;
661 break;
662 }
663
664 if (timed_wait)
665 {
666 const Ticks left = (deadline - GetTicks());
667 if (left <= 0)
668 {
669 result = WAIT_RESULT_TIMEOUT; // budget is spent and the free-list was just checked
670 break;
671 }
672 remaining = static_cast<Timeout>(left);
673 }
674
675 // Atomically release the critical section, suspend the task, and
676 // re-acquire before returning - no CPU cycles wasted while waiting.
677 result = m_cv.WaitEx(cs_, remaining);
678 if (result != WAIT_RESULT_SIGNAL)
679 {
680 break; // timeout, cancellation or kernel failure: report as is
681 }
682 }
683
684 // timeout raced with a Free(): the lock was re-acquired and a block is available,
685 // so honor it instead of reporting a failure (cancellation is never overridden)
686 if ((result == WAIT_RESULT_TIMEOUT) && (m_free_list != nullptr))
687 {
688 result = WAIT_RESULT_SIGNAL;
689 }
690
691 // only allocate a block if the wait ended in a signal (or none was needed)
692 if (result == WAIT_RESULT_SIGNAL)
693 {
694 *block = PopFreeList();
695 }
696 else if (result == WAIT_RESULT_TIMEOUT)
697 {
698 m_stats.RecordAllocFail();
699 }
700 else
701 {
702 // cancellation or kernel failure is not pool exhaustion: not counted
703 }
704 }
705 }
706
707 return result;
708}
static constexpr Timeout NO_WAIT
Timeout value: return immediately if the synchronization object is not yet signaled (non-blocking pol...
Definition stk_common.h:280
EWaitResult
Wait result (see IKernelService::Wait).
Definition stk_common.h:138
@ WAIT_RESULT_FAIL
IKernelService::Wait returned with error without waiting.
Definition stk_common.h:139
@ WAIT_RESULT_TIMEOUT
The wake was caused by a timeout expiry.
Definition stk_common.h:141
int64_t Ticks
Ticks value.
Definition stk_common.h:221
int32_t Timeout
Timeout time (ticks).
Definition stk_common.h:216
static Ticks GetTicks()
Get number of ticks elapsed since kernel start.
Definition stk_helper.h:448
bool IsInsideISR()
Check whether the CPU is currently executing inside a hardware interrupt service routine (ISR).
void * PopFreeList()
Pop the head block from the free-list, increment m_used_count, and return it.
bool IsStorageValid() const
Verify that the backing storage is valid and the pool is ready for use.

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

Referenced by stk_blockpool_timed_alloc_ex(), and TimedAlloc().

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)
inlineinherited

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

Thin typed wrapper around TimedAlloc(). The memory is uninitialized; no constructor is run (see TimedNewT()). Returns nullptr (and asserts in debug builds) if sizeof(T) exceeds the block size or alignof(T) exceeds the pool alignment.

Parameters
[in]timeout_ticksMaximum time to wait (ticks). Same semantics as TimedAlloc().
Returns
Typed pointer, or nullptr if the timeout expired or T does not fit.
Warning
ISR-safe only when timeout_ticks = NO_WAIT; ISR-unsafe otherwise.

Definition at line 723 of file stk_memory_blockpool.h.

724{
725 T *result = nullptr;
726
727 STK_ASSERT(sizeof(T) <= m_block_size); // API contract: block size should be larger or equal to object's size
728 STK_ASSERT(alignof(T) <= m_block_align); // API contract: blocks are aligned to the pool alignment only
729
730 // refuse (rather than hand out an undersized or misaligned block) in release builds too
731 if ((sizeof(T) <= m_block_size) && (alignof(T) <= m_block_align))
732 {
733 result = static_cast<T *>(TimedAlloc(timeout_ticks));
734 }
735
736 return result;
737}

References m_block_align, m_block_size, STK_ASSERT, and TimedAlloc().

Referenced by AllocT(), TimedNewT(), and TryAllocT().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ TimedNewT()

template<typename T, typename... TArgs>
T * stk::memory::BlockMemoryPool::TimedNewT ( Timeout timeout_ticks,
TArgs &&... args )
inlineinherited

Allocate one block and construct a T in it (placement new), waiting up to timeout_ticks.

Parameters
[in]timeout_ticksMaximum time to wait (ticks).
[in]argsConstructor arguments forwarded to T.
Returns
Pointer to the constructed object, or nullptr (see TimedAllocT()).
Note
Pair with DeleteT(). ISR-safe only with NO_WAIT (and only if the constructor is).

Definition at line 768 of file stk_memory_blockpool.h.

769{
770 T *const ptr = TimedAllocT<T>(timeout_ticks);
771
772 if (ptr != nullptr)
773 {
774 auto const obj = new (static_cast<void *>(ptr)) T(static_cast<TArgs &&>(args)...);
775 STK_UNUSED(obj);
776 }
777
778 return ptr;
779}

References STK_UNUSED, and TimedAllocT().

Referenced by NewT(), and TryNewT().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ TryAlloc()

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

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 and never touches the condition variable.

Returns
Pointer to an uninitialized block, or nullptr if the pool is empty.
Note
ISR-safe.

Definition at line 750 of file stk_memory_blockpool.h.

751{
752 return TimedAlloc(NO_WAIT);
753}

References stk::NO_WAIT, and TimedAlloc().

Referenced by stk::pthread::AllocateStack(), and 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 ( )
inlineinherited

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 756 of file stk_memory_blockpool.h.

757{
758 return TimedAllocT<T>(NO_WAIT);
759}

References stk::NO_WAIT, and TimedAllocT().

Here is the call graph for this function:

◆ TryMakeT()

template<typename T, typename... TArgs>
PoolPtr< T, BlockMemoryPool > stk::memory::BlockMemoryPool::TryMakeT ( TArgs &&... args)
inlineinherited

Non-blocking allocate-and-construct returning an owning PoolPtr.

Definition at line 806 of file stk_memory_blockpool.h.

807{
808 return PoolPtr<T, BlockMemoryPool>(TryNewT<T>(static_cast<TArgs &&>(args)...), this);
809}
T * TryNewT(TArgs &&...args)
Non-blocking TimedNewT(). ISR-safe if the constructor of T is.

References TryNewT().

Here is the call graph for this function:

◆ TryNewT()

template<typename T, typename... TArgs>
T * stk::memory::BlockMemoryPool::TryNewT ( TArgs &&... args)
inlineinherited

Non-blocking TimedNewT(). ISR-safe if the constructor of T is.

Definition at line 788 of file stk_memory_blockpool.h.

789{
790 return TimedNewT<T>(NO_WAIT, static_cast<TArgs &&>(args)...);
791}

References stk::NO_WAIT, and TimedNewT().

Referenced by TryMakeT().

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ ALIGN_DEFAULT

const size_t stk::memory::BlockMemoryPool::ALIGN_DEFAULT = stk::memory::MemoryAllocator::MIN_ALIGNMENT
staticinherited

Default block alignment in bytes (see STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT).

Definition at line 141 of file stk_memory_blockpool.h.

Referenced by AlignBlockSize(), RequiredStorageSize(), stk_blockpool_create(), stk_blockpool_create_static(), and STK_STATIC_ASSERT_DESC().

◆ CAPACITY_MAX

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

◆ FILL_ALLOC

const uint8_t stk::memory::BlockMemoryPool::FILL_ALLOC = 0xCDU
staticprivateinherited

payload fill on allocation (STK_MEMORY_POOL_CHECKS)

Definition at line 455 of file stk_memory_blockpool.h.

Referenced by PopFreeList().

◆ FILL_FREE

const uint8_t stk::memory::BlockMemoryPool::FILL_FREE = 0xDDU
staticprivateinherited

payload fill on free (STK_MEMORY_POOL_CHECKS)

Definition at line 456 of file stk_memory_blockpool.h.

Referenced by Free().

◆ m_bitmap

uint8_t* stk::memory::BlockMemoryPool::m_bitmap
privateinherited

"allocated" bitmap (STK_MEMORY_BLOCKPOOL_BITMAP), otherwise unused

Definition at line 506 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), and Setup().

◆ m_block_align

size_t stk::memory::BlockMemoryPool::m_block_align
privateinherited

alignment of every block in bytes

Definition at line 511 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), GetBlockAlignment(), and TimedAllocT().

◆ m_block_size

size_t stk::memory::BlockMemoryPool::m_block_size
privateinherited

aligned block size in bytes (>= m_block_align)

Definition at line 510 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), BuildFreeList(), Free(), GetBlockSize(), GetPeakUsedCount(), PopFreeList(), Setup(), and TimedAllocT().

◆ m_blocks

uint8_t* stk::memory::BlockMemoryPool::m_blocks
privateinherited

aligned start of block 0, nullptr if the pool is invalid

Definition at line 505 of file stk_memory_blockpool.h.

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

◆ m_buf

uint8_t stk::memory::detail::BlockPoolStorage< TBlockSize, TCapacity, TAlign >::m_buf[BlockMemoryPool::RequiredStorageSize(TCapacity, TBlockSize, TAlign)]
inherited

Definition at line 1034 of file stk_memory_blockpool.h.

◆ m_capacity

size_t stk::memory::BlockMemoryPool::m_capacity
privateinherited

total number of blocks (0 if invalid)

Definition at line 512 of file stk_memory_blockpool.h.

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

◆ m_cv

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

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

Definition at line 508 of file stk_memory_blockpool.h.

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

◆ m_free_list

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

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

Definition at line 507 of file stk_memory_blockpool.h.

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

◆ m_stats

MemoryAllocator::Stats stk::memory::BlockMemoryPool::m_stats
privateinherited

live statistics in bytes (blocks * block size): usage, watermark, counters

Definition at line 514 of file stk_memory_blockpool.h.

Referenced by BlockMemoryPool(), BlockMemoryPool(), Free(), GetAllocFailCount(), GetPeakUsedCount(), GetStats(), PopFreeList(), Setup(), and TimedAllocEx().

◆ m_storage

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

raw storage as supplied or allocated (before alignment)

Definition at line 504 of file stk_memory_blockpool.h.

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

◆ m_storage_owned

bool stk::memory::BlockMemoryPool::m_storage_owned
privateinherited

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

Definition at line 515 of file stk_memory_blockpool.h.

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

◆ m_storage_size

size_t stk::memory::BlockMemoryPool::m_storage_size
privateinherited

size of the raw storage in bytes

Definition at line 509 of file stk_memory_blockpool.h.

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

◆ m_used_count

size_t stk::memory::BlockMemoryPool::m_used_count
privateinherited

number of blocks currently allocated (outstanding)

Definition at line 513 of file stk_memory_blockpool.h.

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


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