STK C Memory API

Pure C interface for stk::memory::BlockMemoryPool. More...

Macros
#define	STK_C_BLOCKPOOL_MAX   (8U)
	Maximum number of concurrent stk_blockpool_t instances (default: 8).
#define	STK_BLOCKPOOL_ALIGN   (sizeof(stk_word_t))
	Required storage alignment in bytes (equals sizeof(void*)).
#define	STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(raw_size)
	Compute the internally aligned block size for a given raw byte size.
#define	STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size)
	Compute the minimum external storage buffer size in bytes.
#define	STK_BLOCKPOOL_STORAGE_DECL(name, capacity, raw_block_size)
	Declare a correctly sized and aligned external storage array.

Typedefs
typedef struct stk_blockpool_t	stk_blockpool_t
	Opaque handle to a stk::memory::BlockMemoryPool instance.

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.
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.
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.
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_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.
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).

Detailed Description

Pure C interface for stk::memory::BlockMemoryPool.

Macro Definition Documentation

STK_BLOCKPOOL_ALIGN

#define STK_BLOCKPOOL_ALIGN   (sizeof(stk_word_t))

Required storage alignment in bytes (equals sizeof(void*)).

Definition at line 84 of file stk_c_memory.h.

STK_BLOCKPOOL_ALIGN_BLOCK_SIZE

#define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE

(

raw_size

)

Value:

(((raw_size) < STK_BLOCKPOOL_ALIGN) \
    ? STK_BLOCKPOOL_ALIGN \
    : (((raw_size) + (STK_BLOCKPOOL_ALIGN - 1U)) & ~(STK_BLOCKPOOL_ALIGN - 1U)))

Compute the internally aligned block size for a given raw byte size.

Rounds raw_size up to the nearest multiple of STK_BLOCKPOOL_ALIGN, with a minimum of STK_BLOCKPOOL_ALIGN. Use this at compile time to size external storage buffers correctly.

Definition at line 92 of file stk_c_memory.h.

#define STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(raw_size) \
    (((raw_size) < STK_BLOCKPOOL_ALIGN) \
        ? STK_BLOCKPOOL_ALIGN \
        : (((raw_size) + (STK_BLOCKPOOL_ALIGN - 1U)) & ~(STK_BLOCKPOOL_ALIGN - 1U)))

STK_BLOCKPOOL_STORAGE_DECL

#define STK_BLOCKPOOL_STORAGE_DECL	(		name,
			capacity,
			raw_block_size )

Value:

static stk_word_t name[STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size) / sizeof(stk_word_t)]

Declare a correctly sized and aligned external storage array.

Expands to a static stk_word_t array with the required size and pointer-sized alignment. Intended for file-scope or function-scope use. STK_BLOCKPOOL_ALIGN_BLOCK_SIZE() guarantees the total byte count is always an exact multiple of sizeof(stk_word_t), so the integer division in the array dimension is lossless by construction.

Parameters

name	C identifier for the array variable.
capacity	Number of blocks the pool will hold.
raw_block_size	Raw per-block size in bytes.

STK_BLOCKPOOL_STORAGE_DECL(g_BufStorage, 16, sizeof(MyBuf));
stk_blockpool_t *pool = stk_blockpool_create_static(
    16, sizeof(MyBuf), g_BufStorage, sizeof(g_BufStorage), NULL);

Definition at line 122 of file stk_c_memory.h.

#define STK_BLOCKPOOL_STORAGE_DECL(name, capacity, raw_block_size) \
    static stk_word_t name[STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size) / sizeof(stk_word_t)]

STK_BLOCKPOOL_STORAGE_SIZE

#define STK_BLOCKPOOL_STORAGE_SIZE	(		capacity,
			raw_block_size )

Value:

((capacity) * STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(raw_block_size))

Compute the minimum external storage buffer size in bytes.

Parameters

capacity	Number of blocks the pool will hold.
raw_block_size	Raw per-block size in bytes.

Definition at line 102 of file stk_c_memory.h.

#define STK_BLOCKPOOL_STORAGE_SIZE(capacity, raw_block_size) \
    ((capacity) * STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(raw_block_size))

STK_C_BLOCKPOOL_MAX

#define STK_C_BLOCKPOOL_MAX   (8U)

Maximum number of concurrent stk_blockpool_t instances (default: 8).

Note

Increase if your application needs more simultaneous pools.

Definition at line 74 of file stk_c_memory.h.

Referenced by AcquireSlot(), and FindSlot().

Typedef Documentation

stk_blockpool_t

typedef struct stk_blockpool_t stk_blockpool_t

Opaque handle to a stk::memory::BlockMemoryPool instance.

Definition at line 131 of file stk_c_memory.h.

Function Documentation

