|
SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
|
C language bindings for stk::memory::BlockMemoryPool, stk::memory::BytePool and stk::memory::MemoryAllocator. More...
#include "stk_c.h"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. | |
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():
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():
The general-purpose allocator (stk::memory::MemoryAllocator) is exposed through the stk_mem_*() functions.
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.