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::StaticBytePool< TSize > Class Template Reference

Variable-size pool that owns its storage: no heap and no separately declared, possibly misaligned buffer. More...

#include <stk_memory_bytepool.h>

Inheritance diagram for stk::memory::StaticBytePool< TSize >:
Collaboration diagram for stk::memory::StaticBytePool< TSize >:

Public Member Functions

 StaticBytePool (const char *name=nullptr)
 STK_STATIC_ASSERT_DESC ((BLOCK_ALIGN >=4U) &&((BLOCK_ALIGN &(BLOCK_ALIGN - 1U))==0U), "STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT must be a power of two not less than 4")
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.
template<typename T, typename... TArgs>
T * TimedNewT (Timeout timeout_ticks, TArgs &&...args)
 Allocate a block for a T and construct it (placement new), waiting up to timeout_ticks.
template<typename T, typename... TArgs>
T * NewT (TArgs &&...args)
 Allocate a block for a T and construct 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, BytePool > TryMakeT (TArgs &&...args)
 Non-blocking allocate-and-construct returning an owning PoolPtr.
template<typename T, typename... TArgs>
PoolPtr< T, BytePool > MakeT (TArgs &&...args)
 Blocking allocate-and-construct returning an owning PoolPtr.
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.
MemoryAllocator::Stats GetStats () const
 Get a consistent O(1) statistics snapshot in the same format as MemoryAllocator::GetStats().
size_t GetMaxScanLength () const
 Get the length of the longest block-list walk (in blocks) of any allocation so far.
size_t GetAllocFailCount () const
 Get the number of allocation requests that failed because no suitable block was available (timeouts, NO_WAIT misses and requests larger than GetMaxRequest()).
size_t GetPeakUsedSize () const
 Get the high watermark of pool consumption in bytes (headers included).
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 (BLOCK_ALIGN).
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 BLOCK_ALIGN = stk::memory::MemoryAllocator::MIN_ALIGNMENT
 Payload alignment and block size granularity in bytes.
static const size_t HEADER_SIZE = ((BLOCK_ALIGN > 8U) ? BLOCK_ALIGN : 8U)
 Size of the per-block header in bytes: max(8, BLOCK_ALIGN).

Private Member Functions

 STK_STATIC_ASSERT_DESC (TSize >=(BytePool::HEADER_SIZE+BytePool::BLOCK_ALIGN), "pool size must fit at least one block")
 STK_STATIC_ASSERT_DESC (TSize<=(0xFFFFFFFFUL &~(BytePool::BLOCK_ALIGN - 1U)), "pool size exceeds the 32-bit block size limit")
 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.
void * ScanRange (BlockHeader *from, const BlockHeader *stop, size_t need, size_t &scanned)
 Scan the blocks in [from, stop) for a 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 size_t HeapSize (size_t size)
 Size of the heap buffer for size usable bytes: adds slack for aligning the area start when BLOCK_ALIGN is stricter than the guarantee of MemoryAllocator::Allocate(). 0 on overflow.
static BlockHeader * Next (const BlockHeader *h)
 Get the header of the block that follows h.
static uint32_t * GuardOf (const BlockHeader *h)
 Get the guard word location of the used block h (its last 4 bytes).
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 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_buf [TSize]
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
BlockHeader * m_rover
 where the next search starts (STK_MEMORY_BYTEPOOL_NEXT_FIT)
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
MemoryAllocator::Stats m_stats
 live statistics: bytes of used blocks (headers included), watermark, counters
size_t m_max_scan
 longest block-list walk of a single allocation
bool m_storage_owned
 true -> storage is heap-allocated; free in destructor

Static Private Attributes

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>(0xFFFFFFFFUL) & ~(BLOCK_ALIGN - 1U))
 Largest managed area: block sizes are stored as 32-bit values (kept a multiple of BLOCK_ALIGN).
static const size_t GUARD_SIZE = (( (0) != 0) ? 4U : 0U)
 Size of the overrun guard word at the end of every used block (0 = disabled).
static const uint32_t GUARD_MAGIC = 0xA5C3E17BUL
 value of the guard word of a used block
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
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 TSize>
class stk::memory::StaticBytePool< TSize >

Variable-size pool that owns its storage: no heap and no separately declared, possibly misaligned buffer.

Template Parameters
TSizeSize of the managed area in bytes (headers included). Use BytePool::RequiredSize() to compute it from the blocks that must live at the same time.
Variable-size pool that owns its storage: no heap and no separately declared, possibly misaligned buf...
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 1185 of file stk_memory_bytepool.h.

Constructor & Destructor Documentation

◆ StaticBytePool()

template<size_t TSize>
stk::memory::StaticBytePool< TSize >::StaticBytePool ( const char * name = nullptr)
inlineexplicit

Definition at line 1192 of file stk_memory_bytepool.h.

1193 : BytePool(this->m_buf, sizeof(this->m_buf), name)
1194 {}
BytePool(uint8_t *storage, size_t storage_size, const char *name=nullptr)
Construct a pool backed by caller-supplied (external) storage.

References stk::memory::BytePool::BytePool(), and stk::memory::detail::BytePoolStorage< TSize >::m_buf.

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

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

Definition at line 1140 of file stk_memory_bytepool.h.

