This file contains definitions and implementation for a memory pool. More...

#include "cdi_pool_api.h"
#include <assert.h>
#include <inttypes.h>
#include "configuration.h"
#include "cdi_logger_api.h"
#include "cdi_os_api.h"
#include "internal_log.h"
#include "singly_linked_list_api.h"
#include "utilities_api.h"

Data Structures
struct	CdiPoolItem
	This structure represents a single pool item. More...

struct	CdiPoolState
	This structure represents the current state of a memory pool. More...

Functions
static void	MultithreadedReserve (CdiPoolState *state_ptr)

static void	MultithreadedRelease (CdiPoolState *state_ptr)

static CdiPoolItem *	GetPoolItemFromItemDataPointer (const void *item_ptr)
	Get pointer to the item's parent object (CdiPoolItem).

static uint8_t *	GetDataItem (CdiPoolItem *pool_item_ptr)
	Get pointer to the item's data given the address of the pool item (CdiPoolItem).

static bool	AddEntriesToBuffers (CdiPoolState state_ptr, uint8_t pool_item_array, int item_count)
	Adds pool item array to allocated buffer and free list.

static bool	PoolCreate (const char name_str, uint32_t item_count, uint32_t grow_count, uint32_t max_grow_count, uint32_t item_byte_size, bool thread_safe, void pool_item_array, bool is_existing_buffer, CdiPoolHandle ret_handle_ptr, CdiPoolItemOperatorFunction init_fn, void init_context_ptr)
	Creates a memory pool and returns ret_handle, which is a pointer to create memory pool.

static bool	PoolIncrease (CdiPoolHandle handle_ptr)
	Increases a memory pool. NOTE: this function assumes that MultiThreadedReserve() has been called first.

uint32_t	CdiPoolGetSizeNeeded (uint32_t item_count, uint32_t item_byte_size)

bool	CdiPoolCreate (const char name_str, uint32_t item_count, uint32_t grow_count, uint32_t max_grow_count, uint32_t item_byte_size, bool thread_safe, CdiPoolHandle ret_handle_ptr)

bool	CdiPoolCreateAndInitItems (const char name_str, uint32_t item_count, uint32_t grow_count, uint32_t max_grow_count, uint32_t item_byte_size, bool thread_safe, CdiPoolHandle ret_handle_ptr, CdiPoolItemOperatorFunction init_fn, void *init_context_ptr)

bool	CdiPoolCreateUsingExistingBuffer (const char name_str, uint32_t item_count, uint32_t item_byte_size, bool thread_safe, void buffer_ptr, uint32_t buffer_byte_size, uint32_t buffer_byte_size_needed_ptr, CdiPoolHandle ret_handle_ptr)

bool	CdiPoolCreateUsingExistingBufferAndInitItems (const char name_str, uint32_t item_count, uint32_t item_byte_size, bool thread_safe, void buffer_ptr, uint32_t buffer_byte_size, uint32_t buffer_byte_size_needed_ptr, CdiPoolHandle ret_handle_ptr, CdiPoolItemOperatorFunction init_fn, void *init_context_ptr)

void	CdiPoolDestroy (CdiPoolHandle handle)

bool	CdiPoolPeekInUse (CdiPoolHandle handle, void **ret_item_ptr)

bool	CdiPoolGet (CdiPoolHandle handle, void **ret_item_ptr)

void	CdiPoolPut (CdiPoolHandle handle, const void *item_ptr)

void	CdiPoolPutAll (CdiPoolHandle handle)

const char *	CdiPoolGetName (CdiPoolHandle handle)

uint32_t	CdiPoolGetItemSize (CdiPoolHandle handle)

int	CdiPoolGetFreeItemCount (CdiPoolHandle handle)

int	CdiPoolGetTotalItemCount (CdiPoolHandle handle)
	Get the total number of items in the pool.

bool	CdiPoolForEachItem (CdiPoolHandle handle, CdiPoolItemOperatorFunction operator_function, const void *context_ptr)

void	CdiPoolCallbackEnable (CdiPoolHandle handle, CdiPoolCallback cb_ptr)

void	CdiPoolCallbackDisable (CdiPoolHandle handle)

Detailed Description

This file contains definitions and implementation for a memory pool.

Function Documentation

◆ AddEntriesToBuffers()

static bool AddEntriesToBuffers	(	CdiPoolState *	state_ptr,
		uint8_t *	pool_item_array,
		int	item_count )

inlinestatic

Adds pool item array to allocated buffer and free list.

Parameters

state_ptr	Pool state information for lists and init function.
pool_item_array	The array being attached.
item_count	Number of items in array to be attached.

Returns: true if all of the entries were added and the optional initialization function returned true for every item added, false if not.

◆ CdiPoolCallbackDisable()

void CdiPoolCallbackDisable ( CdiPoolHandle handle )

Disable a previously enabled pool callback.

Parameters

handle pool handle.

◆ CdiPoolCallbackEnable()

void CdiPoolCallbackEnable	(	CdiPoolHandle	handle,
		CdiPoolCallback	cb_ptr )

Enable triggering of a user provided callback function whenever CdiPoolGet() or CdiPoolPut() is used. This is typically used to provide debug information to the caller or the ability to maintain custom in-use lists.

Parameters

handle	pool handle.
cb_ptr	Pointer to callback function.

◆ CdiPoolCreate()

bool CdiPoolCreate	(	const char *	name_str,
		uint32_t	item_count,
		uint32_t	grow_count,
		uint32_t	max_grow_count,
		uint32_t	item_byte_size,
		bool	thread_safe,
		CdiPoolHandle *	ret_handle_ptr )

Create a new memory pool. Memory is allocated by this function.

Parameters

name_str	Pointer to name of pool to copy to the new pool instance.
item_count	Number of initial items in the pool.
grow_count	Number of items that a pool will be increased by if the initial size requested is inadequate.
max_grow_count	Maximum number of times a pool may be increased before an error occurs.
item_byte_size	Size of each item in bytes.
thread_safe	If true, locks are used to protect resources from multi-threaded access, otherwise locks are not used and single threaded access to all APIs is required.
ret_handle_ptr	Pointer to returned handle of the new pool.

Returns: true if successful, otherwise false (not enough memory).

◆ CdiPoolCreateAndInitItems()

bool CdiPoolCreateAndInitItems	(	const char *	name_str,
		uint32_t	item_count,
		uint32_t	grow_count,
		uint32_t	max_grow_count,
		uint32_t	item_byte_size,
		bool	thread_safe,
		CdiPoolHandle *	ret_handle_ptr,
		CdiPoolItemOperatorFunction	init_fn,
		void *	init_context_ptr )

Create a new memory pool and initialize each item in it using the provided callback function. Memory is allocated by this function.

Parameters

name_str	Pointer to name of pool to copy to the new pool instance.
item_count	Number of items in the pool.
grow_count	Number of items that a pool will be increased by if the initial size requested is inadequate.
max_grow_count	Maximum number of times a pool may be increased before an error occurs.
item_byte_size	Size of each item in bytes.
thread_safe	If true, locks are used to protect resources from multi-threaded access, otherwise locks are not used and single threaded access to all APIs is required.
ret_handle_ptr	Pointer to returned handle of the new pool.
init_fn	The address of a function that will be called for each item in the pool at creation time; a value of NULL indicates that no initialization beyond zeroing the memory is to be done. If false is returned by the function, the pool creation will fail and all the resources allocated in the process of creating it will be freed.
init_context_ptr	A value to provide as init_context to init_fn().

Returns: true if successful, otherwise false (not enough memory).

◆ CdiPoolCreateUsingExistingBuffer()

bool CdiPoolCreateUsingExistingBuffer	(	const char *	name_str,
		uint32_t	item_count,
		uint32_t	item_byte_size,
		bool	thread_safe,
		void *	buffer_ptr,
		uint32_t	buffer_byte_size,
		uint32_t *	buffer_byte_size_needed_ptr,
		CdiPoolHandle *	ret_handle_ptr )

Create a new memory pool from a user-provided buffer and initialize each item in it using the provided callback function. Some additional memory is required for each item in the pool to hold data used internally by this pool API. So, the required buffer size must be larger than:

item count x item_byte_size

To determine the exact size needed, use CdiPoolGetSizeNeeded().

Parameters

name_str	Pointer to name of pool to copy to the new pool instance.
item_count	Number of items in the pool.
item_byte_size	Size of each item in bytes.
thread_safe	If true, locks are used to protect resources from multi-threaded access, otherwise locks are not used and single threaded access to all APIs is required.
buffer_ptr	Pointer to buffer to use for the memory pool.
buffer_byte_size	Size of buffer in bytes.
buffer_byte_size_needed_ptr	Pointer to returned size of buffer actually needed or used. See comments for return value below.
ret_handle_ptr	Pointer to returned handle of the new pool.

Returns: true if successful. If false is returned, the value returned in buffer_byte_size_needed will be the number of bytes needed in order to create the pool. If true is returned, the value returned in buffer_byte_size_needed will be the number of bytes actually used for the pool.

◆ CdiPoolCreateUsingExistingBufferAndInitItems()

bool CdiPoolCreateUsingExistingBufferAndInitItems	(	const char *	name_str,
		uint32_t	item_count,
		uint32_t	item_byte_size,
		bool	thread_safe,
		void *	buffer_ptr,
		uint32_t	buffer_byte_size,
		uint32_t *	buffer_byte_size_needed_ptr,
		CdiPoolHandle *	ret_handle_ptr,
		CdiPoolItemOperatorFunction	init_fn,
		void *	init_context_ptr )

Create a new memory pool from a user-provided buffer. Some additional memory is required for each item in the pool to hold data used internally by this pool API. So, the required buffer size must be larger than:

item count x item_byte_size

To determine the exact size needed, use CdiPoolGetSizeNeeded().

Parameters

name_str	Pointer to name of pool to copy to the new pool instance.
item_count	Number of items in the pool.
item_byte_size	Size of each item in bytes.
thread_safe	If true, locks are used to protect resources from multi-threaded access, otherwise locks are not used and single threaded access to all APIs is required.
buffer_ptr	Pointer to buffer to use for the memory pool.
buffer_byte_size	Size of buffer in bytes.
buffer_byte_size_needed_ptr	Pointer to returned size of buffer actually needed or used. See comments for return value below.
ret_handle_ptr	Pointer to returned handle of the new pool.
init_fn	The address of a function that will be called for each item in the pool at creation time; a value of NULL indicates that no initialization beyond zeroing the memory is to be done. If false is returned by the function, the pool creation will fail and all the resources allocated in the process of creating it will be freed.
init_context_ptr	A value to provide as init_context to init_fn().

Returns: true if successful. If false is returned, the value returned in buffer_byte_size_needed will be the number of bytes needed in order to create the pool. If true is returned, the value returned in buffer_byte_size_needed will be the number of bytes actually used for the pool.

◆ CdiPoolDestroy()

void CdiPoolDestroy ( CdiPoolHandle handle )

Destroy a memory pool.

Parameters

handle Memory pool handle.

◆ CdiPoolForEachItem()

bool CdiPoolForEachItem	(	CdiPoolHandle	handle,
		CdiPoolItemOperatorFunction	operator_function,
		const void *	context_ptr )

Call a function for each item in the pool. If any items are allocated from the pool when this function is called, no operations will be performed and false will be returned.

Parameters

handle	Memory pool handle.
operator_function	Pointer to a function that is to be called once for each item in the pool. The items' address and context_ptr are passed in to the function.
context_ptr	This value is passed as the first actual argument to the operator function.

Returns: false if any items are currently allocated from the pool or if operator_function returned false for at least one item in the pool, otherwise true.

◆ CdiPoolGet()

bool CdiPoolGet	(	CdiPoolHandle	handle,
		void **	ret_item_ptr )

Get a pointer to an available buffer in the pool. If not enough memory is available, memory will be increased if possible.

Parameters

handle	Memory pool handle.
ret_item_ptr	Pointer to returned pointer to buffer.

Returns: true if successful, otherwise false (no free buffers).

◆ CdiPoolGetFreeItemCount()

int CdiPoolGetFreeItemCount ( CdiPoolHandle handle )

Get the number of free items currently available in the pool.

Parameters

handle Pool handle.

Returns: Number of free items.

◆ CdiPoolGetItemSize()

uint32_t CdiPoolGetItemSize ( CdiPoolHandle handle )

Get byte size of buffer for a single pool item.

Parameters

handle Pool handle.

Returns: Byte size of the buffer.

◆ CdiPoolGetName()

const char * CdiPoolGetName ( CdiPoolHandle handle )

Get name of pool that was defined when pool was created.

Parameters

handle Pool handle.

Returns: Pointer to NULL terminated name of the pool.

◆ CdiPoolGetSizeNeeded()

uint32_t CdiPoolGetSizeNeeded	(	uint32_t	item_count,
		uint32_t	item_byte_size )

Get the size of the buffer needed to create a pool for the specified number of items and item size.

Parameters

item_count	Number of items in the pool.
item_byte_size	Size of each item in bytes.

Returns: Size of buffer in bytes needed to create pool,

◆ CdiPoolGetTotalItemCount()

int CdiPoolGetTotalItemCount ( CdiPoolHandle handle )

Get the total number of items in the pool.

Parameters

handle Pool handle.

Returns: Number of total items.

◆ CdiPoolPeekInUse()

bool CdiPoolPeekInUse	(	CdiPoolHandle	handle,
		void **	ret_item_ptr )

Get a pointer to the head of the allocated buffer list. If the list is empty, NULL will be written to ret_item_ptr and false returned.

NOTE: Since the returned pointer still resides in the pool, the caller must ensure that other threads cannot use it. This means other threads won't be using CdiPoolPut() for the pool item.

Parameters

handle	Memory pool handle.
ret_item_ptr	Pointer to returned pointer to buffer.

Returns: true if successful, otherwise false (allocated buffer list is empty).

◆ CdiPoolPut()

void CdiPoolPut	(	CdiPoolHandle	handle,
		const void *	item_ptr )

Put a buffer back into the pool.

Parameters

handle	Memory pool handle.
item_ptr	Pointer to buffer to put back.

◆ CdiPoolPutAll()

void CdiPoolPutAll ( CdiPoolHandle handle )

Put all the used buffers back into the pool.

Parameters

handle Memory pool handle.

◆ GetDataItem()

static uint8_t * GetDataItem ( CdiPoolItem * pool_item_ptr )

inlinestatic

Get pointer to the item's data given the address of the pool item (CdiPoolItem).

Parameters

pool_item_ptr Pointer to pool item.

Returns: Pointer to item's data.

◆ GetPoolItemFromItemDataPointer()

static CdiPoolItem * GetPoolItemFromItemDataPointer ( const void * item_ptr )

inlinestatic

Get pointer to the item's parent object (CdiPoolItem).

Parameters

item_ptr Pointer to object being queried.

Returns: Pointer to parent of object.

◆ MultithreadedRelease()

static void MultithreadedRelease ( CdiPoolState * state_ptr )

inlinestatic

If lock used to protect pool resources from multi-threaded access exists, release it.

Parameters

state_ptr Pool state information for the lock.

◆ MultithreadedReserve()

static void MultithreadedReserve ( CdiPoolState * state_ptr )

inlinestatic

If lock used to protect pool resources from multi-threaded access exists, reserve it.

Parameters

state_ptr Pool state information for the lock.

◆ PoolCreate()

static bool PoolCreate	(	const char *	name_str,
		uint32_t	item_count,
		uint32_t	grow_count,
		uint32_t	max_grow_count,
		uint32_t	item_byte_size,
		bool	thread_safe,
		void *	pool_item_array,
		bool	is_existing_buffer,
		CdiPoolHandle *	ret_handle_ptr,
		CdiPoolItemOperatorFunction	init_fn,
		void *	init_context_ptr )

static

Creates a memory pool and returns ret_handle, which is a pointer to create memory pool.

Parameters

name_str	Name of memory pool.
item_count	Number of items in the pool.
grow_count	Number of items that a pool may be increased by if the initial size requested is inadequate.
max_grow_count	Maximum number of times a pool may be increased before an error occurs.
item_byte_size	Size of each item in bytes.
thread_safe	If true, locks are used to protect resources from multi-threaded access, otherwise locks are not used and single threaded access to all resources is required.
pool_item_array	Pointer to data buffer for the memory pool.
is_existing_buffer	If true, using an existing buffer so don't free the memory when the pool is destroyed.
ret_handle_ptr	Pointer to returned handle of the new pool.
init_fn	The address of a function that will be called for each item in the pool at creation time; a value of NULL indicates that no initialization beyond zeroing the memory is to be done.
init_context_ptr	A value to provide as init_context to init_fn().

◆ PoolIncrease()

static bool PoolIncrease ( CdiPoolHandle handle_ptr )

static

Increases a memory pool. NOTE: this function assumes that MultiThreadedReserve() has been called first.

Parameters

handle_ptr Pointer to pool handle.

Returns: If successful true is returned, otherwise false is returned.

Data Structures

Functions

Detailed Description

Function Documentation

◆ AddEntriesToBuffers()

◆ CdiPoolCallbackDisable()

◆ CdiPoolCallbackEnable()

◆ CdiPoolCreate()

◆ CdiPoolCreateAndInitItems()

◆ CdiPoolCreateUsingExistingBuffer()

◆ CdiPoolCreateUsingExistingBufferAndInitItems()

◆ CdiPoolDestroy()

◆ CdiPoolForEachItem()

◆ CdiPoolGet()

◆ CdiPoolGetFreeItemCount()

◆ CdiPoolGetItemSize()

◆ CdiPoolGetName()

◆ CdiPoolGetSizeNeeded()

◆ CdiPoolGetTotalItemCount()

◆ CdiPoolPeekInUse()

◆ CdiPoolPut()

◆ CdiPoolPutAll()

◆ GetDataItem()

◆ GetPoolItemFromItemDataPointer()

◆ MultithreadedRelease()

◆ MultithreadedReserve()

◆ PoolCreate()

◆ PoolIncrease()