vl_pool.c File Reference

#include "vl_pool.h"
#include <memory.h>

Include dependency graph for vl_pool.c:

Functions
vl_pool_node *	vl_PoolNodeNew (vl_pool *pool)
void	vlPoolInitAligned (vl_pool *pool, vl_uint16_t elementSize, vl_uint16_t alignment)
	Initializes the specified fixed pool instance with specified element size and alignment.
vl_pool_idx	vlPoolTake (vl_pool *pool)
	Takes a new index from the fixed pool, which corresponds to a valid memory location within the pool.
void	vlPoolReturn (vl_pool *pool, vl_pool_idx idx)
	Gives the specified index back to the fixed pool, allowing it to be re-used.
void *	vlPoolSample (vl_pool *pool, vl_pool_idx idx)
	Samples the specified fixed pool and retrieves a pointer to the memory associated with the specified pool index.
void	vlPoolClear (vl_pool *pool)
	Clears the specified pool.
void	vlPoolFree (vl_pool *pool)
	De-initializes the specified pool instance.
void	vlPoolReset (vl_pool *pool)
	Resets the specified pool to its initial state.
void	vlPoolReserve (vl_pool *pool, vl_dsidx_t n)
	Ensures that at least n additional elements can be taken without triggering further allocations.
vl_pool *	vlPoolClone (const vl_pool *src, vl_pool *dest)
	Clones the specified source fixed pool.
vl_pool *	vlPoolNewAligned (vl_uint16_t elementSize, vl_uint16_t alignment)
	Allocates and initializes a new fixed pool instance with specific alignment.
void	vlPoolDelete (vl_pool *pool)
	De-initializes and deletes the specified fixed pool instance.

Function Documentation

vl_PoolNodeNew()

vl_pool_node * vl_PoolNodeNew

(

vl_pool *

pool

)

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolClear()

void vlPoolClear

(

vl_pool *

pool

)

Clears the specified pool.

Resets each underlying memory block's counter to 0 and resets the free index stack. This effectively marks all pooled slots as available for reuse.

Contract

• Ownership: Unchanged.
• Lifetime: All previously taken indices and their associated pointers from vlPoolSample become invalid.
• Thread Safety: Not thread-safe.
• Nullability: pool must not be NULL.
• Error Conditions: None.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

pool	pool pointer

Complexity O(n) linear where n is the number of blocks.

Here is the caller graph for this function:

vlPoolClone()

vl_pool * vlPoolClone	(	const vl_pool *	src,
		vl_pool *	dest
	)

Clones the specified source fixed pool.

Clones the entirety of the src pool to the dest pool, including all management state and element data.

The 'src' pool pointer must be non-null and initialized. The 'dest' pool pointer may be null, but if it is not null it must be initialized.

If the 'dest' pool pointer is null, a new pool is initialized via vlPoolNew. Otherwise, its element size is set to the source's and the destination is reset via vlPoolReset.

Contract

• Ownership: If dest is NULL, the caller owns the returned vl_pool. If dest is provided, ownership remains with the caller.
• Lifetime: The dest pool remains valid until deleted or freed.
• Thread Safety: Not thread-safe.
• Nullability: src must not be NULL. dest can be NULL.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: Passing an uninitialized pool.
• Memory Allocation Expectations: Allocates a new vl_pool struct (if dest is NULL) and multiple memory block nodes.
• Return-value Semantics: Returns the pointer to the cloned pool (dest or a new instance), or NULL on failure.

See also

vlPoolNew

Parameters

src	pointer to pool to clone
dest	pointer to target pool, or NULL

Complexity O(n) linear.

Returns

dest, or pool initialized via vlPoolNew

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolDelete()

void vlPoolDelete

(

vl_pool *

pool

)

De-initializes and deletes the specified fixed pool instance.

This frees all internally allocated memory blocks, management structures, and the vl_pool struct itself. This pool should have been initialized via vlPoolNew(Ext).