1141{
1142 if (run != 0U)
1143 {
1144 const size_t payload = (run - HEADER_SIZE);
1145
1146 available += payload;
1147 ++fragments;
1148
1149 if (payload > largest)
1150 {
1151 largest = payload;
1152 }
1153 }
1154}
static const size_t HEADER_SIZE
Size of the per-block header in bytes: max(8, BLOCK_ALIGN).

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

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

Parameters
[in]raw_sizeSize in bytes.
Returns
Aligned size in bytes.

Definition at line 219 of file stk_memory_bytepool.h.

220 {
221 return ((raw_size + (BLOCK_ALIGN - 1U)) & ~(BLOCK_ALIGN - 1U));
222 }
static const size_t BLOCK_ALIGN
Payload alignment and block size granularity in bytes.

References BLOCK_ALIGN.

Referenced by Init(), RequiredSize(), and STK_STATIC_ASSERT_DESC().

Here is the caller graph for this function:

◆ Alloc()

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

Allocate a block, blocking indefinitely until memory is available.

Parameters
[in]sizeRequested 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 757 of file stk_memory_bytepool.h.

758{
759 return TimedAlloc(size, WAIT_INFINITE);
760}
static constexpr Timeout WAIT_INFINITE
Timeout value: block indefinitely until the synchronization object is signaled.
Definition stk_common.h:274
void * TimedAlloc(size_t size, Timeout timeout_ticks=WAIT_INFINITE)
Allocate a block, blocking until memory becomes available or the timeout expires.

References TimedAlloc(), and stk::WAIT_INFINITE.

Referenced by stk_bytepool_alloc().

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

◆ AllocT()

template<typename T>
T * stk::memory::BytePool::AllocT ( )
inlineinherited

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

Returns
Typed pointer, or nullptr (see Alloc()).
Warning
ISR-unsafe.

Definition at line 763 of file stk_memory_bytepool.h.

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

References TimedAllocT(), and stk::WAIT_INFINITE.

Here is the call graph for this function:

◆ Coalesce()

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

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

Note
Critical section must be held.

Definition at line 1020 of file stk_memory_bytepool.h.

1021{
1022 for (BlockHeader *n = Next(h); (n < m_end) && (n->state == STATE_FREE) && IsSane(n); n = Next(h))
1023 {
1024 #if STK_MEMORY_BYTEPOOL_NEXT_FIT
1025 // never leave the rover pointing at a header that is about to disappear
1026 if (m_rover == n)
1027 {
1028 m_rover = h;
1029 }
1030 #endif
1031
1032 h->size += n->size;
1033
1034 // wipe the absorbed header so it can never be mistaken for a live block
1035 n->state = STATE_NONE;
1036 n->size = 0U;
1037 }
1038}
BlockHeader * m_end
one past the last block (aligned), nullptr if the pool is invalid
static const uint32_t STATE_FREE
"FREE"
static const uint32_t STATE_NONE
stale header absorbed by a merge
bool IsSane(const BlockHeader *h) const
Check that the header h (which must be inside the pool) looks intact.
static BlockHeader * Next(const BlockHeader *h)
Get the header of the block that follows h.
BlockHeader * m_rover
where the next search starts (STK_MEMORY_BYTEPOOL_NEXT_FIT)
Header preceding every block (free or used) inside the pool area.

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

Referenced by Free(), and ScanRange().

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

◆ DeleteT()

template<typename T>
void stk::memory::BytePool::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 812 of file stk_memory_bytepool.h.

813{
814 if (ptr != nullptr)
815 {
816 ptr->~T();
817
818 const bool freed = Free(ptr);
819 STK_UNUSED(freed);
820 }
821}
#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::BytePool::Fill ( void * ptr,
size_t size,
uint8_t value )
inlinestaticprivateinherited

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

Definition at line 506 of file stk_memory_bytepool.h.

507 {
508 STK_MEMSET(ptr, value, size);
509 }
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 ScanRange().

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

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

Parameters
[in]needTotal 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 1098 of file stk_memory_bytepool.h.

1099{
1100 size_t scanned = 0U;
1101
1102#if STK_MEMORY_BYTEPOOL_NEXT_FIT
1103 BlockHeader *const start = ((m_rover != nullptr) ? m_rover : m_first);
1104
1105 void *result = ScanRange(start, m_end, need, scanned);
1106
1107 if ((result == nullptr) && (start != m_first))
1108 {
1109 // wrap around: the part before the rover (this also coalesces the free run that precedes it)
1110 result = ScanRange(m_first, start, need, scanned);
1111 }
1112#else
1113 void *const result = ScanRange(m_first, m_end, need, scanned);
1114#endif
1115
1116 if (scanned > m_max_scan)
1117 {
1118 m_max_scan = scanned;
1119 }
1120
1121 return result;
1122}
size_t m_max_scan
longest block-list walk of a single allocation
BlockHeader * m_first
first block header (aligned), nullptr if the pool is invalid
void * ScanRange(BlockHeader *from, const BlockHeader *stop, size_t need, size_t &scanned)
Scan the blocks in [from, stop) for a free block that can hold need bytes.

References m_end, m_first, m_max_scan, m_rover, and ScanRange().

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

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]ptrPointer previously returned by an allocation function of this pool instance. Must not be nullptr. Range, alignment and the block state marker are validated (plus the guard word with STK_MEMORY_BYTEPOOL_GUARD); failures trigger an assertion in debug builds and return false in release builds. With STK_MEMORY_POOL_CHECKS 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, the block is not in use (double-free) or its guard word was overwritten; 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 841 of file stk_memory_bytepool.h.

