AllocatorInterface< TAllocator > Struct Template Reference

Description:

template<typename TAllocator>
struct alib::lang::AllocatorInterface< TAllocator >

This type offers high-level convenience methods for ALib allocators.
An ALib allocator (a type that offers an interface as specified with prototype Allocator) has to provide only three low-level (!) allocation methods. Those are:

• allocate(size_t& size, size_t alignment),
• reallocate(void* mem, size_t oldSize, size_t& newSize, size_t alignment),
• free(void* disposable, size_t size), and

Besides these, the C++ function call operator operator()() has to be implemented to return a temporary instance of this type. Note that the compiler will optimize the function call and the temporary instance out. With this setup, each allocator offers the high-level allocation methods provided with this class.

The naming scheme of the convenience methods found with this type, is along the standards:

• Methods containing the words "Alloc" or "Free" allocate, respectively free memory without construction, respectively destruction of type instances.
• Methods containing the word "New" and "Delete" allocate, respectively free memory and in addition invoke constructors, respectively destructors of type instances.

In contrast to the low-level interface methods Allocator::allocate and Allocator::reallocate, information about a piece of memory returned that is larger than requested is not retrievable with the methods provided here. In case this can be of value, the low-level interface of an allocator has to be used.

The following quick sample illustrates the use of this class in combination with a TMonoAllocator:

// sample type
struct MyType
{
    // the member
    alib::String member;
 
    // constructor
    MyType( const alib::String& pMember)
    : member(pMember)
    {}
};

// Create an allocator (with 4kB initial buffer).
MonoAllocator allocator(ALIB_DBG("MyAllocator",) 4);
 
// Use operator->() on the allocator and invoke high-level interface
MyType* myObject= allocator().New<MyType>(A_CHAR("Hello"));
 
///...
///...
 
// Destruct the object and free the memory
allocator().Delete(myObject);

Note

In this sample, the destructor is of class MyType is emtpy, and furthermore method free of class MonoAllocator is empty. Thus, the whole call to Delete will be optimized out. With other allocators this is different. It is recommended to still include such calls to avoid memory leaks at the moment either the allocator is changed, an allocated type gets equipped with a destructor, etc.

See also

• The Programmer's Manual of module ALib Monomem.
• Allocator types TMonoAllocator and TPoolAllocator found in module ALib Monomem.
• Class HeapAllocator, which is useful for templated types which are agnostic to underlying allocation strategies.
• To allocate and create a copy of a character string, method TString::Allocate or constructor TString(TAllocator& allocator, const TString<TChar>&) may be used. Freeing is then to be performed by using TString::Free.

Definition at line 322 of file allocation.hpp.

#include <allocation.hpp>

Public Field Index:
TAllocator &	allocator
	The allocator type to use.

Public Method Index:
	AllocatorInterface (TAllocator &pAllocator)
template<typename T >
T *	Alloc ()
template<typename TSize , typename TAlignment >
void *	Alloc (TSize size, TAlignment alignment)
template<typename T , typename TLength >
T *	AllocArray (TLength length)
template<typename T >
void	Delete (T *object)
template<typename T , typename TIntegral >
void	DeleteArray (T *array, TIntegral length)
template<typename T >
void	Free (T *mem)
template<typename T , typename TIntegral >
void	Free (T *mem, TIntegral size)
template<typename T , typename TIntegral >
void	FreeArray (T *array, TIntegral length)
template<typename T , typename... TArgs>
ALIB_FORCE_INLINE T *	New (TArgs &&... args)
template<typename T , typename TSize , typename... TArgs>
T *	NewArray (TSize length, TArgs &&... args)

Field Details:

allocator

template<typename TAllocator >

TAllocator& allocator

The allocator type to use.

Definition at line 325 of file allocation.hpp.

Constructor(s) / Destructor Details:

AllocatorInterface()

template<typename TAllocator >

AllocatorInterface ( TAllocator & pAllocator )

inline

Constructor. Usually construction is performed by the function operator of the an Allocator, which then passes itself as parameter pAllocator.

Parameters

pAllocator

The allocator.

Definition at line 330 of file allocation.hpp.

Method Details:

Alloc() [1/2]

template<typename TAllocator >

template<typename T >

T * Alloc ( )

inline

Allocates memory of sizeof(T) and alignof(T).

Template Parameters

T	The type of object to allocate memory for.

Returns

A pointer to the allocated memory.

Definition at line 351 of file allocation.hpp.

Alloc() [2/2]

template<typename TAllocator >

template<typename TSize , typename TAlignment >

void * Alloc ( TSize size, TAlignment alignment )

inline

Allocates memory of the requested size and alignment.

Template Parameters

TSize	The type of parameter size. Deduced by the compiler. (Must be integral.)
TAlignment	The type of parameter alignment. Deduced by the compiler. (Must be integral.)

Parameters

