EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
mempool (Memory Pools)

Overview

Memory pools with fixed-size elements.

#include "etcpal/mempool.h"

This module can be used to declare memory pools containing some number of elements of an arbitrary type. Only elements of that type can be allocated from the pool or freed back into it. A pool element can be a singular type (e.g. MyStruct) or a fixed-size array (e.g. uint8_t[100]).

If EtcPal is built with OS abstraction support (the default in most situations), allocations and deallocations are ensured to be thread-safe by an etcpal_mutex_t internally.

For example:

typedef struct
{
int data1;
int data2;
} MyStruct;
// Create a memory pool of 20 MyStruct instances
// This line typically appears at file scope
ETCPAL_MEMPOOL_DEFINE(my_struct_pool, MyStruct, 20);
// Then, at function scope...
// Initialize the pool
etcpal_mempool_init(my_struct_pool);
// Get an item from the pool
MyStruct* val = (MyStruct*)etcpal_mempool_alloc(my_struct_pool);
if (val)
{
// Do something with the item
}
// Check the status of the pool
printf("my_struct_pool status: %zu used out of %zu total\n", etcpal_mempool_used(my_struct_pool),
etcpal_mempool_size(my_struct_pool));
// Free the item back to the pool
etcpal_mempool_free(my_struct_pool, val);
// No deinitialization required
#define ETCPAL_MEMPOOL_DEFINE(name, type, size)
Define a new memory pool.
Definition: mempool.h:139
#define etcpal_mempool_init(name)
Initialize a memory pool.
Definition: mempool.h:181
#define etcpal_mempool_alloc(name)
Allocate a new element from a memory pool.
Definition: mempool.h:188
#define etcpal_mempool_size(name)
Get the total size of a memory pool.
Definition: mempool.h:210
#define etcpal_mempool_used(name)
Get the number of elements currently allocated from a memory pool.
Definition: mempool.h:217
#define etcpal_mempool_free(name, mem)
Free an element back to a memory pool.
Definition: mempool.h:200

Macros

#define ETCPAL_MEMPOOL_DECLARE(name)   extern EtcPalMempoolDesc name##_pool_desc;
 Declare a pool as an external variable. More...
 
#define ETCPAL_MEMPOOL_DEFINE(name, type, size)
 Define a new memory pool. More...
 
#define ETCPAL_MEMPOOL_DEFINE_ARRAY(name, type, array_size, pool_size)
 Define a new memory pool composed of arrays of elements. More...
 
#define etcpal_mempool_init(name)   etcpal_mempool_init_priv(&name##_pool_desc)
 Initialize a memory pool. More...
 
#define etcpal_mempool_alloc(name)   etcpal_mempool_alloc_priv(&name##_pool_desc)
 Allocate a new element from a memory pool. More...
 
#define etcpal_mempool_free(name, mem)   etcpal_mempool_free_priv(&name##_pool_desc, mem)
 Free an element back to a memory pool. More...
 
#define etcpal_mempool_size(name)   (name##_pool_desc.pool_size)
 Get the total size of a memory pool. More...
 
#define etcpal_mempool_used(name)   etcpal_mempool_used_priv(&name##_pool_desc)
 Get the number of elements currently allocated from a memory pool. More...
 

Macro Definition Documentation

◆ etcpal_mempool_alloc

#define etcpal_mempool_alloc (   name)    etcpal_mempool_alloc_priv(&name##_pool_desc)

Allocate a new element from a memory pool.

Parameters
nameThe name of the memory pool from which to allocate a new element.
Returns
Pointer to the newly-allocated element (success) or NULL (pool is out of memory).

◆ ETCPAL_MEMPOOL_DECLARE

#define ETCPAL_MEMPOOL_DECLARE (   name)    extern EtcPalMempoolDesc name##_pool_desc;

Declare a pool as an external variable.

This optional macro is useful for header files; when used, it must be paired with a call of ETCPAL_MEMPOOL_DEFINE() or ETCPAL_MEMPOOL_DEFINE_ARRAY() using the same name.

Parameters
nameThe name of the memory pool.

◆ ETCPAL_MEMPOOL_DEFINE

#define ETCPAL_MEMPOOL_DEFINE (   name,
  type,
  size 
)
Value:
type name##_pool[size]; \
struct EtcPalMempool name##_pool_list[size]; \
struct EtcPalMempoolDesc name##_pool_desc = {sizeof(type), /* elem_size */ \
size, /* pool_size */ \
NULL, /* freelist */ \
name##_pool_list, /* list */ \
0, /* current_used */ \
name##_pool /* pool */}

Define a new memory pool.

Expands to a number of variable definitions. Should not be used in a header file; if you want your memory pool to be accessible from multiple source files, use ETCPAL_MEMPOOL_DECLARE() in the header file in addition to this macro.

Parameters
nameThe name of the memory pool.
typeThe type of each element in the memory pool (e.g. int, struct foo)
sizeThe number of elements in the memory pool.

◆ ETCPAL_MEMPOOL_DEFINE_ARRAY

#define ETCPAL_MEMPOOL_DEFINE_ARRAY (   name,
  type,
  array_size,
  pool_size 
)
Value:
type name##_pool[array_size][pool_size]; \
struct EtcPalMempool name##_pool_list[pool_size]; \
struct EtcPalMempoolDesc name##_pool_desc = {sizeof(type[array_size]), /* elem_size */ \
pool_size, /* pool_size */ \
NULL, /* freelist */ \
name##_pool_list, /* list */ \
0, /* current_used */ \
name##_pool /* pool */}

Define a new memory pool composed of arrays of elements.

This is an alternative to ETCPAL_MEMPOOL_DEFINE() for creating memory pools containing fixed-size arrays of elements.

Parameters
nameThe name of the memory pool.
typeThe type of a single array element in the memory pool.
array_sizeThe number of elements in each array.
pool_sizeThe number of arrays in the memory pool.

◆ etcpal_mempool_free

#define etcpal_mempool_free (   name,
  mem 
)    etcpal_mempool_free_priv(&name##_pool_desc, mem)

Free an element back to a memory pool.

CAUTION: Just like with a normal free(), freeing a pointer to an element that has not previously been allocated or a pointer to somewhere outside of the memory pool will cause undefined behavior.

Parameters
nameThe name of the memory pool to which to free an element.
memPointer to the element to free.

◆ etcpal_mempool_init

#define etcpal_mempool_init (   name)    etcpal_mempool_init_priv(&name##_pool_desc)

Initialize a memory pool.

Must be called on a pool before using etcpal_mempool_alloc() or etcpal_mempool_free() on it. There is no deinitialization function because there is no cleanup necessary; to reset a pool, simply call this function again.

Parameters
nameThe name of the memory pool to initialize.
Returns
kEtcPalErrOk: The memory pool was initialized successfully.
kEtcPalErrSys: An internal system call error occurred.

◆ etcpal_mempool_size

#define etcpal_mempool_size (   name)    (name##_pool_desc.pool_size)

Get the total size of a memory pool.

This is a constant value that was provided in the ETCPAL_MEMPOOL_DEFINE() call.

Parameters
nameThe name of the memory pool of which to get the size.
Returns
The size of the memory pool.

◆ etcpal_mempool_used

#define etcpal_mempool_used (   name)    etcpal_mempool_used_priv(&name##_pool_desc)

Get the number of elements currently allocated from a memory pool.

Parameters
nameThe name of the memory pool for which to get the current usage.
Returns
The number of elements currently allocated.