Fixed block allocator

Data Structures
struct	JUNO_MEMORY_BLOCK_METADATA_TAG
	Metadata for a memory block entry (allocator-specific). More...

Macros
#define	JUNO_MEMORY_BLOCK(name, type, length)   static type name[length] = {0}
	Declare a static contiguous memory array for block storage.
#define	JUNO_MEMORY_BLOCK_METADATA(name, length)   static JUNO_MEMORY_BLOCK_METADATA_T name[length] = {0}
	Declare a static array for per-block metadata.
#define	JunoMemory_BlockGetT(ptBlkRoot, type)   (ptBlkRoot)->tRoot.ptApi->Get(&(ptBlkRoot)->tRoot, sizeof(type))
	Allocate a block sized for the specified C type.
#define	JunoMemory_BlockPutT(ptBlkRoot, pPtr)   (ptBlkRoot)->tRoot.ptApi->Put(&(ptBlkRoot)->tRoot, (pPtr))
	Free a previously allocated block given its pointer descriptor.

Functions
struct JUNO_MEMORY_ALLOC_BLOCK_TAG	JUNO_MODULE_DERIVE (JUNO_MEMORY_ALLOC_ROOT_T, uint8_t *pvMemory;JUNO_MEMORY_BLOCK_METADATA_T *ptMetadata;size_t zTypeSize;size_t zAlignment;size_t zLength;size_t zUsed;size_t zFreed;)
	Concrete block allocator derivation over the generic alloc root.
JUNO_STATUS_T	JunoMemory_BlockInit (JUNO_MEMORY_ALLOC_BLOCK_T *ptJunoMemory, const JUNO_POINTER_API_T *ptPointerApi, void *pvMemory, JUNO_MEMORY_BLOCK_METADATA_T *ptMetadata, size_t zTypeSize, size_t zAlignment, size_t zLength, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, JUNO_USER_DATA_T *pvFailureUserData)
	Initialize a fixed-size block allocator over a caller-supplied region.

Detailed Description

A deterministic, fixed-capacity allocator that dispenses blocks of a uniform element size from a caller-supplied backing region. Metadata tracks a LIFO free list for O(1) allocation and free. Alignment is enforced per block. This module is freestanding-friendly and uses the Pointer API for verification and zeroing.

Behavior and guarantees:

• Get: Returns a block whose size is the configured element size. If a freed block exists (zFreed > 0), it is reused (LIFO). Otherwise, a new block is carved from the next offset if zUsed < zLength. Newly provided blocks are Reset via the pointer API before being returned; on Reset failure, the allocator rolls back and reports the error.
• Put: Verifies the address belongs to the pool and is aligned. Double frees are rejected. If the block being freed is the most recently allocated block, zUsed is decremented without pushing onto the free stack; otherwise, the address is pushed to the free stack (zFreed++). On success, the caller's descriptor is cleared (pvAddr=NULL, sizes 0).
• Update: Adjusts the descriptor's zSize in place up to the element size; memory is never moved. Requests above element size are rejected.

Invariants:

• 0 <= zUsed <= zLength
• 0 <= zFreed <= zLength
• zUsed counts total blocks ever allocated; it is decremented only when freeing the last allocated block.
• The free stack keeps freed block addresses in ptMetadata[0..zFreed).

Complexity:

• Init, Get, Put, Update are all O(1).

Error cases:

• Get: zero size, size > element size, pool full, corrupt counters.
• Put: null/unaligned/out-of-range address, double free, free list overflow (should be impossible if invariants are maintained).

Macro Definition Documentation

JUNO_MEMORY_BLOCK

#define JUNO_MEMORY_BLOCK	(		name,
			type,
			length
	)		static type name[length] = {0}

Declare a static contiguous memory array for block storage.

Parameters

name	Name of the backing array symbol.
type	Element type for each block.
length	Number of elements in the block pool.

JUNO_MEMORY_BLOCK_METADATA

#define JUNO_MEMORY_BLOCK_METADATA	(		name,
			length
	)		static JUNO_MEMORY_BLOCK_METADATA_T name[length] = {0}

Declare a static array for per-block metadata.

Parameters

name	Name of the metadata array symbol.
length	Number of entries (should match the block array length).

JunoMemory_BlockGetT

#define JunoMemory_BlockGetT	(		ptBlkRoot,
			type
	)		(ptBlkRoot)->tRoot.ptApi->Get(&(ptBlkRoot)->tRoot, sizeof(type))

Allocate a block sized for the specified C type.

Parameters

ptBlkRoot	Pointer to a JUNO_MEMORY_ALLOC_BLOCK_T instance.
type	C type used to derive size and alignment.

JunoMemory_BlockPutT

#define JunoMemory_BlockPutT	(		ptBlkRoot,
			pPtr
	)		(ptBlkRoot)->tRoot.ptApi->Put(&(ptBlkRoot)->tRoot, (pPtr))

Free a previously allocated block given its pointer descriptor.

Parameters

ptBlkRoot	Pointer to a JUNO_MEMORY_ALLOC_BLOCK_T instance.
pPtr	Pointer descriptor previously returned by the allocator.

Function Documentation

JUNO_MODULE_DERIVE()

struct JUNO_MEMORY_ALLOC_BLOCK_TAG JUNO_MODULE_DERIVE	(	JUNO_MEMORY_ALLOC_ROOT_T	,
		uint8_t *pvMemory;JUNO_MEMORY_BLOCK_METADATA_T *ptMetadata;size_t zTypeSize;size_t zAlignment;size_t zLength;size_t zUsed;size_t zFreed;
	)

Concrete block allocator derivation over the generic alloc root.

Stores the backing region and metadata required to manage a pool of fixed-size blocks. The root provides the allocation API pointer and failure handling; ptPointerApi lives in the root (see memory_api.h).

JunoMemory_BlockInit()

JUNO_STATUS_T JunoMemory_BlockInit	(	JUNO_MEMORY_ALLOC_BLOCK_T *	ptJunoMemory,
		const JUNO_POINTER_API_T *	ptPointerApi,
		void *	pvMemory,
		JUNO_MEMORY_BLOCK_METADATA_T *	ptMetadata,
		size_t	zTypeSize,
		size_t	zAlignment,
		size_t	zLength,
		JUNO_FAILURE_HANDLER_T	pfcnFailureHandler,
		JUNO_USER_DATA_T *	pvFailureUserData
	)

Initialize a fixed-size block allocator over a caller-supplied region.

Parameters

ptJunoMemory	Allocator instance to initialize.
ptPointerApi	Pointer API required for internal operations (non-null).
pvMemory	Backing memory region for blocks (aligned to zAlignment).
ptMetadata	Metadata array to track free blocks (length == zLength).
zTypeSize	Size of each block element in bytes (non-zero).
zAlignment	Alignment requirement in bytes for each block (non-zero).
zLength	Total number of blocks available in the pool (non-zero).
pfcnFailureHandler	Optional failure handler callback.
pvFailureUserData	Optional user data passed to the failure handler.

Returns

JUNO_STATUS_SUCCESS on success; JUNO_STATUS_ERR or specific codes on failure.

Note

Performs parameter validation (nulls, overflow of zTypeSize*zLength, base alignment) and wires the allocator API into the root. Counters zUsed and zFreed start at 0.