size	The allocation size requested.
alignment	The required alignment.

Returns

A pointer to the allocated memory.

Definition at line 341 of file allocation.hpp.

AllocArray()

template<typename TAllocator >

template<typename T , typename TLength >

T * AllocArray ( TLength length )

inline

Allocates aligned memory for an array of objects of type T of size length leaving the memory uninitialized.

Template Parameters

T	The array element type.
TLength	The type of parameter length. Has to be integral. Deduced by the compiler.

Parameters

length

The capacity of the requested array.

Returns

A pointer to the first element of the allocated array.

Definition at line 365 of file allocation.hpp.

Delete()

template<typename TAllocator >

template<typename T >

void Delete ( T * object )

inline

Calls the destructor of the given object of type T and then frees the memory with the associated allocator.

Attention

In the context of single inheritance, this convenience function supports deleting pointers to objects of base types, also when they were previously allocated using a derived type, provided that virtual destructors are in place. Virtual destructors ensure that the appropriate destructor is called, preventing resource leaks.

However, in cases of multiple inheritance, passing pointers to base types for deletion might lead to undefined behavior. The underlying challenge here is that safely converting a base type pointer back to the originally allocated derived type pointer (as required for correct memory deallocation) is not feasible with standard C++ mechanisms. While the C++ delete operator is equipped to handle such scenarios - thanks to internal compiler implementations that track the original pointer - standard C++ does not expose a portable way to replicate this functionality. Consequently, objects utilizing multiple inheritance have to be deleted using the same derived type pointer that was used for allocation.

Template Parameters

T	The type that parameter object points to.

Parameters

object

The object to delete.

Definition at line 426 of file allocation.hpp.

DeleteArray()

template<typename TAllocator >

template<typename T , typename TIntegral >

void DeleteArray ( T * array, TIntegral length )

inline

Destructs all array elements and frees the array's memory.

Template Parameters

T	The pointer type of parameter array.
TIntegral	Integral type of parameter size. Deduced by the compiler.

Parameters

array	Pointer to the first array element.
length	The size of the given mem.

Definition at line 439 of file allocation.hpp.

Free() [1/2]

template<typename TAllocator >

template<typename T >

void Free ( T * mem )

inline

Frees memory of size sizeof(T) pointed to by mem. This method does not call a destructor. To dispose custom types with due destruction, use method Delete<T>(T*).

Template Parameters

T	The pointer type of the given mem to free.

Parameters

mem	The memory to free.

Definition at line 457 of file allocation.hpp.

Free() [2/2]

template<typename TAllocator >

template<typename T , typename TIntegral >

void Free ( T * mem, TIntegral size )

inline

Frees memory of given size pointed to by mem. This method does not call a destructor. To dispose custom types with due destruction, use method Delete<T>(T*).

Template Parameters

T	The pointer type of the given mem to free.
TIntegral	The type that parameter size is provided with. Deduced by the compiler. (Has to be integral.)

Parameters

mem	The memory to free.
size	The size of the given mem.

Definition at line 473 of file allocation.hpp.

FreeArray()

template<typename TAllocator >

template<typename T , typename TIntegral >

void FreeArray ( T * array, TIntegral length )

inline

Frees memory of an array of objects. This method does not call a destructor. To also destruct the elements of an array, use method DeleteArray<T>(T*, TIntegral).

Template Parameters

T	The pointer type of parameter array.
TIntegral	Integral type of parameter size. Deduced by the compiler.

Parameters

array	Pointer to the first array element.
length	The size of the given mem.

Definition at line 487 of file allocation.hpp.

New()

template<typename TAllocator >

template<typename T , typename... TArgs>

ALIB_FORCE_INLINE T * New ( TArgs &&... args )

inline

Allocates memory of size- and alignment-suitable for type T and performs a C++ "placement-new", passing the given variadic arguments to the type's constructor.

Template Parameters

T	Type of the object to allocate and construct.
TArgs	Types of variadic parameters given with parameter args.

Parameters

args	Variadic parameters to be forwarded to the constructor of type T.

Returns

A pointer to the initialized array.

Definition at line 379 of file allocation.hpp.

NewArray()

template<typename TAllocator >

template<typename T , typename TSize , typename... TArgs>

T * NewArray ( TSize length, TArgs &&... args )

inline

Allocates aligned memory for an array of objects of type T of size length. All array elements are initialized using a "placement-new", passing the given args to each element's constructor.

Template Parameters

T	Element type of the array to allocate and construct.
TArgs	Types of variadic parameters given with parameter args.
TSize	The type of parameter length. Deduced by the compiler. (Must be integral.)

Parameters

length	The capacity of the requested array.
args	Variadic parameters to be forwarded to the constructor of each array element of type T.

Returns

A pointer to the first element of the allocated array.

Definition at line 394 of file allocation.hpp.

---

The documentation for this struct was generated from the following file:

• allocation.hpp