CDI Pool API

Introduction

CDI Pool provides a collection of generic functions for managing memory use. Using CDI Pool functions, users can pre-allocate a memory block sized to fit a given number of items of the user's data type, then reserve and free items from the pool as needed. Pools can be created and zeroed-out, and optionally the contents of each pool item can be initialized using a user-provided callback function. Finally, pools can be set up to grow automatically when they are not large enough to accommodate a new request, and can error out when a provided grow limit is reached.

Refer to cdi_pool_api.h for API details.

Example

As outlined in the API, several functions exist for creating pools. The following example demonstrates the instructions needed to generate a pool of transmit buffers from a pre-allocated buffer space. In this example, the pool function CdiPoolCreateUsingExistingBuffer() is used to allocate payload buffers within the adapter buffer that is reserved when the adapter is initialized.

Set defines and initialize variables. Use the CdiPoolHandle type to create a pool handle.

CdiAdapterData* adapter_data_ptr;
CdiPoolHandle tx_buffer_pool_handle;
 
// Set the number of total bytes to reserve from the adapter for payload storage.
adapter_data_ptr->tx_buffer_size_bytes = TX_PAYLOAD_SIZE_BYTES * TX_NUM_PAYLOAD_BUFFERS;

Initialize the adapter interface, and then use the returned ret_tx_buffer_ptr buffer pointer to create a pool of payload buffers which the application's transmit code can pull from later. The pool create function will return the actual number of bytes needed in buffer_bytes_size_needed_ptr.

CdiCoreNetworkAdapterInitialize(adapter_data_ptr, &adapter_handle);
CdiPoolCreateUsingExistingBuffer("Tx Buffer Pool", TX_NUM_PAYLOAD_BUFFERS, TX_PAYLOAD_SIZE_BYTES,
                                 false, adapter_data_ptr->ret_tx_buffer_ptr,
                                 adapter_data_ptr->tx_buffer_size_bytes, buffer_bytes_size_needed_ptr,
                                 &tx_buffer_pool_handle);

Whenever a payload is to be sent, get a payload buffer from the pool. If the pool get fails, use pool functions to get information about the pool to use in a log message.

uint32_t* new_tx_buffer_ptr;
if (!CdiPoolGet(tx_buffer_pool_handle, (void**)&new_tx_buffer_ptr)) {
    CDI_LOG_THREAD(kLogError, "Unable to get a buffer of [%d] bytes from pool[%s]. There are [%d] items left.",
                    CdiPoolGetItemSize(tx_buffer_pool_handle, CdiPoolGetName(tx_buffer_pool_handle),
                    CdiPoolGetFreeItemCount(tx_buffer_pool_handle));
}

In the case of transmit buffers, the buffers will be used by the SDK until the Tx Callback occurs. Pool items should be put back into the pool during the application's Tx Callback function. Buffers are to be returned to the pool using CdiPoolPut().

CdiPoolPut(tx_buffer_pool_handle, used_buffer_ptr);

When the application is shutting down, destroy the pool. Under normal management and use of pool gets and puts, the call to CdiPoolPutAll() is unnecessary, and would probably be masking a coding error, but it can be used as a safeguard if desired.

CdiPoolPutAll(tx_buffer_pool_handle);
CdiPoolDestroy(tx_buffer_pool_handle);