|
SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
|
Pure C interface for stk::memory::BlockMemoryPool, stk::memory::BytePool and stk::memory::MemoryAllocator. More...
Namespaces | |
| namespace | stk |
| Namespace of STK package. | |
Classes | |
| struct | stk_mem_stats_t |
| Snapshot of allocator statistics. More... | |
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. | |
Pure C interface for stk::memory::BlockMemoryPool, stk::memory::BytePool and stk::memory::MemoryAllocator.
| #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).
Definition at line 178 of file stk_c_memory.h.
Referenced by STK_STATIC_ASSERT_DESC().
| #define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE | ( | raw_size | ) |
Same as STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX() with the default alignment.
Definition at line 193 of file stk_c_memory.h.
| #define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX | ( | raw_size, | |
| align ) |
Compute the internally aligned block size for a given raw byte size and alignment.
Rounds raw_size up to the nearest multiple of align, with a minimum of align. Matches BlockMemoryPool::AlignBlockSize().
Definition at line 185 of file stk_c_memory.h.
| #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().
Definition at line 200 of file stk_c_memory.h.
| #define STK_BLOCKPOOL_STORAGE_DECL | ( | name, | |
| capacity, | |||
| raw_block_size ) |
Declare a correctly sized and aligned external storage array (default alignment).
| name | C identifier for the array variable. |
| capacity | Number of blocks the pool will hold. |
| raw_block_size | Raw per-block size in bytes. |
Definition at line 245 of file stk_c_memory.h.
| #define STK_BLOCKPOOL_STORAGE_DECL_EX | ( | name, | |
| capacity, | |||
| raw_block_size, | |||
| align ) |
Declare a correctly sized storage array aligned to align bytes.
Expands to a static stk_word_t array with the required size (rounded up to whole words) and the requested alignment attribute. Intended for file-scope or function-scope use.
| name | C identifier for the array variable. |
| capacity | Number of blocks the pool will hold. |
| raw_block_size | Raw per-block size in bytes. |
| align | Block alignment in bytes. |
Definition at line 229 of file stk_c_memory.h.
| #define STK_BLOCKPOOL_STORAGE_SIZE | ( | capacity, | |
| raw_block_size ) |
Same as STK_BLOCKPOOL_STORAGE_SIZE_EX() with the default alignment.
Definition at line 217 of file stk_c_memory.h.
| #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().
| capacity | Number of blocks the pool will hold. |
| raw_block_size | Raw per-block size in bytes. |
| align | Block alignment in bytes (power of two, not less than sizeof(void *)). |
Definition at line 211 of file stk_c_memory.h.
| #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).
Definition at line 256 of file stk_c_memory.h.
Referenced by STK_STATIC_ASSERT_DESC().
| #define STK_BYTEPOOL_ALIGN_SIZE | ( | raw_size | ) |
Round raw_size up to the nearest multiple of STK_BYTEPOOL_ALIGN.
Definition at line 272 of file stk_c_memory.h.
| #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).
Definition at line 267 of file stk_c_memory.h.
| #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.
Definition at line 262 of file stk_c_memory.h.
Referenced by STK_STATIC_ASSERT_DESC().
| #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().
Definition at line 281 of file stk_c_memory.h.
| #define STK_BYTEPOOL_STORAGE_DECL | ( | name, | |
| size_bytes ) |
Declare an external storage array for a byte pool, aligned to STK_BYTEPOOL_ALIGN.
Expands to a static uint64_t array (so that the start address is at least 8-byte aligned on every target) with the alignment attribute STK_BYTEPOOL_ALIGN. Use sizeof(name) as the storage_size argument.
| name | C identifier for the array variable. |
| size_bytes | Required pool size in bytes (headers included), e.g. a sum of STK_BYTEPOOL_REQUIRED_SIZE() values. |
Definition at line 293 of file stk_c_memory.h.
| #define STK_C_BLOCKPOOL_MAX (8U) |
Maximum number of concurrent stk_blockpool_t instances (default: 8).
Definition at line 105 of file stk_c_memory.h.
| #define STK_C_BYTEPOOL_MAX (8U) |
Maximum number of concurrent stk_bytepool_t instances (default: 8).
Definition at line 113 of file stk_c_memory.h.
| #define STK_C_MEMORY_DEFAULT_ALLOCATOR (0) |
Selects the implementation of stk::memory::MemoryAllocator provided by the C binding (default: 0).
0: wraps the C library malloc() / free() (the lock hooks of the C library must be implemented, e.g. __malloc_lock for newlib). Statistics are not available (all zero).1: uses the deterministic, ISR-safe allocator on top of a static BytePool (stk_memory_allocator_default.h), heap size is STK_MEMORY_DEFAULT_HEAP_SIZE. STK_MEMORY_NO_HEAP is 1 (no allocator is provided then). Definition at line 126 of file stk_c_memory.h.
| #define STK_MEM_MIN_ALIGNMENT (8U) |
Minimum alignment in bytes guaranteed for pointers returned by stk_mem_allocate() (equals MemoryAllocator::MIN_ALIGNMENT).
Definition at line 782 of file stk_c_memory.h.
Referenced by STK_STATIC_ASSERT_DESC().
| #define STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT (8U) |
Default block alignment of a block pool (see stk_memory_blockpool.h).
Definition at line 140 of file stk_c_memory.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).
Definition at line 149 of file stk_c_memory.h.
| #define STK_MEMORY_BYTEPOOL_ALIGN_DEFAULT (8U) |
Payload alignment of byte pool allocations (see stk_memory_bytepool.h).
Definition at line 159 of file stk_c_memory.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).
Definition at line 167 of file stk_c_memory.h.
| typedef struct stk_blockpool_t stk_blockpool_t |
Opaque handle to a stk::memory::BlockMemoryPool instance.
Definition at line 303 of file stk_c_memory.h.
| typedef struct stk_bytepool_t stk_bytepool_t |
Opaque handle to a stk::memory::BytePool instance.
Definition at line 307 of file stk_c_memory.h.
| typedef struct stk_mem_stats_t stk_mem_stats_t |
Snapshot of allocator statistics.
stk::memory::MemoryAllocator::Stats. Byte counters of pools are in bytes (BlockMemoryPool: blocks * block size; BytePool: used blocks including their headers). | void * stk_blockpool_alloc | ( | stk_blockpool_t * | pool | ) |
Allocate one block, blocking indefinitely until one is available.
| [in] | pool | Pool handle. |
NULL only if the wait was cancelled (via IKernel::CancelTaskWait()) or the pool is invalid (see stk_blockpool_is_storage_valid()); never on timeout. Use stk_blockpool_timed_alloc_ex() to tell these apart. Definition at line 379 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::Alloc(), stk_blockpool_t::handle, stk::hw::IsInsideISR(), and STK_ASSERT.
| 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).
Allocates a flat byte buffer of STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size) bytes (plus alignment slack) via the memory allocator. Call stk_blockpool_is_storage_valid() immediately after creation when operating without exceptions (typical embedded configuration).
| [in] | capacity | Total number of blocks. |
| [in] | raw_block_size | Requested per-block size in bytes. |
| [in] | name | Optional human-readable name (may be NULL). Forwarded to ITraceable::SetTraceName(). |
NULL if the static slot pool is exhausted (STK_C_BLOCKPOOL_MAX reached) or heap support is compiled out (STK_MEMORY_NO_HEAP). A non-NULL handle does not guarantee the backing storage was successfully heap-allocated; always call stk_blockpool_is_storage_valid() immediately after creation when operating without exceptions. Definition at line 313 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::ALIGN_DEFAULT, and stk_blockpool_create_ex().
| 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.
| [in] | capacity | Total number of blocks. |
| [in] | raw_block_size | Requested per-block size in bytes. |
| [in] | name | Optional human-readable name (may be NULL). |
| [in] | alignment | Block alignment in bytes, a power of two not less than sizeof(void *). |
stk_blockpool_create(). An invalid alignment results in an invalid pool (check stk_blockpool_is_storage_valid()). Definition at line 282 of file stk_c_memory.cpp.
References stk::ConstructIn(), STK_ASSERT, and STK_UNUSED.
Referenced by stk_blockpool_create().
| 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).
The pool references storage directly without taking ownership. The caller must keep the buffer alive for the entire lifetime of the pool. The storage is not freed on destruction. A misaligned start address is corrected internally (the unaligned head bytes are not used) and the capacity is trimmed to what fits (asserted in debug builds).
| [in] | capacity | Total number of blocks the pool can hold. |
| [in] | raw_block_size | Requested per-block size in bytes. |
| [in] | storage | Pointer to a caller-owned byte buffer. Should be aligned to STK_BLOCKPOOL_ALIGN and large enough to hold at least STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size) bytes. Asserted at construction time. |
| [in] | storage_size | Size of storage in bytes. |
| [in] | name | Optional human-readable name (may be NULL). |
NULL if the static slot pool is exhausted (STK_C_BLOCKPOOL_MAX reached). Definition at line 347 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::ALIGN_DEFAULT, and stk_blockpool_create_static_ex().
| 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.
| [in] | capacity | Total number of blocks the pool can hold. |
| [in] | raw_block_size | Requested per-block size in bytes. |
| [in] | storage | Caller-owned byte buffer, at least STK_BLOCKPOOL_STORAGE_SIZE_EX(capacity, raw_block_size, alignment) bytes. |
| [in] | storage_size | Size of storage in bytes. |
| [in] | name | Optional human-readable name (may be NULL). |
| [in] | alignment | Block alignment in bytes, a power of two not less than sizeof(void *). |
NULL if the static slot pool is exhausted. Definition at line 318 of file stk_c_memory.cpp.
References stk::ConstructIn(), stk::memory::BlockMemoryPool::RequiredStorageSize(), and STK_ASSERT.
Referenced by stk_blockpool_create_static().
| void stk_blockpool_destroy | ( | stk_blockpool_t * | pool | ) |
Destroy a pool and return its slot to the static pool.
If the pool owns heap storage, it is freed. External storage is never touched.
| [in] | pool | Pool handle obtained via one of the stk_blockpool_create*() functions. |
stk_blockpool_alloc() or stk_blockpool_timed_alloc() is a logic error and triggers an assertion in debug builds. All blocks must be returned before destruction. NULL after this call to prevent accidental use-after-destroy (the handle slot may be reused by a subsequent stk_blockpool_create() call). Definition at line 357 of file stk_c_memory.cpp.
References STK_ASSERT.
| bool stk_blockpool_free | ( | stk_blockpool_t * | pool, |
| void * | ptr ) |
Return a previously allocated block to the pool.
Pushes the block back onto the free-list head in O(1) and wakes exactly one task blocked inside stk_blockpool_alloc() or stk_blockpool_timed_alloc(), if any.
| [in] | pool | Pool handle. |
| [in] | ptr | Pointer previously returned by an allocation function of this pool. Bounds and alignment are validated; failures trigger an assertion in debug builds. |
true on success. false if ptr is NULL, out of range, misaligned or already free (double-free; release-build detection requires STK_MEMORY_BLOCKPOOL_BITMAP) - each case indicates a caller logic error. stk_blockpool_free() to prevent double-free. Definition at line 415 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::Free(), stk_blockpool_t::handle, and STK_ASSERT.
| 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).
| [in] | pool | Pool handle. |
Definition at line 475 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetAllocFailCount(), stk_blockpool_t::handle, and STK_ASSERT.
| size_t stk_blockpool_get_block_alignment | ( | const stk_blockpool_t * | pool | ) |
Get the alignment of every block of the pool.
| [in] | pool | Pool handle. |
Definition at line 447 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetBlockAlignment(), stk_blockpool_t::handle, and STK_ASSERT.
| size_t stk_blockpool_get_block_size | ( | const stk_blockpool_t * | pool | ) |
Get the aligned block size used internally by the allocator.
Equal to STK_BLOCKPOOL_ALIGN_BLOCK_SIZE_EX(raw_block_size, alignment) as passed at construction. Always >= the pool alignment.
| [in] | pool | Pool handle. |
Definition at line 440 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetBlockSize(), stk_blockpool_t::handle, and STK_ASSERT.
| size_t stk_blockpool_get_capacity | ( | const stk_blockpool_t * | pool | ) |
Get the total block capacity of the pool.
| [in] | pool | Pool handle. |
Definition at line 433 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetCapacity(), stk_blockpool_t::handle, and STK_ASSERT.
| size_t stk_blockpool_get_free_count | ( | const stk_blockpool_t * | pool | ) |
Get the number of free (available) blocks.
| [in] | pool | Pool handle. |
Definition at line 461 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetFreeCount(), stk_blockpool_t::handle, and STK_ASSERT.
| 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.
| [in] | pool | Pool handle obtained via stk_blockpool_create*(). |
stk::memory::BlockMemoryPool instance. Never NULL for a valid handle. __cplusplus); not part of the C ABI. Definition at line 503 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, and STK_ASSERT.
| 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.
Run your worst-case workload and use this value to size the pool.
| [in] | pool | Pool handle. |
Definition at line 468 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetPeakUsedCount(), stk_blockpool_t::handle, and STK_ASSERT.
| void stk_blockpool_get_stats | ( | const stk_blockpool_t * | pool, |
| stk_mem_stats_t * | stats ) |
Get a consistent statistics snapshot (bytes: blocks * block size).
| [in] | pool | Pool handle. |
| [out] | stats | Receives the snapshot. Must not be NULL. |
Definition at line 482 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetStats(), stk_blockpool_t::handle, and STK_ASSERT.
| size_t stk_blockpool_get_used_count | ( | const stk_blockpool_t * | pool | ) |
Get the number of currently allocated (outstanding) blocks.
| [in] | pool | Pool handle. |
Definition at line 454 of file stk_c_memory.cpp.
References stk::memory::BlockMemoryPool::GetUsedCount(), stk_blockpool_t::handle, and STK_ASSERT.
| bool stk_blockpool_is_empty | ( | const stk_blockpool_t * | pool | ) |
Check whether all blocks are free (no outstanding allocations).
| [in] | pool | Pool handle. |
true if no blocks are currently allocated. Definition at line 496 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, stk::memory::BlockMemoryPool::IsEmpty(), and STK_ASSERT.
| bool stk_blockpool_is_full | ( | const stk_blockpool_t * | pool | ) |
Check whether all blocks are currently allocated (pool exhausted).
| [in] | pool | Pool handle. |
true if no blocks are available for allocation. Definition at line 489 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, stk::memory::BlockMemoryPool::IsFull(), and STK_ASSERT.
| 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.
Always true for pools created with a sufficiently large external buffer. For heap-constructed pools, false if the heap allocation failed. false as well if the arguments were invalid or the buffer is too small for a single block.
| [in] | pool | Pool handle. |
true if the pool is ready for use. Definition at line 426 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, stk::memory::BlockMemoryPool::IsStorageValid(), and STK_ASSERT.
| 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.
| [in] | pool | Pool handle. |
| [in] | timeout | Maximum time to wait in OS ticks. Pass STK_WAIT_INFINITE to block indefinitely (same as stk_blockpool_alloc()), or STK_NO_WAIT for a non-blocking attempt identical to stk_blockpool_try_alloc(). |
NULL if the timeout expired before a block became available, the wait was cancelled or the pool is invalid. stk_blockpool_timed_alloc_ex() to tell them apart. stk_ticks_from_ms() to convert a millisecond value to ticks for best portability across different tick rates. STK_NO_WAIT; not ISR-safe otherwise. Definition at line 389 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, STK_ASSERT, and stk::memory::BlockMemoryPool::TimedAlloc().
| 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.
| [in] | pool | Pool handle. |
| [out] | block | Receives the allocated block on STK_WAIT_RESULT_SIGNAL, NULL on any other result. Must not be NULL. |
| [in] | timeout | Maximum time to wait in OS ticks (see stk_blockpool_timed_alloc()). |
STK_WAIT_RESULT_SIGNAL - a block was allocated, STK_WAIT_RESULT_TIMEOUT - no block became available before the timeout (or STK_NO_WAIT on an empty pool), STK_WAIT_RESULT_CANCELED - the wait was cancelled, nothing was allocated, STK_WAIT_RESULT_FAIL - invalid arguments, invalid pool or the kernel rejected the wait. STK_NO_WAIT; not ISR-safe otherwise. Definition at line 396 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, STK_ASSERT, and stk::memory::BlockMemoryPool::TimedAllocEx().
| void * stk_blockpool_try_alloc | ( | stk_blockpool_t * | pool | ) |
Non-blocking allocation attempt.
Returns a block immediately if one is available, or NULL if the pool is empty. Never suspends the calling task.
| [in] | pool | Pool handle. |
NULL if the pool is empty. Definition at line 404 of file stk_c_memory.cpp.
References stk_blockpool_t::handle, STK_ASSERT, and stk::memory::BlockMemoryPool::TryAlloc().
| void * stk_bytepool_alloc | ( | stk_bytepool_t * | pool, |
| size_t | size ) |
Allocate a block, blocking indefinitely until enough contiguous memory is available.
| [in] | pool | Pool handle. |
| [in] | size | Requested payload size in bytes (> 0 and <= stk_bytepool_get_max_request()). |
STK_BYTEPOOL_ALIGN, or NULL if the request is invalid (zero, larger than the pool) or the wait was cancelled. Never returns NULL because of a timeout. Definition at line 589 of file stk_c_memory.cpp.
References stk::memory::BytePool::Alloc(), stk_bytepool_t::handle, stk::hw::IsInsideISR(), and STK_ASSERT.
| stk_bytepool_t * stk_bytepool_create | ( | size_t | storage_size, |
| const char * | name ) |
Create a byte pool backed by heap-allocated storage.
Allocates storage_size bytes (plus alignment slack) via the memory allocator. The size includes block headers (see STK_BYTEPOOL_REQUIRED_SIZE()). Call stk_bytepool_is_storage_valid() immediately after creation when operating without exceptions.
| [in] | storage_size | Size of the pool area in bytes (headers included). |
| [in] | name | Optional human-readable name (may be NULL). |
NULL if the static slot pool is exhausted (STK_C_BYTEPOOL_MAX reached) or heap support is compiled out (STK_MEMORY_NO_HEAP). A non-NULL handle does not guarantee that the heap allocation succeeded; check stk_bytepool_is_storage_valid(). Definition at line 518 of file stk_c_memory.cpp.
References stk::memory::BytePool::BLOCK_ALIGN, stk::ConstructIn(), stk::memory::BytePool::HEADER_SIZE, STK_ASSERT, and STK_UNUSED.
| 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.
The pool references storage directly without taking ownership. The caller must keep the buffer alive for the entire lifetime of the pool. A misaligned start address is corrected internally (unaligned head/tail bytes are unused).
| [in] | storage | Pointer to a caller-owned byte buffer, preferably aligned to STK_BYTEPOOL_ALIGN (see STK_BYTEPOOL_STORAGE_DECL()). |
| [in] | storage_size | Size of storage in bytes. Must be at least STK_BYTEPOOL_HEADER_SIZE + STK_BYTEPOOL_ALIGN (asserted). |
| [in] | name | Optional human-readable name (may be NULL). |
NULL if the static slot pool is exhausted (STK_C_BYTEPOOL_MAX reached). Definition at line 544 of file stk_c_memory.cpp.
References stk::memory::BytePool::BLOCK_ALIGN, stk::ConstructIn(), stk::memory::BytePool::HEADER_SIZE, and STK_ASSERT.
| void stk_bytepool_destroy | ( | stk_bytepool_t * | pool | ) |
Destroy a byte pool and return its slot to the static pool.
Heap storage is freed if owned. External storage is never touched.
| [in] | pool | Handle obtained via stk_bytepool_create() or stk_bytepool_create_static(). |
stk_bytepool_alloc() or stk_bytepool_timed_alloc() is a logic error. All blocks must be returned before destruction. NULL after this call; the slot may be reused. Definition at line 567 of file stk_c_memory.cpp.
References STK_ASSERT.
| bool stk_bytepool_free | ( | stk_bytepool_t * | pool, |
| void * | ptr ) |
Return a previously allocated block to the pool.
Marks the block free, merges it with following free blocks and wakes all tasks blocked in stk_bytepool_alloc() / stk_bytepool_timed_alloc().
| [in] | pool | Pool handle. |
| [in] | ptr | Pointer previously returned by an allocation function of this pool. |
true on success; false if ptr is NULL, outside the pool, misaligned, not in use (double-free) or - with STK_MEMORY_BYTEPOOL_GUARD - its guard word was overwritten (the block is kept, i.e. leaked, to protect the pool metadata). stk_bytepool_free() to prevent double-free. Definition at line 625 of file stk_c_memory.cpp.
References stk::memory::BytePool::Free(), stk_bytepool_t::handle, and STK_ASSERT.
| 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()).
| [in] | pool | Pool handle. |
Definition at line 668 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetAllocFailCount(), stk_bytepool_t::handle, and STK_ASSERT.
| 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).
| [in] | pool | Pool handle. |
| [out] | available | Total allocatable payload bytes over all free fragments (may be NULL). |
| [out] | largest | Payload size of the largest free fragment, i.e. the biggest request that would succeed right now (may be NULL). |
| [out] | fragments | Number of free fragments; 1 means no external fragmentation (may be NULL). |
stk_bytepool_get_stats() for an O(1) alternative. Definition at line 636 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetInfo(), stk_bytepool_t::handle, and STK_ASSERT.
| 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.
| [in] | pool | Pool handle obtained via stk_bytepool_create() or stk_bytepool_create_static(). |
stk::memory::BytePool instance. Never NULL for a valid handle. __cplusplus); not part of the C ABI. Definition at line 703 of file stk_c_memory.cpp.
References stk_bytepool_t::handle, and STK_ASSERT.
| size_t stk_bytepool_get_max_request | ( | const stk_bytepool_t * | pool | ) |
Get the largest request that can ever succeed on this pool.
| [in] | pool | Pool handle. |
Definition at line 696 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetMaxRequest(), stk_bytepool_t::handle, and STK_ASSERT.
| 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.
The walk is executed inside a critical section, so this measures the worst-case time interrupts/scheduling were blocked by the allocator.
| [in] | pool | Pool handle. |
Definition at line 661 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetMaxScanLength(), stk_bytepool_t::handle, and STK_ASSERT.
| size_t stk_bytepool_get_peak_used_size | ( | const stk_bytepool_t * | pool | ) |
Get the high watermark of pool consumption in bytes (headers included).
| [in] | pool | Pool handle. |
Definition at line 675 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetPeakUsedSize(), stk_bytepool_t::handle, and STK_ASSERT.
| size_t stk_bytepool_get_size | ( | const stk_bytepool_t * | pool | ) |
Get the total managed (aligned) area size in bytes, headers included.
| [in] | pool | Pool handle. |
Definition at line 689 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetSize(), stk_bytepool_t::handle, and STK_ASSERT.
| void stk_bytepool_get_stats | ( | const stk_bytepool_t * | pool, |
| stk_mem_stats_t * | stats ) |
Get an O(1) statistics snapshot.
capacity is the managed area size and allocated the bytes held by used blocks, both including headers (the real pool consumption).
| [in] | pool | Pool handle. |
| [out] | stats | Receives the snapshot. Must not be NULL. |
Definition at line 654 of file stk_c_memory.cpp.
References stk::memory::BytePool::GetStats(), stk_bytepool_t::handle, and STK_ASSERT.
| 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.
| [in] | pool | Pool handle. |
true if the pool is ready; false if heap allocation failed or the supplied area is too small for even one block. Definition at line 682 of file stk_c_memory.cpp.
References stk_bytepool_t::handle, stk::memory::BytePool::IsStorageValid(), and STK_ASSERT.
| 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.
The timeout is a total budget, not per wake-up.
| [in] | pool | Pool handle. |
| [in] | size | Requested payload size in bytes. |
| [in] | timeout | Maximum time to wait in OS ticks. STK_WAIT_INFINITE blocks indefinitely; STK_NO_WAIT is identical to stk_bytepool_try_alloc(). |
NULL on timeout, cancellation or invalid arguments. Use stk_bytepool_timed_alloc_ex() to tell them apart. STK_NO_WAIT. Definition at line 599 of file stk_c_memory.cpp.
References stk_bytepool_t::handle, STK_ASSERT, and stk::memory::BytePool::TimedAlloc().
| 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.
| [in] | pool | Pool handle. |
| [out] | block | Receives the allocated block on STK_WAIT_RESULT_SIGNAL, NULL on any other result. Must not be NULL. |
| [in] | size | Requested payload size in bytes. |
| [in] | timeout | Maximum time to wait in OS ticks (see stk_bytepool_timed_alloc()). |
STK_WAIT_RESULT_SIGNAL - a block was allocated (immediately or after waiting), STK_WAIT_RESULT_TIMEOUT - no suitable block became available before the timeout (or STK_NO_WAIT was passed), STK_WAIT_RESULT_CANCELED - the wait was cancelled, STK_WAIT_RESULT_FAIL - invalid arguments (block is NULL, size is 0 or exceeds stk_bytepool_get_max_request(), no valid storage) or the kernel rejected the wait. STK_NO_WAIT. Definition at line 606 of file stk_c_memory.cpp.
References stk_bytepool_t::handle, STK_ASSERT, and stk::memory::BytePool::TimedAllocEx().
| void * stk_bytepool_try_alloc | ( | stk_bytepool_t * | pool, |
| size_t | size ) |
Non-blocking allocation attempt.
| [in] | pool | Pool handle. |
| [in] | size | Requested payload size in bytes. |
NULL if no suitable free block exists. Definition at line 614 of file stk_c_memory.cpp.
References stk_bytepool_t::handle, STK_ASSERT, and stk::memory::BytePool::TryAlloc().
| void * stk_mem_allocate | ( | size_t | size | ) |
Allocate a memory chunk from the general-purpose allocator.
| [in] | size | Size in bytes. |
STK_MEM_MIN_ALIGNMENT, or NULL on failure (or if size is 0). STK_C_MEMORY_DEFAULT_ALLOCATOR = 1. Definition at line 723 of file stk_c_memory.cpp.
References stk::memory::MemoryAllocator::Allocate(), and stk_mem_is_available().
| void * stk_mem_allocate_aligned | ( | size_t | size, |
| size_t | alignment ) |
Allocate a chunk with an alignment stricter than STK_MEM_MIN_ALIGNMENT.
The result must be released with stk_mem_free_aligned(), never with stk_mem_free().
| [in] | size | Size in bytes. |
| [in] | alignment | Required alignment, a power of two. |
NULL on failure, if alignment is not a power of two or heap support is compiled out. Definition at line 743 of file stk_c_memory.cpp.
References stk::memory::MemoryAllocator::AllocateAligned(), and STK_UNUSED.
| void stk_mem_free | ( | void * | ptr | ) |
Free a chunk obtained with stk_mem_allocate().
| [in] | ptr | Pointer to the chunk. NULL is allowed and results in noop. |
STK_C_MEMORY_DEFAULT_ALLOCATOR = 1. Definition at line 735 of file stk_c_memory.cpp.
References stk::memory::MemoryAllocator::Free(), and stk_mem_is_available().
| void stk_mem_free_aligned | ( | void * | ptr | ) |
Free a chunk obtained with stk_mem_allocate_aligned().
| [in] | ptr | Pointer returned by stk_mem_allocate_aligned(). NULL is allowed and results in noop. |
Definition at line 757 of file stk_c_memory.cpp.
References stk::memory::MemoryAllocator::FreeAligned(), and STK_UNUSED.
| void stk_mem_get_stats | ( | stk_mem_stats_t * | stats | ) |
Get statistics of the general-purpose allocator.
| [out] | stats | Receives the snapshot. Must not be NULL. All zero if the implementation does not provide statistics (STK_C_MEMORY_DEFAULT_ALLOCATOR = 0). |
Definition at line 766 of file stk_c_memory.cpp.
References stk::memory::MemoryAllocator::GetStats(), STK_ASSERT, and stk_mem_is_available().
| bool stk_mem_is_available | ( | void | ) |
Check that the memory allocator implementation is linked in.
true if allocation functions are available (always true unless STK_MEMORY_NO_HEAP is 1). Definition at line 714 of file stk_c_memory.cpp.
References stk::memory::MemoryAllocator::IsAvailable().
Referenced by stk_mem_allocate(), stk_mem_free(), and stk_mem_get_stats().