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_c_memory.h File Reference

C language bindings for stk::memory::BlockMemoryPool, stk::memory::BytePool and stk::memory::MemoryAllocator. More...

#include "stk_c.h"
Include dependency graph for stk_c_memory.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  stk_mem_stats_t
 Snapshot of allocator statistics. More...

Namespaces

namespace  stk
 Namespace of STK package.
namespace  stk::memory
 Memory-related primitives: fixed-size block pool, variable-size byte pool, zero-heap pool variants, pool-aware object helpers (PoolPtr) and the general-purpose allocator interface.

Macros

#define STK_C_BLOCKPOOL_MAX   (8U)
 Maximum number of concurrent stk_blockpool_t instances (default: 8).
#define STK_C_BYTEPOOL_MAX   (8U)
 Maximum number of concurrent stk_bytepool_t instances (default: 8).
#define STK_C_MEMORY_DEFAULT_ALLOCATOR   (0)
 Selects the implementation of stk::memory::MemoryAllocator provided by the C binding (default: 0).
#define STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT   (8U)
 Default block alignment of a block pool (see stk_memory_blockpool.h).
#define STK_MEMORY_BLOCKPOOL_BITMAP   (0)
 When 1, a block pool keeps an "allocated" bit per block (O(1) double-free detection in release builds) and its storage requirement grows by capacity/8 bytes (see stk_memory_blockpool.h).
#define STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT   (8U)
 Payload alignment of byte pool allocations (see stk_memory_bytepool.h).
#define STK_MEMORY_BYTEPOOL_GUARD   (0)
 When 1, every byte pool allocation carries a 4-byte overrun guard word (see stk_memory_bytepool.h).
#define STK_BLOCKPOOL_ALIGN   (STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT)
 Default block alignment in bytes (equals STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT, i.e. BlockMemoryPool::ALIGN_DEFAULT).
#define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX(raw_size, align)
 Compute the internally aligned block size for a given raw byte size and alignment.
#define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(raw_size)
 Same as STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX() with the default alignment.
#define STK_BLOCKPOOL_BITMAP_BYTES(capacity)
 Size in bytes of the "allocated" bitmap of a pool of capacity blocks (0 unless STK_MEMORY_BLOCKPOOL_BITMAP is 1). Matches BlockMemoryPool::BitmapBytes().
#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). Matches BlockMemoryPool::RequiredStorageSize().
#define STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size)
 Same as STK_BLOCKPOOL_STORAGE_SIZE_EX() with the default alignment.
#define STK_BLOCKPOOL_STORAGE_DECL_EX(name, capacity, raw_block_size, align)
 Declare a correctly sized storage array aligned to align bytes.
#define STK_BLOCKPOOL_STORAGE_DECL(name, capacity, raw_block_size)
 Declare a correctly sized and aligned external storage array (default alignment).
#define STK_BYTEPOOL_ALIGN   (STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT)
 Payload alignment and block size granularity of a byte pool, in bytes (equals STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT: 8, 16 on RISC-V by default).
#define STK_BYTEPOOL_HEADER_SIZE   ((STK_BYTEPOOL_ALIGN > 8U) ? STK_BYTEPOOL_ALIGN : 8U)
 Per-block header size in bytes: max(8, STK_BYTEPOOL_ALIGN). Every allocation consumes this many bytes of the pool in addition to its aligned payload.
#define STK_BYTEPOOL_GUARD_SIZE   ((STK_MEMORY_BYTEPOOL_GUARD != 0) ? 4U : 0U)
 Size of the overrun guard word of a used block (4 with STK_MEMORY_BYTEPOOL_GUARD, otherwise 0).
#define STK_BYTEPOOL_ALIGN_SIZE(raw_size)
 Round raw_size up to the nearest multiple of STK_BYTEPOOL_ALIGN.
#define STK_BYTEPOOL_REQUIRED_SIZE(payload_size)
 Pool space in bytes consumed by one allocation of payload_size bytes (aligned payload, plus the guard word if enabled, plus the block header). Sum the value for every block that must be alive simultaneously to size external storage. Matches BytePool::RequiredSize().
#define STK_BYTEPOOL_STORAGE_DECL(name, size_bytes)
 Declare an external storage array for a byte pool, aligned to STK_BYTEPOOL_ALIGN.
#define STK_MEM_MIN_ALIGNMENT   (8U)
 Minimum alignment in bytes guaranteed for pointers returned by stk_mem_allocate() (equals MemoryAllocator::MIN_ALIGNMENT).

Typedefs

typedef struct stk_blockpool_t stk_blockpool_t
 Opaque handle to a stk::memory::BlockMemoryPool instance.
typedef struct stk_bytepool_t stk_bytepool_t
 Opaque handle to a stk::memory::BytePool instance.
typedef struct stk_mem_stats_t stk_mem_stats_t
 Snapshot of allocator statistics.

Functions

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_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.
stk_blockpool_t * stk_blockpool_create_static (size_t capacity, size_t raw_block_size, uint8_t *storage, size_t storage_size, const char *name)
 Create a block pool backed by caller-supplied (external) storage (default alignment).
stk_blockpool_t * stk_blockpool_create_static_ex (size_t capacity, size_t raw_block_size, uint8_t *storage, size_t storage_size, const char *name, size_t alignment)
 Create a block pool backed by caller-supplied storage with an explicit block alignment.
void stk_blockpool_destroy (stk_blockpool_t *pool)
 Destroy a pool and return its slot to the static pool.
void * stk_blockpool_alloc (stk_blockpool_t *pool)
 Allocate one block, blocking indefinitely until one is available.
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.
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.
void * stk_blockpool_try_alloc (stk_blockpool_t *pool)
 Non-blocking allocation attempt.
bool stk_blockpool_free (stk_blockpool_t *pool, void *ptr)
 Return a previously allocated block to the pool.
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.
size_t stk_blockpool_get_capacity (const stk_blockpool_t *pool)
 Get the total block capacity of the pool.
size_t stk_blockpool_get_block_size (const stk_blockpool_t *pool)
 Get the aligned block size used internally by the allocator.
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.
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.
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_WAIT misses).
void stk_blockpool_get_stats (const stk_blockpool_t *pool, stk_mem_stats_t *stats)
 Get a consistent statistics snapshot (bytes: blocks * block size).
bool stk_blockpool_is_full (const stk_blockpool_t *pool)
 Check whether all blocks are currently allocated (pool exhausted).
bool stk_blockpool_is_empty (const stk_blockpool_t *pool)
 Check whether all blocks are free (no outstanding allocations).
stk_bytepool_t * stk_bytepool_create (size_t storage_size, const char *name)
 Create a byte pool backed by heap-allocated storage.
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_bytepool_destroy (stk_bytepool_t *pool)
 Destroy a byte pool and return its slot to the static pool.
void * stk_bytepool_alloc (stk_bytepool_t *pool, size_t size)
 Allocate a block, blocking indefinitely until enough contiguous memory is available.
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.
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.
void * stk_bytepool_try_alloc (stk_bytepool_t *pool, size_t size)
 Non-blocking allocation attempt.
bool stk_bytepool_free (stk_bytepool_t *pool, void *ptr)
 Return a previously allocated block to the pool.
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).
void stk_bytepool_get_stats (const stk_bytepool_t *pool, stk_mem_stats_t *stats)
 Get an O(1) statistics snapshot.
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.
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, STK_NO_WAIT misses and requests larger than stk_bytepool_get_max_request()).
size_t stk_bytepool_get_peak_used_size (const stk_bytepool_t *pool)
 Get the high watermark of pool consumption in bytes (headers included).
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.
size_t stk_bytepool_get_size (const stk_bytepool_t *pool)
 Get the total managed (aligned) area size in bytes, headers included.
size_t stk_bytepool_get_max_request (const stk_bytepool_t *pool)
 Get the largest request that can ever succeed on this pool.
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.
void stk_mem_free (void *ptr)
 Free a chunk obtained with stk_mem_allocate().
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_mem_free_aligned (void *ptr)
 Free a chunk obtained with stk_mem_allocate_aligned().
void stk_mem_get_stats (stk_mem_stats_t *stats)
 Get statistics of the general-purpose allocator.
stk::memory::BlockMemoryPool * stk_blockpool_get_instance (stk_blockpool_t *pool)
 Get the underlying C++ stk::memory::BlockMemoryPool object wrapped by a stk_blockpool_t handle.
