This abstract class defines the interface for a Memory Allocator. More...

Detailed Description

This abstract class defines the interface for a Memory Allocator.

A Memory Allocator manages a pool memory that is assigned/released to/from clients at run-time (i.e. provides the memory for "dynamic" memory allocations).

The following is an example on how to dynamically create/destroy object using the memory provided by a Allocator object:

Example of placement new:
-------------------------
#include <new>
#include "Cpl/Memory/Allocator.h"
 
class Foo { .... };
 
Foo* newMe( Allocator& src, ...)
    {
    // Get a chunk memory large enough to contain an instance of Foo
    void* mem = src.allocate(sizeof(Foo));
 
    // Create an instance Foo using placement new
    if ( mem )
        {
        return new(mem) Foo(...);
        }
    else
        {
        // error condition: not enough memory. Do...
        return 0;
        }
    }
 
 
Example of delete for an object created with by placement new:
--------------------------------------------------------------
void deleteMe( Foo* ptr, Allocator& src )
    {
    // Since delete is not called ->I have to Explicitly call the destructor!
    ptr->~Foo();
 
    // Release the memory back to the MemorySource
    src.release(ptr);
    }

#include <Allocator.h>

Inheritance diagram for Cpl::Memory::Allocator:

[legend]

Collaboration diagram for Cpl::Memory::Allocator:

[legend]

Public Member Functions
virtual void *	allocate (size_t numbytes)=0
	Allocate and returns a pointer to at least numBytes of storage.

virtual void	release (void *ptr)=0
	Frees memory that was allocated via the allocate() method.

virtual size_t	wordSize () const noexcept=0
	Returns the 'word' size of the allocator, i.e.

size_t	allocatedSizeForNBytes (size_t nbytes) const noexcept
	Convenience method that determines the actual amount of memory that actually allocated for a successful allocate request of N bytes.

virtual	~Allocator ()
	Provide a virtual destructor.

Public Member Functions inherited from Cpl::Container::Item
bool	insert_ (void *newContainerPtr)
	Helper method to trap when inserting an item in multiple containers.

bool	isInContainer_ (const void *containerPtr) const noexcept
	Returns 'true' if the instance is in the specified container.

Additional Inherited Members
Static Public Member Functions inherited from Cpl::Container::Item
static void	remove_ (Item *itemPtr) noexcept
	Helper method to do the proper 'clean-up' for the multiple-containers-error-trap when removing an item from a container.

Public Attributes inherited from Cpl::Container::Item
void *	m_nextPtr_
	The link field.

void *	m_inListPtr_
	Debug field.

Protected Member Functions inherited from Cpl::Container::Item
	Item ()
	Constructor.

	Item (const char *)
	Constructor used ONLY with the child class MapItem: -->special constructor to allow a Map to be statically allocated.

Constructor & Destructor Documentation

◆ ~Allocator()

virtual Cpl::Memory::Allocator::~Allocator ( )

inlinevirtual

Provide a virtual destructor.

Member Function Documentation

◆ allocate()

virtual void * Cpl::Memory::Allocator::allocate ( size_t numbytes )

pure virtual

Allocate and returns a pointer to at least numBytes of storage.

Returns 0 if out of memory.

Implemented in Cpl::Memory::HPool< T >, Cpl::Memory::LeanHeap, Cpl::Memory::Pool_, Cpl::Memory::SPool< T, N >, Cpl::Memory::SPool< Cpl::Io::File::Littlefs::FileDesc_T, OPTION_CPL_IO_FILE_LITTLEFS_MAX_CONCURRENT_FILES >, and Cpl::Memory::SPool< Cpl::Io::Socket::InputOutput, N >.

◆ allocatedSizeForNBytes()

size_t Cpl::Memory::Allocator::allocatedSizeForNBytes ( size_t nbytes ) const

inlinenoexcept

Convenience method that determines the actual amount of memory that actually allocated for a successful allocate request of N bytes.

◆ release()

virtual void Cpl::Memory::Allocator::release ( void * ptr )

pure virtual

Frees memory that was allocated via the allocate() method.

It is VERY IMPORTANT that the memory is allocate() and release() from/to the SAME MemorySource Instance!

NOTES:

1) Freeing a 0 pointer causes release() to return immediately
   without any errors.

2) The pointer released() MUST be the same value as the pointer
   that was returned by the allocate().  This is particularly
   important if the memory allocated is used to create a
   concrete object that inherits multiple abstract/virtual
   interfaces.  When deleting the object, the pointer value
   passed to the release() method must be a pointer type of
   concrete object - NOT a pointer to any of its parent classes.
   This is required to prevent possible memory leaks because of
   the C++ magic where the actual pointer value to the concrete
   object is not necessarily the same pointer value when the pointer
   is up-cast to one of its abstract base classes!

Implemented in Cpl::Memory::HPool< T >, Cpl::Memory::Pool_, Cpl::Memory::SPool< T, N >, Cpl::Memory::SPool< Cpl::Io::File::Littlefs::FileDesc_T, OPTION_CPL_IO_FILE_LITTLEFS_MAX_CONCURRENT_FILES >, and Cpl::Memory::SPool< Cpl::Io::Socket::InputOutput, N >.

◆ wordSize()

virtual size_t Cpl::Memory::Allocator::wordSize ( ) const

pure virtualnoexcept

Returns the 'word' size of the allocator, i.e.

chunks of memory are allocate in multiple of this size. For example: Given a word size of 4 and memory request for 5 bytes - the allocated would actually allocate 8 bytes of memory, i.e. 2 * 4 >= 5