842{
843 bool success = false;
844
845 if ((ptr != nullptr) && (m_first != nullptr))
846 {
847 // bounds check: payload must be in range [m_first + HEADER_SIZE, m_end)
848 const Word pt = hw::PtrToWord(ptr);
849 const Word lo = hw::PtrToWord(m_first);
850 const Word hi = hw::PtrToWord(m_end);
851
852 if ((pt < (lo + HEADER_SIZE)) || (pt >= hi))
853 {
854 STK_ASSERT(false); // API contract: ptr does not belong to this pool
855 }
856 // alignment check: payloads always start on a BLOCK_ALIGN boundary relative to the area start
857 else if ((static_cast<size_t>(pt - lo) % BLOCK_ALIGN) != 0U)
858 {
859 STK_ASSERT(false); // API contract: ptr is misaligned (not a payload start)
860 }
861 else
862 {
863 const hw::CriticalSection::ScopedLock cs_;
864
865 BlockHeader *const h = (reinterpret_cast<BlockHeader *>(ptr) - 1);
866
867 if (h->state != STATE_USED)
868 {
869 STK_ASSERT(false); // block is not in use - double-free or foreign pointer
870 }
871 else
872 {
873 bool is_block = true;
874
875 #if STK_MEMORY_POOL_CHECKS
876 // O(n) validation that ptr really is the start of a block (and not an address
877 // inside some payload which happens to look like a header), only active if
878 // STK_MEMORY_POOL_CHECKS is enabled - compiles away completely otherwise
879 is_block = IsBlockStart(h);
880 STK_ASSERT(is_block);
881 #endif
882
883 if (is_block && IsSane(h))
884 {
885 bool guard_ok = true;
886
887 #if STK_MEMORY_BYTEPOOL_GUARD
888 // the guard word sits at the very end of the block; if it was overwritten the
889 // caller overran its payload, the following header may be damaged as well: keep
890 // the block (leak it) instead of merging it into a possibly corrupted list
891 guard_ok = (*GuardOf(h) == GUARD_MAGIC);
892 STK_ASSERT(guard_ok);
893 #endif
894
895 if (guard_ok)
896 {
897 const size_t block_size = h->size;
898
899 m_stats.RecordFree(block_size);
900
901 h->state = STATE_FREE;
902
903 #if STK_MEMORY_POOL_CHECKS
904 Fill((h + 1), (block_size - HEADER_SIZE), FILL_FREE);
905 #endif
906
907 // merge with the free blocks that follow; the ones that precede are merged by the next scan
908 Coalesce(h);
909
910 // memory became available: waiters have different request sizes, so all of
911 // them must re-evaluate (waking only one could leave a satisfiable request asleep)
912 m_cv.NotifyAll_CS();
913
914 success = true;
915 }
916 }
917 }
918 }
919 }
920
921 return success;
922}
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
uintptr_t Word
Native processor word type.
Definition stk_common.h:206
static Word PtrToWord(T *const ptr) noexcept
Cast a pointer to a CPU register-width integer.
Definition stk_arch.h:215
MemoryAllocator::Stats m_stats
live statistics: bytes of used blocks (headers included), watermark, counters
static const uint32_t STATE_USED
"USED"
sync::ConditionVariable m_cv
signalled by Free() to wake tasks blocked in TimedAlloc()
bool IsBlockStart(const BlockHeader *h) const
Check that h is the header of an existing block (walks the list from the start).
static const uint32_t GUARD_MAGIC
value of the guard word of a used block
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)
void Coalesce(BlockHeader *h)
Merge h (a free block) with the free blocks that directly follow it.
static uint32_t * GuardOf(const BlockHeader *h)
Get the guard word location of the used block h (its last 4 bytes).

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

Referenced by DeleteT(), stk::memory::MemoryAllocator::Weak::Free(), and stk_bytepool_free().

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

◆ GetAllocFailCount()

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

Get the number of allocation requests that failed because no suitable block was available (timeouts, NO_WAIT misses and requests larger than GetMaxRequest()).

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

Definition at line 401 of file stk_memory_bytepool.h.

401{ return m_stats.alloc_fail_count; }

References m_stats.

Referenced by stk_bytepool_get_alloc_fail_count().

Here is the caller graph for this function:

◆ GetInfo()

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

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]availableTotal payload bytes that can still be allocated, summed over all free fragments (a single request can use at most largest of them).
[out]largestPayload size of the largest free fragment, i.e. the biggest request that would succeed right now (less the guard word with STK_MEMORY_BYTEPOOL_GUARD).
[out]fragmentsNumber of free fragments (1 means no external fragmentation).
Note
ISR-safe, but O(n) in the number of blocks. See GetStats() for an O(1) alternative.

Definition at line 928 of file stk_memory_bytepool.h.

929{
930 available = 0U;
931 largest = 0U;
932 fragments = 0U;
933
934 if (m_first != nullptr)
935 {
936 const hw::CriticalSection::ScopedLock cs_;
937
938 size_t run = 0U; // length of the current run of adjacent free blocks
939
940 for (const BlockHeader *h = m_first; (h < m_end); h = Next(h))
941 {
942 if (!IsSane(h))
943 {
944 STK_ASSERT(false); // pool metadata is corrupted (payload overrun?)
945 break;
946 }
947
948 if (h->state == STATE_FREE)
949 {
950 run += h->size;
951 }
952 else
953 {
954 AccountRun(run, available, largest, fragments);
955 run = 0U;
956 }
957 }
958
959 AccountRun(run, available, largest, fragments);
960 }
961}
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.

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

Referenced by stk_bytepool_get_info().

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

◆ GetMaxRequest()

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

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

Equals the payload of a single block spanning the entire pool (less the guard word with STK_MEMORY_BYTEPOOL_GUARD).

Returns
Maximum payload size in bytes, or 0 if the storage is invalid.
Note
ISR-safe.

Definition at line 433 of file stk_memory_bytepool.h.

434 {
435 const size_t size = GetSize();
436 return ((size >= MIN_BLOCK_SIZE) ? (size - HEADER_SIZE - GUARD_SIZE) : 0U);
437 }
static const size_t MIN_BLOCK_SIZE
Smallest block: a header plus the minimum payload (BLOCK_ALIGN).
size_t GetSize() const
Get the total size of the managed (aligned) area in bytes, headers included.
static const size_t GUARD_SIZE
Size of the overrun guard word at the end of every used block (0 = disabled).

References GetSize(), GUARD_SIZE, HEADER_SIZE, and MIN_BLOCK_SIZE.

Referenced by stk_bytepool_get_max_request(), and TimedAllocEx().

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

◆ GetMaxScanLength()

size_t stk::memory::BytePool::GetMaxScanLength ( ) const
inlineinherited

Get the length of the longest block-list walk (in blocks) of any allocation so far.

The walk is executed inside the critical section, so this is a direct measure of the worst-case time interrupts/scheduling were blocked by the allocator (multiply by the cost of one iteration of your target). Use it to decide whether a time-critical ISR may call TryAlloc().

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

Definition at line 395 of file stk_memory_bytepool.h.

395{ return m_max_scan; }

References m_max_scan.

Referenced by stk_bytepool_get_max_scan_length().

Here is the caller graph for this function:

◆ GetPeakUsedSize()

size_t stk::memory::BytePool::GetPeakUsedSize ( ) const
inlineinherited

Get the high watermark of pool consumption in bytes (headers included).

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

Definition at line 406 of file stk_memory_bytepool.h.

406{ return m_stats.peak_allocated; }

References m_stats.

Referenced by stk_bytepool_get_peak_used_size().

Here is the caller graph for this function:

◆ GetSize()

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

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

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

References m_end, and m_first.

Referenced by GetMaxRequest(), and stk_bytepool_get_size().

Here is the caller graph for this function:

◆ GetStats()

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

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

capacity is the managed area size and allocated the bytes held by used blocks, both including headers (i.e. the real pool consumption). min_ever_free is derived from the peak, so it is exact in terms of consumed bytes, not of allocatable payload.

Returns
Stats structure.
Note
ISR-safe.

Definition at line 963 of file stk_memory_bytepool.h.

964{
965 const hw::CriticalSection::ScopedLock cs_;
966
967 return m_stats;
968}

References m_stats.

Referenced by stk::memory::MemoryAllocator::Weak::GetStats(), and stk_bytepool_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 }

◆ GuardOf()

uint32_t * stk::memory::BytePool::GuardOf ( const BlockHeader * h)
inlinestaticprivateinherited

Get the guard word location of the used block h (its last 4 bytes).

Definition at line 499 of file stk_memory_bytepool.h.

500 {
501 return reinterpret_cast<uint32_t *>(const_cast<uint8_t *>(reinterpret_cast<const uint8_t *>(h)) + h->size - sizeof(uint32_t));
502 }

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

Referenced by Free(), and ScanRange().

Here is the caller graph for this function:

◆ HeapSize()

size_t stk::memory::BytePool::HeapSize ( size_t size)
inlinestaticprivateinherited

Size of the heap buffer for size usable bytes: adds slack for aligning the area start when BLOCK_ALIGN is stricter than the guarantee of MemoryAllocator::Allocate(). 0 on overflow.

Definition at line 477 of file stk_memory_bytepool.h.

478 {
479 const size_t slack = ((BLOCK_ALIGN > MemoryAllocator::MIN_ALIGNMENT) ? (BLOCK_ALIGN - 1U) : 0U);
480 return ((size <= (static_cast<size_t>(~static_cast<size_t>(0U)) - slack)) ? (size + slack) : 0U);
481 }
static constexpr size_t MIN_ALIGNMENT
Minimum alignment (bytes) guaranteed for pointers returned by Allocate().

References BLOCK_ALIGN, and stk::memory::MemoryAllocator::MIN_ALIGNMENT.

Referenced by BytePool().

Here is the caller graph for this function:

◆ Init()

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

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

975{
976 STK_STATIC_ASSERT_DESC(sizeof(BlockHeader) == HEADER_SIZE, "BlockHeader must be exactly HEADER_SIZE bytes");
977
978 // start from an empty snapshot: a pool that turns out to be invalid (no storage, or too small for a single
979 // block) must report zero capacity, consistent with GetSize() == 0; a valid pool sets the real capacity below
980 m_stats.Reset(0U);
981
982 if (m_storage != nullptr)
983 {
984 // align the area start to BLOCK_ALIGN and trim its size to a multiple of BLOCK_ALIGN
985 const size_t addr = static_cast<size_t>(hw::PtrToWord(m_storage));
986 const size_t shift = (AlignSize(addr) - addr);
987 size_t usable = ((m_storage_size > shift) ? ((m_storage_size - shift) & ~(BLOCK_ALIGN - 1U)) : 0U);
988
989 // block sizes are 32-bit: a larger area would be wasted beyond this limit
990 if (usable > POOL_SIZE_MAX)
991 {
992 usable = POOL_SIZE_MAX;
993 }
994
995 if (usable >= MIN_BLOCK_SIZE)
996 {
999
1000 m_first->size = static_cast<uint32_t>(usable);
1001 m_first->state = STATE_FREE;
1002
1003 m_rover = m_first;
1004
1005 m_stats.Reset(usable);
1006 }
1007 }
1008}
#define STK_STATIC_ASSERT_DESC(X, DESC)
Compile-time assertion with a custom error description. Produces a compilation error if X is false.
Definition stk_defs.h:548
static T * WordToPtr(Word value) noexcept
Cast a CPU register-width integer back to a pointer.
Definition stk_arch.h:232
static const size_t POOL_SIZE_MAX
Largest managed area: block sizes are stored as 32-bit values (kept a multiple of BLOCK_ALIGN).
size_t m_storage_size
size of the raw storage in bytes
uint8_t * m_storage
raw storage as supplied or allocated (before alignment)
static constexpr size_t AlignSize(size_t raw_size)
Round a size up to the nearest multiple of the block alignment (BLOCK_ALIGN).

References AlignSize(), BLOCK_ALIGN, HEADER_SIZE, m_end, m_first, m_rover, m_stats, m_storage, m_storage_size, MIN_BLOCK_SIZE, POOL_SIZE_MAX, stk::hw::PtrToWord(), STATE_FREE, STK_STATIC_ASSERT_DESC, 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
inlineprivateinherited

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 STK_MEMORY_POOL_CHECKS builds only.

Definition at line 1124 of file stk_memory_bytepool.h.

1125{
1126 bool found = false;
1127
1128 for (const BlockHeader *b = m_first; (b != nullptr) && (b <= h) && (b < m_end) && IsSane(b); b = Next(b))
1129 {
1130 if (b == h)
1131 {
1132 found = true;
1133 break;
1134 }
1135 }
1136
1137 return found;
1138}

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
inlineprivateinherited

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

1011{
1012 const bool state_ok = ((h->state == STATE_FREE) || (h->state == STATE_USED));
1013
1014 return (state_ok &&
1015 (h->size >= MIN_BLOCK_SIZE) &&
1016 ((h->size % BLOCK_ALIGN) == 0U) &&
1017 (static_cast<size_t>(reinterpret_cast<const uint8_t *>(m_end) - reinterpret_cast<const uint8_t *>(h)) >= h->size));
1018}

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(), Free(), GetInfo(), IsBlockStart(), and ScanRange().

Here is the caller graph for this function:

◆ IsStorageValid()

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

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

415{ return (m_first != nullptr); }

References m_first.

Referenced by stk_bytepool_is_storage_valid(), and TimedAllocEx().

Here is the caller graph for this function:

◆ MakeT()

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

Blocking allocate-and-construct returning an owning PoolPtr.

Warning
ISR-unsafe.

Definition at line 830 of file stk_memory_bytepool.h.

831{
832 return PoolPtr<T, BytePool>(NewT<T>(static_cast<TArgs &&>(args)...), this);
833}
T * NewT(TArgs &&...args)
Allocate a block for a T and construct it, blocking indefinitely.

References NewT().

Here is the call graph for this function:

◆ NewT()

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

Allocate a block for a T and construct it, blocking indefinitely.

Warning
ISR-unsafe.

Definition at line 800 of file stk_memory_bytepool.h.

801{
802 return TimedNewT<T>(WAIT_INFINITE, static_cast<TArgs &&>(args)...);
803}
T * TimedNewT(Timeout timeout_ticks, TArgs &&...args)
Allocate a block for a T and construct 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:

◆ Next()

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

Get the header of the block that follows h.

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

Definition at line 492 of file stk_memory_bytepool.h.

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

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

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

Here is the caller graph for this function:

◆ RequiredSize()

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

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

Equals the aligned payload (plus the guard word if STK_MEMORY_BYTEPOOL_GUARD is 1) plus the block header. Use it to size external storage, adding the value for every block that must be alive at the same time:

static constexpr size_t RequiredSize(size_t payload_size)
Compute the pool space consumed by a single allocation of payload_size bytes.
Parameters
[in]payload_sizeRequested payload size in bytes.
Returns
Space in bytes taken from the pool.

Definition at line 234 of file stk_memory_bytepool.h.

235 {
236 return (AlignSize(payload_size + GUARD_SIZE) + HEADER_SIZE);
237 }

References AlignSize(), GUARD_SIZE, and HEADER_SIZE.

Referenced by STK_STATIC_ASSERT_DESC(), TimedAllocEx(), and tx_byte_pool_create().

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

◆ ScanRange()

void * stk::memory::BytePool::ScanRange ( BlockHeader * from,
const BlockHeader * stop,
size_t need,
size_t & scanned )
inlineprivateinherited

Scan the blocks in [from, stop) for a free block that can hold need bytes.

Parameters
[in,out]scannedIncremented for every inspected block.
Note
Critical section must be held.

Definition at line 1040 of file stk_memory_bytepool.h.

1041{
1042 void *result = nullptr;
1043
1044 for (BlockHeader *h = from; (h != nullptr) && (h < stop) && (result == nullptr); h = Next(h))
1045 {
1046 ++scanned;
1047
1048 if (!IsSane(h))
1049 {
1050 STK_ASSERT(false); // pool metadata is corrupted (payload overrun?)
1051 break;
1052 }
1053
1054 if (h->state == STATE_FREE)
1055 {
1056 Coalesce(h);
1057
1058 if (h->size >= need)
1059 {
1060 const size_t rest = (h->size - need);
1061
1062 // split off the tail if it can form a valid block of its own
1063 if (rest >= MIN_BLOCK_SIZE)
1064 {
1065 BlockHeader *const tail = reinterpret_cast<BlockHeader *>(reinterpret_cast<uint8_t *>(h) + need);
1066 tail->size = static_cast<uint32_t>(rest);
1067 tail->state = STATE_FREE;
1068
1069 h->size = static_cast<uint32_t>(need);
1070 }
1071
1072 h->state = STATE_USED;
1073 result = (h + 1);
1074
1075 m_stats.RecordAllocate(h->size);
1076
1077 #if STK_MEMORY_POOL_CHECKS
1078 Fill(result, (h->size - HEADER_SIZE - GUARD_SIZE), FILL_ALLOC);
1079 #endif
1080
1081 #if STK_MEMORY_BYTEPOOL_GUARD
1082 *GuardOf(h) = GUARD_MAGIC;
1083 #endif
1084
1085 #if STK_MEMORY_BYTEPOOL_NEXT_FIT
1086 {
1087 BlockHeader *const nxt = Next(h);
1088 m_rover = ((nxt < m_end) ? nxt : m_first);
1089 }
1090 #endif
1091 }
1092 }
1093 }
1094
1095 return result;
1096}
static const uint8_t FILL_ALLOC
payload fill on allocation (STK_MEMORY_POOL_CHECKS)
uint32_t size
total block size including this header (multiple of BLOCK_ALIGN)

References Coalesce(), Fill(), FILL_ALLOC, GUARD_MAGIC, GUARD_SIZE, GuardOf(), HEADER_SIZE, IsSane(), m_end, m_first, m_rover, m_stats, MIN_BLOCK_SIZE, Next(), stk::memory::BytePool::BlockHeader::size, stk::memory::BytePool::BlockHeader::state, STATE_FREE, STATE_USED, and STK_ASSERT.

Referenced by FindFree().

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:

◆ STK_NONCOPYABLE_CLASS()

stk::memory::BytePool::STK_NONCOPYABLE_CLASS ( BytePool )
privateinherited

References BytePool().

Here is the call graph for this function:

◆ STK_STATIC_ASSERT_DESC() [1/3]

stk::memory::BytePool::STK_STATIC_ASSERT_DESC ( (BLOCK_ALIGN >=4U) &&((BLOCK_ALIGN &(BLOCK_ALIGN - 1U))==0U) ,
"STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT must be a power of two not less than 4"  )
inherited

References BLOCK_ALIGN.

◆ STK_STATIC_ASSERT_DESC() [2/3]

template<size_t TSize>
stk::memory::StaticBytePool< TSize >::STK_STATIC_ASSERT_DESC ( TSize >= BytePool::HEADER_SIZE+BytePool::BLOCK_ALIGN,
"pool size must fit at least one block"  )
private

◆ STK_STATIC_ASSERT_DESC() [3/3]

template<size_t TSize>
stk::memory::StaticBytePool< TSize >::STK_STATIC_ASSERT_DESC ( TSize<= 0xFFFFFFFFUL &~(BytePool::BLOCK_ALIGN - 1U),
"pool size exceeds the 32-bit block size limit"  )
private

◆ TimedAlloc()

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

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

Parameters
[in]sizeRequested payload size in bytes.
[in]timeout_ticksMaximum time to wait (ticks). Same semantics as TimedAllocEx().
Returns
Pointer to an uninitialized block of at least size bytes aligned to BLOCK_ALIGN, 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 737 of file stk_memory_bytepool.h.

738{
739 void *block = nullptr;
740
741 if (TimedAllocEx(&block, size, timeout_ticks) != WAIT_RESULT_SIGNAL)
742 {
743 block = nullptr;
744 }
745
746 return block;
747}
@ WAIT_RESULT_SIGNAL
The wake was caused by a signal.
Definition stk_common.h:140
EWaitResult TimedAllocEx(void **block, size_t size, Timeout timeout_ticks=WAIT_INFINITE)
Allocate a block, preserving the full wait outcome.

References TimedAllocEx(), and stk::WAIT_RESULT_SIGNAL.

Referenced by Alloc(), stk_bytepool_timed_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 )
inlineinherited

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]blockReceives the allocated block on WAIT_RESULT_SIGNAL, nullptr on any other result. Must not be nullptr.
[in]sizeRequested payload size in bytes (must be > 0 and <= GetMaxRequest()).
[in]timeout_ticksMaximum 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 630 of file stk_memory_bytepool.h.

631{
633
634 STK_ASSERT(block != nullptr); // API contract: output pointer must be valid
635
636 if (block == nullptr)
637 {
638 // result is WAIT_RESULT_FAIL already, so noop
639 }
640 else
641 {
642 *block = nullptr;
643
644 if (hw::IsInsideISR() && (timeout_ticks != NO_WAIT))
645 {
646 STK_ASSERT(false); // API contract: ISR callers must pass NO_WAIT / use TryAlloc()
647 }
648 else if ((size == 0U) || (size > GetMaxRequest()))
649 {
650 // result is WAIT_RESULT_FAIL: such a request can never succeed, so do not block on it;
651 // an oversized request on a valid pool still counts as a failed allocation (pool sizing aid)
652 if ((size != 0U) && IsStorageValid())
653 {
654 const hw::CriticalSection::ScopedLock cs_;
655
656 m_stats.RecordAllocFail();
657 }
658 }
659 else
660 {
661 sync::ScopedCriticalSection cs_;
662
663 // safe from overflow: size <= GetMaxRequest() <= POOL_SIZE_MAX - HEADER_SIZE - GUARD_SIZE
664 const size_t need = RequiredSize(size);
665
666 const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
667
668 // capture an absolute deadline once, before entering the wait loop; every Free()
669 // wakes all waiters (Mesa-style, not a direct handoff) and a woken task may have
670 // to wait again, so re-passing the original timeout_ticks on each retry would
671 // silently restart it; kept as 64-bit Ticks (not truncated to Timeout) so it
672 // can't wrap on long uptimes
673 const Ticks deadline = (timed_wait ? (GetTicks() + static_cast<Ticks>(timeout_ticks)) : 0);
674
675 void *ptr = FindFree(need); // fast path: a suitable block is already available
676 result = WAIT_RESULT_SIGNAL;
677
678 while (ptr == nullptr)
679 {
680 Timeout remaining = timeout_ticks;
681
682 if (timeout_ticks == NO_WAIT)
683 {
684 result = WAIT_RESULT_TIMEOUT; // no waiting requested (ISR-safe path)
685 break;
686 }
687
688 if (timed_wait)
689 {
690 const Ticks left = (deadline - GetTicks());
691 if (left <= 0)
692 {
693 result = WAIT_RESULT_TIMEOUT; // budget is spent and a scan was just made
694 break;
695 }
696 remaining = static_cast<Timeout>(left);
697 }
698
699 // Atomically release the critical section, suspend the task, and
700 // re-acquire before returning - no CPU cycles wasted while waiting.
701 result = m_cv.WaitEx(cs_, remaining);
702 if ((result != WAIT_RESULT_SIGNAL) && (result != WAIT_RESULT_TIMEOUT))
703 {
704 break; // cancellation or kernel failure: report as is
705 }
706
707 // the lock was re-acquired: re-scan regardless of the wake reason, because the memory
708 // may have been released at the very moment the timeout expired (honor it instead of
709 // failing), or may have been taken by someone else after the wake-up (wait again)
710 ptr = FindFree(need);
711 if (ptr != nullptr)
712 {
713 result = WAIT_RESULT_SIGNAL;
714 }
715 else if (result == WAIT_RESULT_TIMEOUT)
716 {
717 break;
718 }
719 else
720 {
721 // spurious or stolen wake-up: continue waiting within the remaining budget
722 }
723 }
724
725 if ((ptr == nullptr) && (result == WAIT_RESULT_TIMEOUT))
726 {
727 m_stats.RecordAllocFail(); // memory exhausted/fragmented (cancellation is not counted)
728 }
729
730 *block = ptr;
731 }
732 }
733
734 return result;
735}
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).
bool IsStorageValid() const
Verify that the backing storage is valid and the pool is ready for use.
size_t GetMaxRequest() const
Get the largest request that can ever succeed on this pool.
void * FindFree(size_t need)
Find (and claim) the first free block that can hold need bytes.

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

Referenced by stk_bytepool_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::BytePool::TimedAllocT ( Timeout timeout_ticks = WAIT_INFINITE)
inlineinherited

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 (see TimedNewT()). T must not require alignment above BLOCK_ALIGN (compile-time checked).

Parameters
[in]timeout_ticksMaximum 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 750 of file stk_memory_bytepool.h.

751{
752 STK_STATIC_ASSERT_DESC(alignof(T) <= BLOCK_ALIGN, "payload is aligned to BLOCK_ALIGN only (STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT)");
753
754 return static_cast<T *>(TimedAlloc(sizeof(T), timeout_ticks));
755}

References BLOCK_ALIGN, STK_STATIC_ASSERT_DESC, 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::BytePool::TimedNewT ( Timeout timeout_ticks,
TArgs &&... args )
inlineinherited

Allocate a block for a T and construct 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.
Note
Pair with DeleteT(). ISR-safe only with NO_WAIT (and only if the constructor is).

Definition at line 786 of file stk_memory_bytepool.h.

787{
788 T *const ptr = TimedAllocT<T>(timeout_ticks);
789
790 if (ptr != nullptr)
791 {
792 auto const obj = new (static_cast<void *>(ptr)) T(static_cast<TArgs &&>(args)...);
793 STK_UNUSED(obj);
794 }
795
796 return ptr;
797}

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::BytePool::TryAlloc ( size_t size)
inlineinherited

Non-blocking allocation attempt.

Parameters
[in]sizeRequested 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 768 of file stk_memory_bytepool.h.

769{
770 return TimedAlloc(size, NO_WAIT);
771}

References stk::NO_WAIT, and TimedAlloc().

Referenced by stk::memory::MemoryAllocator::Weak::Allocate(), and stk_bytepool_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::BytePool::TryAllocT ( )
inlineinherited

Non-blocking typed allocation attempt.

Returns
Typed pointer, or nullptr if no suitable free block exists.
Note
ISR-safe (see TryAlloc()).

