Skip to content

ssfmpool.md

Latest commit

 

History

History
395 lines (260 loc) · 12 KB

ssfmpool.md

File metadata and controls

395 lines (260 loc) · 12 KB

ssfmpool — Memory Pool Interface

SSF | Data Structures

Fixed-size block memory pool for deterministic O(1) allocation without fragmentation.

All blocks are allocated from the system heap once during SSFMPoolInit(). Every subsequent SSFMPoolAlloc() and SSFMPoolFree() call is O(1) and involves no further heap interaction. Each block is guarded by a canary value that detects buffer overruns at free time.

Dependencies | Notes | Configuration | API Summary | Function Reference

↑ Dependencies

↑ Notes

  • SSFMPoolAlloc() asserts (never returns NULL) if the pool is empty; check SSFMPoolIsEmpty() before calling.
  • SSFMPoolAlloc() asserts if size exceeds blockSize; pass sizeof your struct or a compile-time constant ≤ blockSize.
  • SSFMPoolFree() returns NULL; assign the return value to null the caller's pointer: ptr = (MyType_t *)SSFMPoolFree(&pool, ptr).
  • SSFMPoolDeInit() asserts if any blocks are still allocated; free all blocks first.
  • Each block carries a 3-byte canary; SSFMPoolFree() verifies it to detect overruns.
  • When SSF_MPOOL_DEBUG is 1, each block records its owner tag to aid leak analysis.
  • All blocks are the same size; allocating a struct smaller than blockSize is allowed but wastes the remainder.

↑ Configuration

All options are set in ssfoptions.h.

Option Default Description
SSF_MPOOL_DEBUG 0 1 to enable a debug structure that tracks all blocks and their owner tags

↑ API Summary

Definitions

Symbol Kind Description
SSFMPool_t Struct Pool instance; pass by pointer to all API functions. Do not access fields directly.

Functions

Function / Macro Description
e.g. void SSFMPoolInit(pool, blocks, blockSize) Initialize a memory pool
e.g. void SSFMPoolDeInit(pool) De-initialize a memory pool
e.g. void *SSFMPoolAlloc(pool, size, owner) Allocate a block from the pool
e.g. void *SSFMPoolFree(pool, ptr) Free a block back to the pool
e.g. uint32_t SSFMPoolBlockSize(pool) Returns the fixed block size in bytes
e.g. uint32_t SSFMPoolSize(pool) Returns the total number of blocks in the pool
e.g. uint32_t SSFMPoolLen(pool) Returns the number of free blocks remaining
e.g. bool SSFMPoolIsEmpty(pool) Returns true if no free blocks remain
e.g. bool SSFMPoolIsFull(pool) Returns true if all blocks are free

↑ Function Reference

↑ void SSFMPoolInit()

void SSFMPoolInit(SSFMPool_t *pool, uint32_t blocks, uint32_t blockSize);

Initializes a memory pool by allocating blocks blocks of blockSize bytes each from the system heap. The pool thereafter provides O(1) allocation and deallocation with no further heap calls. Each block is zero-initialized and guarded by a canary value. The pool must not already be initialized; asserting otherwise.

Parameter Direction Type Description
pool out SSFMPool_t * Pointer to the pool structure to initialize. Must not be NULL. Must not already be initialized.
blocks in uint32_t Number of blocks to allocate. Must be greater than 0.
blockSize in uint32_t Size of each block in bytes. Must be greater than 0.

Returns: Nothing. Asserts if malloc fails.

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
/* pool holds 4 blocks of sizeof(MyMsg_t) bytes each */

↑ void SSFMPoolDeInit()

void SSFMPoolDeInit(SSFMPool_t *pool);

De-initializes the memory pool, freeing all block memory back to the system heap. All allocated blocks must have been freed before calling; asserting otherwise.

Parameter Direction Type Description
pool in-out SSFMPool_t * Pointer to an initialized pool with all blocks returned. Must not be NULL.

Returns: Nothing.

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
SSFMPoolDeInit(&pool);
/* pool is no longer valid */

↑ void *SSFMPoolAlloc()

void *SSFMPoolAlloc(SSFMPool_t *pool, uint32_t size, uint8_t owner);

Allocates one block from the pool and returns a pointer to it. The size argument is validated against the pool's blockSize; it must not exceed blockSize. The block is not zeroed on allocation. The owner tag is stored in the block's canary area to aid leak analysis when SSF_MPOOL_DEBUG is 1.

Parameter Direction Type Description
pool in-out SSFMPool_t * Pointer to an initialized pool. Must not be NULL. Must not be empty.
size in uint32_t Requested allocation size in bytes. Must not exceed the pool's blockSize.
owner in uint8_t Tag identifying the allocating code path. Stored in the block header regardless of SSF_MPOOL_DEBUG.

