stk_c_memory.h File Reference

C language binding for stk::memory::BlockMemoryPool. 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.

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

C language binding for stk::memory::BlockMemoryPool.

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

For zero-heap deployments, declare a storage buffer with the helper macro STK_BLOCKPOOL_STORAGE_SIZE() 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);
 
stk_blockpool_t *pool = stk_blockpool_create_static(
    PKT_COUNT, PKT_SIZE,
    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);
    }
}

Definition in file stk_c_memory.h.