Definition at line 774 of file stk_memory_bytepool.h.

775{
776 return TimedAllocT<T>(NO_WAIT);
777}

References stk::NO_WAIT, and TimedAllocT().

Here is the call graph for this function:

◆ TryMakeT()

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

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

Definition at line 824 of file stk_memory_bytepool.h.

825{
826 return PoolPtr<T, BytePool>(TryNewT<T>(static_cast<TArgs &&>(args)...), this);
827}
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::BytePool::TryNewT ( TArgs &&... args)
inlineinherited

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

Definition at line 806 of file stk_memory_bytepool.h.

807{
808 return TimedNewT<T>(NO_WAIT, static_cast<TArgs &&>(args)...);
809}

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

◆ BLOCK_ALIGN

◆ FILL_ALLOC

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

payload fill on allocation (STK_MEMORY_POOL_CHECKS)

Definition at line 470 of file stk_memory_bytepool.h.

Referenced by ScanRange().

◆ FILL_FREE

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

payload fill on free (STK_MEMORY_POOL_CHECKS)

Definition at line 471 of file stk_memory_bytepool.h.

Referenced by Free().

◆ GUARD_MAGIC

const uint32_t stk::memory::BytePool::GUARD_MAGIC = 0xA5C3E17BUL
staticprivateinherited

value of the guard word of a used block

Definition at line 464 of file stk_memory_bytepool.h.

Referenced by Free(), and ScanRange().

◆ GUARD_SIZE

const size_t stk::memory::BytePool::GUARD_SIZE = (( (0) != 0) ? 4U : 0U)
staticprivateinherited

Size of the overrun guard word at the end of every used block (0 = disabled).

Definition at line 462 of file stk_memory_bytepool.h.

Referenced by GetMaxRequest(), RequiredSize(), and ScanRange().

◆ HEADER_SIZE

const size_t stk::memory::BytePool::HEADER_SIZE = ((BLOCK_ALIGN > 8U) ? BLOCK_ALIGN : 8U)
staticinherited

Size of the per-block header in bytes: max(8, BLOCK_ALIGN).

Every allocation consumes HEADER_SIZE bytes of the pool in addition to its (aligned) payload. It is a multiple of BLOCK_ALIGN so the payload that directly follows the header is aligned as well.

Definition at line 174 of file stk_memory_bytepool.h.

Referenced by AccountRun(), Free(), GetMaxRequest(), Init(), RequiredSize(), ScanRange(), stk_bytepool_create(), stk_bytepool_create_static(), stk::memory::StaticBytePool< TSize >::STK_STATIC_ASSERT_DESC(), and STK_STATIC_ASSERT_DESC().

◆ m_buf

template<size_t TSize>
uint8_t stk::memory::detail::BytePoolStorage< TSize >::m_buf[TSize]
inherited

◆ m_cv

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

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

Definition at line 549 of file stk_memory_bytepool.h.

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

◆ m_end

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

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

Definition at line 547 of file stk_memory_bytepool.h.

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

◆ m_first

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

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

Definition at line 546 of file stk_memory_bytepool.h.

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

◆ m_max_scan

size_t stk::memory::BytePool::m_max_scan
privateinherited

longest block-list walk of a single allocation

Definition at line 552 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), FindFree(), and GetMaxScanLength().

◆ m_rover

BlockHeader* stk::memory::BytePool::m_rover
privateinherited

where the next search starts (STK_MEMORY_BYTEPOOL_NEXT_FIT)

Definition at line 548 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), Coalesce(), FindFree(), Init(), and ScanRange().

◆ m_stats

MemoryAllocator::Stats stk::memory::BytePool::m_stats
privateinherited

live statistics: bytes of used blocks (headers included), watermark, counters

Definition at line 551 of file stk_memory_bytepool.h.

Referenced by BytePool(), BytePool(), Free(), GetAllocFailCount(), GetPeakUsedSize(), GetStats(), Init(), ScanRange(), TimedAllocEx(), and ~BytePool().

◆ m_storage

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

raw storage as supplied or allocated (before alignment)

Definition at line 545 of file stk_memory_bytepool.h.

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

◆ m_storage_owned

bool stk::memory::BytePool::m_storage_owned
privateinherited

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

Definition at line 553 of file stk_memory_bytepool.h.

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

◆ m_storage_size

size_t stk::memory::BytePool::m_storage_size
privateinherited

size of the raw storage in bytes

Definition at line 550 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)
staticprivateinherited

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

Also the smallest remainder worth splitting off.

Definition at line 454 of file stk_memory_bytepool.h.

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

◆ POOL_SIZE_MAX

const size_t stk::memory::BytePool::POOL_SIZE_MAX = (static_cast<size_t>(0xFFFFFFFFUL) & ~(BLOCK_ALIGN - 1U))
staticprivateinherited

Largest managed area: block sizes are stored as 32-bit values (kept a multiple of BLOCK_ALIGN).

Definition at line 458 of file stk_memory_bytepool.h.

Referenced by Init().

◆ STATE_FREE

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

"FREE"

Definition at line 466 of file stk_memory_bytepool.h.

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

◆ STATE_NONE

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

stale header absorbed by a merge

Definition at line 468 of file stk_memory_bytepool.h.

Referenced by Coalesce().

◆ STATE_USED

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

"USED"

Definition at line 467 of file stk_memory_bytepool.h.

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


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