stk_blockpool_alloc()

void * stk_blockpool_alloc

(

stk_blockpool_t *

pool

)

Allocate one block, blocking indefinitely until one is available.

Parameters

[in]

pool

Pool handle.

Returns

Pointer to an uninitialized block of at least raw_block_size bytes. Never returns NULL.

Warning

Not ISR-safe.

Definition at line 208 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
    // stk_blockpool_alloc() blocks indefinitely and must never be called from an ISR.
    // Use stk_blockpool_try_alloc() or stk_blockpool_timed_alloc(..., STK_NO_WAIT) instead.
    STK_ASSERT(!hw::IsInsideISR());
 
    return pool->handle.Alloc();
}

References stk::memory::BlockMemoryPool::Alloc(), stk_blockpool_t::handle, stk::hw::IsInsideISR(), and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_create()

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.

Allocates a flat byte buffer of capacity * AlignBlockSize(raw_block_size) bytes from the heap. Call stk_blockpool_is_storage_valid() immediately after creation when operating without exceptions (typical embedded configuration).

Parameters

[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().

Returns

Pool handle, or NULL if the static slot pool is exhausted (STK_C_BLOCKPOOL_MAX reached). 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.

Note

Not ISR-safe.

See also

stk_blockpool_is_storage_valid(), stk_blockpool_destroy()

Definition at line 137 of file stk_c_memory.cpp.

{
    STK_ASSERT(capacity > 0U);
    STK_ASSERT(raw_block_size > 0U);
 
    const sync::ScopedCriticalSection cs_;
 
    BlockPoolSlot *const slot = AcquireSlot();
 
    // pool exhausted — increase STK_C_BLOCKPOOL_MAX
    STK_ASSERT(slot != nullptr);
 
    stk_blockpool_t *result = nullptr;
    if (slot != nullptr)
    {
        result = new (slot->storage) stk_blockpool_t(capacity, raw_block_size, name);
    }
 
    return result;
}

References AcquireSlot(), STK_ASSERT, and BlockPoolSlot::storage.

Here is the call graph for this function:

stk_blockpool_create_static()

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.

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.

Parameters

[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. Must be aligned to at least sizeof(void*) 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 (used for the size assertion).
[in]	name	Optional human-readable name (may be NULL).

Returns

Pool handle, or NULL if the static slot pool is exhausted (STK_C_BLOCKPOOL_MAX reached).

Note

Not ISR-safe.

See also

stk_blockpool_destroy()

Definition at line 158 of file stk_c_memory.cpp.

{
    STK_ASSERT(capacity > 0U);
    STK_ASSERT(raw_block_size > 0U);
    STK_ASSERT(storage_ptr != nullptr);
    STK_ASSERT(storage_size >= (capacity * BlockMemoryPool::AlignBlockSize(raw_block_size)));
 
    const sync::ScopedCriticalSection cs_;
 
    BlockPoolSlot *const slot = AcquireSlot();
 
    // pool exhausted — increase STK_C_BLOCKPOOL_MAX
    STK_ASSERT(slot != nullptr);
 
    stk_blockpool_t *result = nullptr;
    if (slot != nullptr)
    {
        result = new (slot->storage) stk_blockpool_t(capacity, raw_block_size,
                                                     storage_ptr, storage_size, name);
    }
 
    return result;
}

References AcquireSlot(), stk::memory::BlockMemoryPool::AlignBlockSize(), STK_ASSERT, and BlockPoolSlot::storage.

Here is the call graph for this function:

stk_blockpool_destroy()

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.

Parameters

[in]

pool

Pool handle obtained via stk_blockpool_create() or stk_blockpool_create_static().

Warning

Destroying a pool while tasks are blocked in stk_blockpool_alloc() or stk_blockpool_timed_alloc() is a logic error and triggers an assertion in debug builds.

Set the pool pointer to NULL after this call to prevent accidental use-after-destroy (the handle slot may be reused by a subsequent stk_blockpool_create() call).

Note

Not ISR-safe.

Definition at line 186 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    const sync::ScopedCriticalSection cs_;
 
    BlockPoolSlot *const slot = FindSlot(pool);
 
    // pool not found: double-destroy or corruption
    STK_ASSERT(slot != nullptr);
    if (slot != nullptr)
    {
        // Explicitly run the destructor (frees heap storage if owned).
        pool->~stk_blockpool_t();
        slot->busy = false;
    }
}

References BlockPoolSlot::busy, FindSlot(), and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_free()

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.

Parameters

[in]	pool	Pool handle.
[in]	ptr	Pointer previously returned by stk_blockpool_alloc(), stk_blockpool_timed_alloc(), or stk_blockpool_try_alloc(). Must belong to pool. Bounds and alignment are validated; failures trigger an assertion in debug builds.

Returns

true on success. false if ptr is NULL, out of range, or misaligned - each case indicates a caller logic error.

Note

ISR-safe.

Warning

Null the pointer after stk_blockpool_free() to prevent double-free.

Definition at line 236 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.Free(ptr);
}

References stk::memory::BlockMemoryPool::Free(), stk_blockpool_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_get_block_size()

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(raw_block_size) as passed at construction. Always >= STK_BLOCKPOOL_ALIGN.

Parameters

[in]

pool

Pool handle.

Returns

Aligned block size in bytes.

Note

ISR-safe.

Definition at line 261 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.GetBlockSize();
}

References stk::memory::BlockMemoryPool::GetBlockSize(), stk_blockpool_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_get_capacity()

size_t stk_blockpool_get_capacity

(

const stk_blockpool_t *

pool

)

Get the total block capacity of the pool.

Parameters

[in]

pool

Pool handle.

Returns

Maximum number of blocks that can be simultaneously allocated.

Note

ISR-safe.

Definition at line 254 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.GetCapacity();
}

References stk::memory::BlockMemoryPool::GetCapacity(), stk_blockpool_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_get_free_count()

size_t stk_blockpool_get_free_count

(

const stk_blockpool_t *

pool

)

Get the number of free (available) blocks.

Parameters

[in]

pool

Pool handle.

Returns

Point-in-time snapshot of capacity - used_count.

Note

ISR-safe.

Definition at line 275 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.GetFreeCount();
}

References stk::memory::BlockMemoryPool::GetFreeCount(), stk_blockpool_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_get_used_count()

size_t stk_blockpool_get_used_count

(

const stk_blockpool_t *

pool

)

Get the number of currently allocated (outstanding) blocks.

Parameters

[in]

pool

Pool handle.

Returns

Point-in-time snapshot. May be stale immediately after return in a multi-task environment.

Note

ISR-safety depends on target ABI: the counter is a 16-bit value, so a single-instruction atomic read is guaranteed on 32-bit Cortex-M (aligned halfword load) but not on 8-bit targets where two bus cycles may be needed. Treat the result as advisory in all multi-core or 8-bit contexts.

Definition at line 268 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.GetUsedCount();
}

References stk::memory::BlockMemoryPool::GetUsedCount(), stk_blockpool_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_is_empty()

bool stk_blockpool_is_empty

(

const stk_blockpool_t *

pool

)

Check whether all blocks are free (no outstanding allocations).

Parameters

[in]

pool

Pool handle.

Returns

true if no blocks are currently allocated.

Note

ISR-safe.

Definition at line 289 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.IsEmpty();
}

References stk_blockpool_t::handle, stk::memory::BlockMemoryPool::IsEmpty(), and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_is_full()

bool stk_blockpool_is_full

(

const stk_blockpool_t *

pool

)

Check whether all blocks are currently allocated (pool exhausted).

Parameters

[in]

pool

Pool handle.

Returns

true if no blocks are available for allocation.

Note

ISR-safe.

Definition at line 282 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.IsFull();
}

References stk_blockpool_t::handle, stk::memory::BlockMemoryPool::IsFull(), and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_is_storage_valid()

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 stk_blockpool_create_static(). For heap-constructed pools (stk_blockpool_create()), false if operator new failed. Must be checked after heap construction when operating without exceptions.

Parameters

[in]

pool

Pool handle.

Returns

true if the pool is ready for use.

Note

ISR-safe.

Definition at line 247 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.IsStorageValid();
}

References stk_blockpool_t::handle, stk::memory::BlockMemoryPool::IsStorageValid(), and STK_ASSERT.

Here is the call graph for this function:

stk_blockpool_timed_alloc()

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.

Parameters

[in]	pool	Pool handle.
[in]	timeout	Maximum time to wait in 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().

Returns

Pointer to an uninitialized block, or NULL if the timeout expired before a block became available.

Warning

ISR-safe only when timeout = STK_NO_WAIT; not ISR-safe otherwise.

Definition at line 218 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.TimedAlloc(timeout);
}

References stk_blockpool_t::handle, STK_ASSERT, and stk::memory::BlockMemoryPool::TimedAlloc().

Here is the call graph for this function:

stk_blockpool_try_alloc()

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.

Parameters

[in]

pool

Pool handle.

Returns

Pointer to an uninitialized block, or NULL if the pool is empty.

Note

ISR-safe.

Definition at line 225 of file stk_c_memory.cpp.

{
    STK_ASSERT(pool != nullptr);
 
    return pool->handle.TryAlloc();
}

References stk_blockpool_t::handle, STK_ASSERT, and stk::memory::BlockMemoryPool::TryAlloc().

Here is the call graph for this function: