cdi_pool_api.h File Reference

This file declares the public API data types, structures and functions that comprise the CDI Pool Utility API. More...

#include <stdbool.h>
#include <stdint.h>
#include "cdi_utility_api.h"

Go to the source code of this file.

Data Structures
struct	CdiPoolCbData
	Contains the state of a single pool get or put operation. More...

Typedefs
typedef struct CdiPoolState *	CdiPoolHandle
	Type used as the handle (pointer to an opaque structure) for a Memory Pool. Each handle represents a instance of a Memory Pool.
typedef bool(*	CdiPoolItemOperatorFunction) (const void *context_ptr, void *item_ptr)
typedef void(*	CdiPoolCallback) (const CdiPoolCbData *data_ptr)
	Prototype of pool callback function.

Functions
CDI_INTERFACE uint32_t	CdiPoolGetSizeNeeded (uint32_t item_count, uint32_t item_byte_size)
CDI_INTERFACE 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)
CDI_INTERFACE 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)
CDI_INTERFACE 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)
CDI_INTERFACE 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)
CDI_INTERFACE bool	CdiPoolPeekInUse (CdiPoolHandle handle, void **ret_item_ptr)
CDI_INTERFACE bool	CdiPoolGet (CdiPoolHandle handle, void **ret_item_ptr)
CDI_INTERFACE void	CdiPoolPut (CdiPoolHandle handle, const void *item_ptr)
CDI_INTERFACE void	CdiPoolPutAll (CdiPoolHandle handle)
CDI_INTERFACE const char *	CdiPoolGetName (CdiPoolHandle handle)
CDI_INTERFACE uint32_t	CdiPoolGetItemSize (CdiPoolHandle handle)
CDI_INTERFACE int	CdiPoolGetFreeItemCount (CdiPoolHandle handle)
CDI_INTERFACE int	CdiPoolGetTotalItemCount (CdiPoolHandle handle)
	Get the total number of items in the pool.
CDI_INTERFACE bool	CdiPoolForEachItem (CdiPoolHandle handle, CdiPoolItemOperatorFunction operator_function, const void *context_ptr)
CDI_INTERFACE void	CdiPoolCallbackEnable (CdiPoolHandle handle, CdiPoolCallback cb_ptr)
CDI_INTERFACE void	CdiPoolCallbackDisable (CdiPoolHandle handle)
CDI_INTERFACE void	CdiPoolDestroy (CdiPoolHandle handle)

Detailed Description

This file declares the public API data types, structures and functions that comprise the CDI Pool Utility API.

Typedef Documentation

CdiPoolCallback

typedef void(* CdiPoolCallback) (const CdiPoolCbData *data_ptr)

Prototype of pool callback function.

This callback function is invoked whenever an item is put to or get from the pool.

Parameters

data_ptr

A pointer to an CdiFifoCbData structure.

CdiPoolItemOperatorFunction

typedef bool(* CdiPoolItemOperatorFunction) (const void *context_ptr, void *item_ptr)

Prototype of a function for operations on pool members during initialization, destruction, and "for each". This function will be called item_count times, once for each item. (item_count being an argument to CdiPoolCreate() or CdiPoolCreateUsingExistingBuffer().

Parameters

context_ptr	A pointer value provided as the init_context argument to CdiPoolCreate() or CdiPoolCreateUsingExistingBuffer().
item_ptr	The address of the item being added to the pool.

Returns

true if the operation was successful, false if not.

Function Documentation

CdiPoolCallbackDisable()

CDI_INTERFACE void CdiPoolCallbackDisable

(

CdiPoolHandle

handle

)

Disable a previously enabled pool callback.

Parameters

handle

pool handle.

CdiPoolCallbackEnable()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE void CdiPoolDestroy

(

CdiPoolHandle

handle

)

Destroy a memory pool.

Parameters

handle

Memory pool handle.

CdiPoolForEachItem()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE int CdiPoolGetTotalItemCount

(

CdiPoolHandle

handle

)

Get the total number of items in the pool.

Parameters

handle

Pool handle.

Returns

Number of total items.

CdiPoolPeekInUse()

CDI_INTERFACE 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()

CDI_INTERFACE 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()

CDI_INTERFACE void CdiPoolPutAll

(

CdiPoolHandle

handle

)

Put all the used buffers back into the pool.

Parameters

handle

Memory pool handle.