stk::memory::BytePool * stk_bytepool_get_instance (stk_bytepool_t *pool)
 Get the underlying C++ stk::memory::BytePool object wrapped by a stk_bytepool_t handle.

Detailed Description

C language bindings for stk::memory::BlockMemoryPool, stk::memory::BytePool and stk::memory::MemoryAllocator.

stk_blockpool_t instances are allocated from a static pool of STK_C_BLOCKPOOL_MAX slots. Obtain a handle with stk_blockpool_create() or stk_blockpool_create_static() and release it with stk_blockpool_destroy().

Two storage modes are exposed, mirroring the C++ class:

Mode Function Who owns storage?
Heap storage stk_blockpool_create() Pool (freed on destroy)
External storage stk_blockpool_create_static() Caller

The _ex variants additionally take an explicit block alignment (cache-line / DMA / SIMD buffers).

For zero-heap deployments, declare a storage buffer with the helper macro STK_BLOCKPOOL_STORAGE_DECL() and pass it to stk_blockpool_create_static():

#define PKT_COUNT 8U
#define PKT_SIZE sizeof(Packet)
STK_BLOCKPOOL_STORAGE_DECL(g_PktStorage, PKT_COUNT, PKT_SIZE);
PKT_COUNT, PKT_SIZE,
(uint8_t *)g_PktStorage, sizeof(g_PktStorage), "pkt_pool");
void ISR_Receiver(void) {
void *blk = stk_blockpool_try_alloc(pool);
if (blk) { FillPacket((Packet *)blk); Queue_Write(blk); }
}
void Task_Parser(void) {
void *blk = NULL;
if (Queue_Read(&blk)) {
Parse((Packet *)blk);
stk_blockpool_free(pool, blk);
}
}
struct stk_blockpool_t stk_blockpool_t
Opaque handle to a stk::memory::BlockMemoryPool instance.
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.
stk_blockpool_t * stk_blockpool_create_static(size_t capacity, size_t raw_block_size, uint8_t *storage, size_t storage_size, const char *name)
Create a block pool backed by caller-supplied (external) storage (default alignment).
#define STK_BLOCKPOOL_STORAGE_DECL(name, capacity, raw_block_size)
Declare a correctly sized and aligned external storage array (default alignment).

stk_bytepool_t (variable-size, first-fit allocator with coalescing) follows the same pattern with STK_C_BYTEPOOL_MAX slots, stk_bytepool_create(), stk_bytepool_create_static() and stk_bytepool_destroy():

stk_bytepool_t *bp = stk_bytepool_create_static((uint8_t *)g_Heap, sizeof(g_Heap), "msg_pool");
void Task_Producer(void) {
char *msg = (char *)stk_bytepool_timed_alloc(bp, 64, stk_ticks_from_ms(100));
if (msg) { Format(msg, 64); Queue_Write(msg); }
}
void Task_Consumer(void) {
void *msg = NULL;
if (Queue_Read(&msg)) { Send((const char *)msg); stk_bytepool_free(bp, msg); }
}
stk_tick_t stk_ticks_from_ms(stk_time_t msec)
Get ticks from milliseconds using current kernel tick resolution.
Definition stk_c.cpp:792
#define STK_BYTEPOOL_REQUIRED_SIZE(payload_size)
Pool space in bytes consumed by one allocation of payload_size bytes (aligned payload,...
bool stk_bytepool_free(stk_bytepool_t *pool, void *ptr)
Return a previously allocated block to the pool.
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.
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.
#define STK_BYTEPOOL_STORAGE_DECL(name, size_bytes)
Declare an external storage array for a byte pool, aligned to STK_BYTEPOOL_ALIGN.

The general-purpose allocator (stk::memory::MemoryAllocator) is exposed through the stk_mem_*() functions.

Note
The STK_MEMORY_* configuration macros (block/byte pool alignment, bitmap, guard word, ...) change the layout and sizing rules of the C++ pools. They are mirrored below with identical defaults and are verified against the C++ classes at compile time in stk_c_memory.cpp. Set them in the build system so that every translation unit (C and C++) sees the same values.

Definition in file stk_c_memory.h.