26 "STK_BLOCKPOOL_ALIGN and BlockMemoryPool::ALIGN_DEFAULT have diverged "
27 "(STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT). Keep both definitions in sync.");
29 "STK_BYTEPOOL_ALIGN and BytePool::BLOCK_ALIGN have diverged "
30 "(STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT). Keep both definitions in sync.");
32 "STK_MEM_MIN_ALIGNMENT and MemoryAllocator::MIN_ALIGNMENT have diverged. Keep both definitions in sync.");
50 "STK_BLOCKPOOL_* macros and BlockMemoryPool have diverged. Keep both definitions in sync.");
63 "STK_BYTEPOOL_* macros and BytePool have diverged. Keep both definitions in sync.");
70 "stk_wait_result_t mismatch");
82 uint8_t *storage,
size_t storage_size,
const char *name,
size_t alignment)
83 :
handle(capacity, raw_block_size, storage, storage_size, name, alignment)
86#if STK_MEMORY_HAS_HEAP
88 stk_blockpool_t(
size_t capacity,
size_t raw_block_size,
const char *name,
size_t alignment)
89 :
handle(capacity, raw_block_size, name, alignment)
106 :
handle(storage, storage_size, name)
109#if STK_MEMORY_HAS_HEAP
112 :
handle(storage_size, name)
125template <
typename T>
constexpr size_t StkGetWordCountForType()
159 BlockPoolSlot() : busy(false)
178 BytePoolSlot() : busy(false)
196 BlockPoolSlot *result =
nullptr;
200 if (s_BlockPools[i].busy)
202 if (s_BlockPools[i].pool() == pool)
204 result = &s_BlockPools[i];
214BlockPoolSlot *AcquireSlot()
216 BlockPoolSlot *result =
nullptr;
220 if (!s_BlockPools[i].busy)
222 s_BlockPools[i].busy =
true;
223 result = &s_BlockPools[i];
234 BytePoolSlot *result =
nullptr;
238 if (s_BytePools[i].busy)
240 if (s_BytePools[i].pool() == pool)
242 result = &s_BytePools[i];
252BytePoolSlot *AcquireBytePoolSlot()
254 BytePoolSlot *result =
nullptr;
258 if (!s_BytePools[i].busy)
260 s_BytePools[i].busy =
true;
261 result = &s_BytePools[i];
283 size_t raw_block_size,
292#if STK_MEMORY_HAS_HEAP
295 BlockPoolSlot *
const slot = AcquireSlot();
319 size_t raw_block_size,
320 uint8_t *storage_ptr,
332 BlockPoolSlot *
const slot = AcquireSlot();
341 storage_ptr, storage_size, name, alignment);
348 size_t raw_block_size,
349 uint8_t *storage_ptr,
363 BlockPoolSlot *
const slot = FindSlot(pool);
370 pool->~stk_blockpool_t();
524#if STK_MEMORY_HAS_HEAP
527 BytePoolSlot *
const slot = AcquireBytePoolSlot();
553 BytePoolSlot *
const slot = AcquireBytePoolSlot();
573 BytePoolSlot *
const slot = FindBytePoolSlot(pool);
580 pool->~stk_bytepool_t();
649 if (available !=
nullptr) { *available = avail; }
650 if (largest !=
nullptr) { *largest = large; }
651 if (fragments !=
nullptr) { *fragments = frags; }
716#if STK_MEMORY_NO_HEAP
725 void *result =
nullptr;
745 void *result =
nullptr;
747#if STK_MEMORY_HAS_HEAP
759#if STK_MEMORY_HAS_HEAP
Collection of memory-related primitives (stk::memory namespace).
Top-level STK include. Provides the Kernel class template and all built-in task-switching strategies.
#define STK_UNUSED(X)
Explicitly marks a variable as unused to suppress compiler warnings.
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
#define STK_STATIC_ASSERT_DESC(X, DESC)
Compile-time assertion with a custom error description. Produces a compilation error if X is false.
C language binding/interface for SuperTinyKernel RTOS.
C language bindings for stk::memory::BlockMemoryPool, stk::memory::BytePool and stk::memory::MemoryAl...
stk_wait_result_t
Outcome of a cancellable, timed kernel wait (see stk_cv_wait_ex(), stk_mutex_timed_lock_ex(),...
int32_t stk_timeout_t
Timeout value.
@ STK_WAIT_RESULT_TIMEOUT
The wake was caused by a timeout expiry.
@ STK_WAIT_RESULT_SIGNAL
The wake was caused by a signal.
@ STK_WAIT_RESULT_CANCELED
The wait was cancelled by another task, independent of signal/timeout.
@ STK_WAIT_RESULT_FAIL
The kernel returned an error without actually waiting.
size_t stk_blockpool_get_capacity(const stk_blockpool_t *pool)
Get the total block capacity of the pool.
void * stk_blockpool_timed_alloc(stk_blockpool_t *pool, stk_timeout_t timeout)
Allocate one block, blocking until one becomes available or the timeout expires.
size_t stk_bytepool_get_size(const stk_bytepool_t *pool)
Get the total managed (aligned) area size in bytes, headers included.
#define STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size)
Same as STK_BLOCKPOOL_STORAGE_SIZE_EX() with the default alignment.
void stk_blockpool_destroy(stk_blockpool_t *pool)
Destroy a pool and return its slot to the static pool.
size_t stk_blockpool_get_alloc_fail_count(const stk_blockpool_t *pool)
Get the number of allocation requests that failed because the pool was exhausted (timeouts and STK_NO...
#define STK_BYTEPOOL_REQUIRED_SIZE(payload_size)
Pool space in bytes consumed by one allocation of payload_size bytes (aligned payload,...
bool stk_blockpool_is_storage_valid(const stk_blockpool_t *pool)
Verify that the backing storage is valid and the pool is ready for use.
bool stk_bytepool_free(stk_bytepool_t *pool, void *ptr)
Return a previously allocated block to the pool.
#define STK_C_BLOCKPOOL_MAX
Maximum number of concurrent stk_blockpool_t instances (default: 8).
size_t stk_blockpool_get_block_alignment(const stk_blockpool_t *pool)
Get the alignment of every block of the pool.
size_t stk_blockpool_get_used_count(const stk_blockpool_t *pool)
Get the number of currently allocated (outstanding) blocks.
#define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX(raw_size, align)
Compute the internally aligned block size for a given raw byte size and alignment.
struct stk_blockpool_t stk_blockpool_t
Opaque handle to a stk::memory::BlockMemoryPool instance.
void * stk_blockpool_alloc(stk_blockpool_t *pool)
Allocate one block, blocking indefinitely until one is available.
void stk_bytepool_destroy(stk_bytepool_t *pool)
Destroy a byte pool and return its slot to the static pool.
size_t stk_bytepool_get_peak_used_size(const stk_bytepool_t *pool)
Get the high watermark of pool consumption in bytes (headers included).
BlockMemoryPool * stk_blockpool_get_instance(stk_blockpool_t *pool)
Get the underlying C++ stk::memory::BlockMemoryPool object wrapped by a stk_blockpool_t handle.
#define STK_BYTEPOOL_ALIGN_SIZE(raw_size)
Round raw_size up to the nearest multiple of STK_BYTEPOOL_ALIGN.
#define STK_C_BYTEPOOL_MAX
Maximum number of concurrent stk_bytepool_t instances (default: 8).
stk_bytepool_t * stk_bytepool_create(size_t storage_size, const char *name)
Create a byte pool backed by heap-allocated storage.
stk_wait_result_t stk_blockpool_timed_alloc_ex(stk_blockpool_t *pool, void **block, stk_timeout_t timeout)
Allocate one block, preserving the full wait outcome.
struct stk_bytepool_t stk_bytepool_t
Opaque handle to a stk::memory::BytePool instance.
void * stk_bytepool_timed_alloc(stk_bytepool_t *pool, size_t size, stk_timeout_t timeout)
Allocate a block, blocking until memory becomes available or the timeout expires.
size_t stk_bytepool_get_max_request(const stk_bytepool_t *pool)
Get the largest request that can ever succeed on this pool.
void * stk_bytepool_alloc(stk_bytepool_t *pool, size_t size)
Allocate a block, blocking indefinitely until enough contiguous memory is available.
stk_wait_result_t stk_bytepool_timed_alloc_ex(stk_bytepool_t *pool, void **block, size_t size, stk_timeout_t timeout)
Allocate a block, preserving the full wait outcome.
#define STK_BLOCKPOOL_BITMAP_BYTES(capacity)
Size in bytes of the "allocated" bitmap of a pool of capacity blocks (0 unless STK_MEMORY_BLOCKPOOL_B...
bool stk_blockpool_free(stk_blockpool_t *pool, void *ptr)
Return a previously allocated block to the pool.
void * stk_blockpool_try_alloc(stk_blockpool_t *pool)
Non-blocking allocation attempt.
size_t stk_bytepool_get_max_scan_length(const stk_bytepool_t *pool)
Get the length of the longest block-list walk (in blocks) of any allocation so far.
stk_blockpool_t * stk_blockpool_create_static(size_t capacity, size_t raw_block_size, uint8_t *storage_ptr, size_t storage_size, const char *name)
Create a block pool backed by caller-supplied (external) storage (default alignment).
#define STK_BYTEPOOL_HEADER_SIZE
Per-block header size in bytes: max(8, STK_BYTEPOOL_ALIGN). Every allocation consumes this many bytes...
stk_blockpool_t * stk_blockpool_create(size_t capacity, size_t raw_block_size, const char *name)
Create a block pool backed by heap-allocated storage (default alignment).
stk_bytepool_t * stk_bytepool_create_static(uint8_t *storage, size_t storage_size, const char *name)
Create a byte pool backed by caller-supplied (external) storage.
void stk_mem_free_aligned(void *ptr)
Free a chunk obtained with stk_mem_allocate_aligned().
#define STK_BLOCKPOOL_STORAGE_SIZE_EX(capacity, raw_block_size, align)
Compute the minimum external storage buffer size in bytes (blocks plus the optional bitmap)....
bool stk_blockpool_is_empty(const stk_blockpool_t *pool)
Check whether all blocks are free (no outstanding allocations).
void stk_mem_get_stats(stk_mem_stats_t *stats)
Get statistics of the general-purpose allocator.
bool stk_bytepool_is_storage_valid(const stk_bytepool_t *pool)
Verify that the backing storage is valid and the pool is ready for use.
bool stk_blockpool_is_full(const stk_blockpool_t *pool)
Check whether all blocks are currently allocated (pool exhausted).
size_t stk_blockpool_get_free_count(const stk_blockpool_t *pool)
Get the number of free (available) blocks.
size_t stk_blockpool_get_peak_used_count(const stk_blockpool_t *pool)
Get the high watermark: the maximum number of blocks allocated at the same time.
void stk_mem_free(void *ptr)
Free a chunk obtained with stk_mem_allocate().
size_t stk_bytepool_get_alloc_fail_count(const stk_bytepool_t *pool)
Get the number of allocation requests that failed because no suitable block was available (timeouts,...
void * stk_bytepool_try_alloc(stk_bytepool_t *pool, size_t size)
Non-blocking allocation attempt.
#define STK_BYTEPOOL_ALIGN
Payload alignment and block size granularity of a byte pool, in bytes (equals STK_MEMORY_BYTEPOOL_ALI...
void stk_bytepool_get_stats(const stk_bytepool_t *pool, stk_mem_stats_t *stats)
Get an O(1) statistics snapshot.
size_t stk_blockpool_get_block_size(const stk_blockpool_t *pool)
Get the aligned block size used internally by the allocator.
#define STK_MEM_MIN_ALIGNMENT
Minimum alignment in bytes guaranteed for pointers returned by stk_mem_allocate() (equals MemoryAlloc...
#define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(raw_size)
Same as STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX() with the default alignment.
void * stk_mem_allocate_aligned(size_t size, size_t alignment)
Allocate a chunk with an alignment stricter than STK_MEM_MIN_ALIGNMENT.
void stk_bytepool_get_info(const stk_bytepool_t *pool, size_t *available, size_t *largest, size_t *fragments)
Collect pool statistics (mutually consistent snapshot).
stk_blockpool_t * stk_blockpool_create_ex(size_t capacity, size_t raw_block_size, const char *name, size_t alignment)
Create a block pool backed by heap-allocated storage with an explicit block alignment.
void stk_blockpool_get_stats(const stk_blockpool_t *pool, stk_mem_stats_t *stats)
Get a consistent statistics snapshot (bytes: blocks * block size).
BytePool * stk_bytepool_get_instance(stk_bytepool_t *pool)
Get the underlying C++ stk::memory::BytePool object wrapped by a stk_bytepool_t handle.
stk_blockpool_t * stk_blockpool_create_static_ex(size_t capacity, size_t raw_block_size, uint8_t *storage_ptr, size_t storage_size, const char *name, size_t alignment)
Create a block pool backed by caller-supplied storage with an explicit block alignment.
#define STK_BLOCKPOOL_ALIGN
Default block alignment in bytes (equals STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT, i.e. BlockMemoryPool::AL...
bool stk_mem_is_available(void)
Check that the memory allocator implementation is linked in.
void * stk_mem_allocate(size_t size)
Allocate a memory chunk from the general-purpose allocator.
Namespace of STK package.
uintptr_t Word
Native processor word type.
static T * ConstructIn(Mem &mem, Args &&... args)
Construct object T in-place inside a C memory container.
@ WAIT_RESULT_FAIL
IKernelService::Wait returned with error without waiting.
@ WAIT_RESULT_CANCELED
The wait was cancelled by another task via IKernel::CancelTaskWait(), independent of signal/timeout.
@ WAIT_RESULT_TIMEOUT
The wake was caused by a timeout expiry.
@ WAIT_RESULT_SIGNAL
The wake was caused by a signal.
bool IsInsideISR()
Check whether the CPU is currently executing inside a hardware interrupt service routine (ISR).
Memory-related primitives: fixed-size block pool, variable-size byte pool, zero-heap pool variants,...
static void * AllocateAligned(size_t size, size_t alignment, size_t offset=0U)
Allocate memory with an alignment stricter than MIN_ALIGNMENT and an optional offset.
static Stats GetStats()
Get stats of memory allocation (checked).
static void Free(void *ptr)
Free the memory chunk (checked).
static constexpr size_t MIN_ALIGNMENT
Minimum alignment (bytes) guaranteed for pointers returned by Allocate().
static bool IsAvailable()
Check that Weak::Allocate() and Weak::Free() were provided by the application.
static void FreeAligned(void *ptr)
Free memory obtained with AllocateAligned().
static void * Allocate(size_t size)
Allocate the memory chunk (checked).
Snapshot of the memory allocator's statistics.
volatile size_t allocated
Number of bytes currently allocated (dynamic value).
volatile size_t allocate_count
Number of successful allocations with Allocate().
size_t capacity
Total capacity of the memory pool in bytes.
volatile size_t free_count
Number of successful frees with Free().
volatile size_t min_ever_free
Minimum free bytes recorded since system start (watermark).
volatile size_t alloc_fail_count
Number of allocation requests that could not be satisfied.
volatile size_t peak_allocated
Maximum number of bytes that were allocated at the same time (high watermark).
Fixed-size block allocator with O(1) alloc/free and proper task-blocking semantics.
size_t GetUsedCount() const
Get the number of currently allocated (outstanding) blocks.
EWaitResult TimedAllocEx(void **block, Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, preserving the full wait outcome.
static const size_t ALIGN_DEFAULT
Default block alignment in bytes (see STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT).
static constexpr size_t BitmapBytes(size_t capacity)
Number of bytes of the "allocated" bitmap for capacity blocks.
size_t GetFreeCount() const
Get the number of free (available) blocks.
size_t GetCapacity() const
Get the total block capacity of the pool.
size_t GetBlockAlignment() const
Get the alignment (bytes) of every block.
bool IsFull() const
Check whether all blocks are currently allocated (pool exhausted).
size_t GetAllocFailCount() const
Get the number of allocation requests that failed because the pool was exhausted (timeouts and NO_WAI...
bool IsStorageValid() const
Verify that the backing storage is valid and the pool is ready for use.
MemoryAllocator::Stats GetStats() const
Get a consistent statistics snapshot in the same format as MemoryAllocator::GetStats().
bool Free(void *ptr)
Return a previously allocated block to the pool.
size_t GetPeakUsedCount() const
Get the high watermark: the maximum number of blocks that were allocated at the same time.
void * TryAlloc()
Non-blocking allocation attempt.
void * TimedAlloc(Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, blocking until one becomes available or the timeout expires.
size_t GetBlockSize() const
Get the aligned block size used internally by the allocator.
void * Alloc()
Allocate one block, blocking indefinitely until one is available.
bool IsEmpty() const
Check whether all blocks are free (no outstanding allocations).
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 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.
Variable-size (first-fit) allocator with block coalescing and proper task-blocking semantics.
size_t GetMaxScanLength() const
Get the length of the longest block-list walk (in blocks) of any allocation so far.
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 GetMaxRequest() const
Get the largest request that can ever succeed on this pool.
static const size_t HEADER_SIZE
Size of the per-block header in bytes: max(8, BLOCK_ALIGN).
size_t GetPeakUsedSize() const
Get the high watermark of pool consumption in bytes (headers included).
EWaitResult TimedAllocEx(void **block, size_t size, Timeout timeout_ticks=WAIT_INFINITE)
Allocate a block, preserving the full wait outcome.
MemoryAllocator::Stats GetStats() const
Get a consistent O(1) statistics snapshot in the same format as MemoryAllocator::GetStats().
size_t GetSize() const
Get the total size of the managed (aligned) area in bytes, headers included.
void * Alloc(size_t size)
Allocate a block, blocking indefinitely until memory is available.
void GetInfo(size_t &available, size_t &largest, size_t &fragments) const
Collect pool statistics.
static constexpr size_t RequiredSize(size_t payload_size)
Compute the pool space consumed by a single allocation of payload_size bytes.
static constexpr size_t AlignSize(size_t raw_size)
Round a size up to the nearest multiple of the block alignment (BLOCK_ALIGN).
static const size_t BLOCK_ALIGN
Payload alignment and block size granularity in bytes.
size_t GetAllocFailCount() const
Get the number of allocation requests that failed because no suitable block was available (timeouts,...
void * TryAlloc(size_t size)
Non-blocking allocation attempt.
void * TimedAlloc(size_t size, Timeout timeout_ticks=WAIT_INFINITE)
Allocate a block, blocking until memory becomes available or the timeout expires.
RAII-style low-level synchronization primitive for atomic code execution. Used as building brick for ...
Snapshot of allocator statistics.
size_t peak_allocated
High watermark of allocated bytes.
size_t capacity
Total capacity in bytes.
size_t free_count
Number of successful frees.
size_t min_ever_free
Minimum free bytes recorded since the start (watermark).
size_t allocated
Bytes currently allocated.
size_t allocate_count
Number of successful allocations.
size_t alloc_fail_count
Number of allocation requests that could not be satisfied.
stk_blockpool_t(size_t capacity, size_t raw_block_size, uint8_t *storage, size_t storage_size, const char *name, size_t alignment)
stk_bytepool_t(uint8_t *storage, size_t storage_size, const char *name)