A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd

pool

A fixed capacity object pool.
STL equivalent: none

etl::pool<typename T, const size_t SIZE>

Inherits from etl::ipool
etl::ipool may be used as a size and type independent pointer or reference type for any etl::pool instance.

Notes

The pool does not construct or destruct anything. It merely provides access to memory that is sized and aligned to
contain a T object. It is up to the user of the pool to handle the lifetime of the object.

class Data
{
   ...
};

etl::pool<Data, 10> data_pool;

// Create.
Data* pdata = new (data_pool.allocate<Data>()) Data();

// Destroy
pdata->~Data();
data_pool.release(pdata);

Heterogeneous pools may be constructed by either basing the pool's type on a union or using etl::variant.

union Data
{
  char   text[100];
  int    counter;
  double ratio;
};

etl::pool<Data, 10> data_pool;

char   *pc = data_pool.allocate<char>();
int    *pi = data_pool.allocate<int>();
double *pd = data_pool.allocate<double>();

Constructor

pool()
Constructs a pool. No elements are constructed.

Operations

template <typename T>
T* allocate()
Allocates an item from the pool and returns a pointer to it.
If the pool has no free items then an etl::pool_no_allocation() is emitted and a nullptr is returned.
Does not call the object's constructor.

void release(const void* pobject);
Releases an object back to the pool.
If the object does not belong to the pool an etl::pool_object_not_in_pool() is emitted.
Does not call the object's destructor.

void release_all();
Releases all objects back to the pool.
Does not destruct any T objects.

bool is_in_pool(const T* p_object) const;
Checks to see if an object belongs to the pool.
Returns true if it does, otherwise false.

Capacity

bool empty() const
Returns true if there are no allocated objects in the pool, otherwise false.

bool full() const
Returns true if there are no free objects in the pool, otherwise false.

size_t available() const
Returns the remaining available free objects in the pool.

size_t size() const
Returns the number of allocated objects in the pool.

size_t max_size() const
Returns the maximum number of objects in the pool.

Technical stuff

The pool is based around a block of memory, with storage for SIZE items, properly aligned for type T.
Each item in the pool is a union of a uintptr_t and a type T. Free items contain a pointer to the next free item. Allocated
items contain a T value. Allocation is quick as all that is necessary is to return the address of the next free item. Release is
also very quick as the item's content is simply replaced with the address of the current next free item.

On first use the memory block is uninitialised. On each new allocation a new item is initialised with the address of the next
free item. This just-in-time initialisation means that construction does not involve writing to a potentially large amount of
memory in one go.
pool.h