Contract

• Ownership: Releases ownership of all internally allocated memory blocks, management structures, and the vl_pool struct.
• Lifetime: All indices, pointers, and the pool struct itself become invalid.
• Thread Safety: Not thread-safe.
• Nullability: pool should not be NULL.
• Error Conditions: None.
• Undefined Behavior: Double deletion.
• Memory Allocation Expectations: Deallocates all pool-related memory via vlMemFree and free.
• Return-value Semantics: None (void).

See also

vlPoolNew

Parameters

pool

pointer

Complexity O(1) constant.

Here is the call graph for this function:

vlPoolFree()

void vlPoolFree

(

vl_pool *

pool

)

De-initializes the specified pool instance.

This will clear up all memory associated with members of the pool, including all allocated block nodes and management tables. This pool should have been initialized via vlPoolInit(Ext).

Contract

• Ownership: Releases ownership of all internally allocated memory blocks and management structures. Does NOT release the pool struct itself.
• Lifetime: All indices previously returned by vlPoolTake and all pointers from vlPoolSample become invalid.
• Thread Safety: Not thread-safe.
• Nullability: pool must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Double free.
• Memory Allocation Expectations: Deallocates all memory blocks and management structures via vlMemFree.
• Return-value Semantics: None (void).

See also

vlPoolInit

Parameters

pool

pointer

Complexity O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolInitAligned()

void vlPoolInitAligned	(	vl_pool *	pool,
		vl_uint16_t	elementSize,
		vl_uint16_t	alignment
	)

Initializes the specified fixed pool instance with specified element size and alignment.

This pool should be de-initialized via vlPoolFree.

Contract

• Ownership: The caller maintains ownership of the pool struct. The function initializes internal management structures.
• Lifetime: The pool struct must remain valid for the duration of its use. Internal allocations are valid until vlPoolFree or vlPoolDelete.
• Thread Safety: Not thread-safe. Concurrent access must be synchronized.
• Nullability: If pool is NULL, the function returns immediately (no-op).
• Error Conditions: None.
• Undefined Behavior: alignment is not a power of 2. Passing an already initialized pool without first calling vlPoolFree (causes memory leak).
• Memory Allocation Expectations: Allocates initial lookup table, free index stack, and the first memory block node via vlMemAlloc and vlMemAllocAligned.
• Return-value Semantics: None (void).

Warning

alignment must be a power of 2.

See also

vlPoolFree

Parameters

pool	pointer
elementSize	size of each element, in bytes.
alignment	alignment of each element, in bytes.

Complexity O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolNewAligned()

vl_pool * vlPoolNewAligned	(	vl_uint16_t	elementSize,
		vl_uint16_t	alignment
	)

Allocates and initializes a new fixed pool instance with specific alignment.

This pool should later be deleted via vlPoolDelete.

Contract

• Ownership: The caller owns the returned vl_pool pointer and is responsible for calling vlPoolDelete.
• Lifetime: The pool instance is valid until it is passed to vlPoolDelete.
• Thread Safety: Not thread-safe.
• Nullability: Returns NULL if heap allocation for the vl_pool struct fails.
• Error Conditions: Returns NULL on allocation failure.
• Undefined Behavior: alignment is not a power of 2.
• Memory Allocation Expectations: Allocates memory for the vl_pool struct and its management structures.
• Return-value Semantics: Returns a pointer to the newly allocated and initialized pool, or NULL.

Warning

alignment must be a power of 2.

See also

vlPoolDelete

Parameters

elementSize	size of each element, in bytes.
alignment	alignment of each element, in bytes.

Complexity O(1) constant.

Returns

pointer to pool instance

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolReserve()

void vlPoolReserve	(	vl_pool *	pool,
		vl_dsidx_t	n
	)

Ensures that at least n additional elements can be taken without triggering further allocations.

This may create one or more new block nodes, following the geometric growth strategy (doubling size).

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Not thread-safe.
• Nullability: pool must not be NULL.
• Error Conditions: Allocation failure when creating new nodes.
• Undefined Behavior: None.
• Memory Allocation Expectations: May allocate multiple new block nodes and reallocate management tables.
• Return-value Semantics: None (void).

Parameters

pool	pointer
n	total additional elements to reserve space for

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolReset()

void vlPoolReset

(

vl_pool *

pool

)

Resets the specified pool to its initial state.

Deletes all memory block nodes except for the initial one, and resets all counters and the free stack.

Contract

• Ownership: Releases ownership of all but the first memory block node.
• Lifetime: All indices and pointers become invalid.
• Thread Safety: Not thread-safe.
• Nullability: pool must not be NULL.
• Error Conditions: None.
• Undefined Behavior: None.
• Memory Allocation Expectations: Deallocates block nodes via vlMemFree.
• Return-value Semantics: None (void).

Parameters

pool

Complexity O(n) linear.

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolReturn()

void vlPoolReturn	(	vl_pool *	pool,
		vl_pool_idx	idx
	)

Gives the specified index back to the fixed pool, allowing it to be re-used.

Contract

• Ownership: Transfers ownership of the element slot back to the pool.
• Lifetime: The index becomes invalid for the caller immediately.
• Thread Safety: Not thread-safe.
• Nullability: idx can be VL_POOL_INVALID_IDX (no-op).
• Error Conditions: None (potential reallocation failure of free stack is not handled in current implementation).
• Undefined Behavior: Passing an index that was not previously taken or already returned.
• Memory Allocation Expectations: May trigger heap reallocation of the internal free index stack.
• Return-value Semantics: None (void).

Parameters

pool	pointer
idx	element index

Complexity O(1) constant.

Here is the call graph for this function:

Here is the caller graph for this function:

vlPoolSample()

void * vlPoolSample	(	vl_pool *	pool,
		vl_pool_idx	idx
	)

Samples the specified fixed pool and retrieves a pointer to the memory associated with the specified pool index.

Contract

• Ownership: Ownership remains with the pool.
• Lifetime: The returned pointer is valid until the element is returned, or the pool is cleared/reset/destroyed.
• Thread Safety: Safe for concurrent reads if no other thread is writing to the same element or reallocating pool management structures.
• Nullability: Returns NULL if idx is VL_POOL_INVALID_IDX or if the block associated with the index is not found.
• Error Conditions: None.
• Undefined Behavior: Passing an invalid index (e.g., out of bounds, already returned).
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns a pointer to the raw element data, or NULL.

Parameters

pool	pointer to the fixed pool
idx	numeric index of pooled memory instance

Complexity O(1) constant.

Returns

pointer to element data.

Here is the caller graph for this function:

vlPoolTake()

vl_pool_idx vlPoolTake

(

vl_pool *

pool

)

Takes a new index from the fixed pool, which corresponds to a valid memory location within the pool.

If no free slots are available in existing blocks, a new memory block node is automatically allocated.

Contract

• Ownership: The pool owns the memory associated with the returned index.
• Lifetime: The index is valid until it is returned via vlPoolReturn or the pool is destroyed/reset.
• Thread Safety: Not thread-safe.
• Nullability: Returns VL_POOL_INVALID_IDX if allocation fails when growing the pool.
• Error Conditions: Returns VL_POOL_INVALID_IDX on allocation failure.
• Undefined Behavior: Passing an uninitialized pool.
• Memory Allocation Expectations: May trigger heap allocation for new block nodes or lookup table/free stack expansion via vlMemAllocAligned and vlMemRealloc.
• Return-value Semantics: Returns a handle (vl_pool_idx) to an element, or VL_POOL_INVALID_IDX on failure.

Parameters

pool

pointer

Complexity O(1) constant.

Returns

index of new pool item.

Here is the call graph for this function:

Here is the caller graph for this function: