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

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

name	The 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

name	The 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

name	The name of the memory pool.
type	The type of each element in the memory pool (e.g. int, struct foo)
size	The 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

name	The name of the memory pool.
type	The type of a single array element in the memory pool.
array_size	The number of elements in each array.
pool_size	The 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

name	The name of the memory pool to which to free an element.
mem	Pointer 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

name	The 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

name	The 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

name	The name of the memory pool for which to get the current usage.

Returns

The number of elements currently allocated.