Returns: Pointer to the allocated block. Asserts if the pool is empty or size > blockSize.

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;
MyMsg_t *msg;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));

if (SSFMPoolIsEmpty(&pool) == false)
{
    msg = (MyMsg_t *)SSFMPoolAlloc(&pool, sizeof(MyMsg_t), 0x01u);
    msg->id = 42u;
    /* pool has 3 free blocks */
}

↑ void *SSFMPoolFree()

void *SSFMPoolFree(SSFMPool_t *pool, void *ptr);

Returns a previously allocated block back to the pool. The canary value is verified before returning the block; asserting on corruption or overrun. After this call the pointer is invalid. Returns NULL to enable the nulling pattern ptr = SSFMPoolFree(&pool, ptr).

Parameter Direction Type Description
pool in-out SSFMPool_t * Pointer to the pool the block was allocated from. Must not be NULL.
ptr in void * Pointer to the block to free. Must not be NULL. Must have been returned by SSFMPoolAlloc() on this pool.

Returns: Always NULL.

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;
MyMsg_t *msg;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
msg = (MyMsg_t *)SSFMPoolAlloc(&pool, sizeof(MyMsg_t), 0x01u);

msg = (MyMsg_t *)SSFMPoolFree(&pool, msg);
/* msg == NULL; pool has 4 free blocks */

↑ uint32_t SSFMPoolBlockSize()

uint32_t SSFMPoolBlockSize(const SSFMPool_t *pool);

Returns the fixed block size of the pool.

Parameter Direction Type Description
pool in const SSFMPool_t * Pointer to an initialized pool. Must not be NULL.

Returns: The blockSize value supplied to SSFMPoolInit().

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
SSFMPoolBlockSize(&pool);   /* returns sizeof(MyMsg_t) */

↑ uint32_t SSFMPoolSize()

uint32_t SSFMPoolSize(const SSFMPool_t *pool);

Returns the total number of blocks in the pool.

Parameter Direction Type Description
pool in const SSFMPool_t * Pointer to an initialized pool. Must not be NULL.

Returns: The blocks value supplied to SSFMPoolInit().

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
SSFMPoolSize(&pool);   /* returns 4 */

↑ uint32_t SSFMPoolLen()

uint32_t SSFMPoolLen(const SSFMPool_t *pool);

Returns the number of free (available) blocks remaining in the pool.

Parameter Direction Type Description
pool in const SSFMPool_t * Pointer to an initialized pool. Must not be NULL.

Returns: Number of free blocks currently available for allocation (Size minus the number of allocated blocks).

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;
MyMsg_t *msg;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
SSFMPoolLen(&pool);   /* returns 4 (all blocks free) */

msg = (MyMsg_t *)SSFMPoolAlloc(&pool, sizeof(MyMsg_t), 0x01u);
SSFMPoolLen(&pool);   /* returns 3 */

↑ bool SSFMPoolIsEmpty()

bool SSFMPoolIsEmpty(const SSFMPool_t *pool);

Returns true if no free blocks remain — i.e., all blocks are currently allocated. Calling SSFMPoolAlloc() on an empty pool will assert; check this function first.

Parameter Direction Type Description
pool in const SSFMPool_t * Pointer to an initialized pool. Must not be NULL.

Returns: true if no free blocks remain; false otherwise.

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;
MyMsg_t *msgs[4];
uint32_t i;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
SSFMPoolIsEmpty(&pool);   /* returns false */

for (i = 0; i < 4u; i++) { msgs[i] = (MyMsg_t *)SSFMPoolAlloc(&pool, sizeof(MyMsg_t), 0x01u); }
SSFMPoolIsEmpty(&pool);   /* returns true (all blocks allocated) */

↑ bool SSFMPoolIsFull()

bool SSFMPoolIsFull(const SSFMPool_t *pool);

Returns true if all blocks are free — i.e., no blocks are currently allocated. This is the required state before calling SSFMPoolDeInit().

Parameter Direction Type Description
pool in const SSFMPool_t * Pointer to an initialized pool. Must not be NULL.

Returns: true if all blocks are free; false otherwise.

Example:

typedef struct { uint32_t id; uint8_t payload[16]; } MyMsg_t;

SSFMPool_t pool;
MyMsg_t *msg;

SSFMPoolInit(&pool, 4u, sizeof(MyMsg_t));
SSFMPoolIsFull(&pool);   /* returns true (all blocks free) */

msg = (MyMsg_t *)SSFMPoolAlloc(&pool, sizeof(MyMsg_t), 0x01u);
SSFMPoolIsFull(&pool);   /* returns false */