Allocator Struct Reference

Description:

This is class does not exist but is just exposed in the documentation of ALib. Its purpose is to precisely define what an ALib "Allocator" needs to offer as an interface to be usable with ALib template types that expect an allocator.

Implementations of this interface exist with ALib.:

• HeapAllocator,
• TMonoAllocator, its derivate
• TLocalAllocator, and
• TPoolAllocator.

The first is just using std::malloc and std::free, hence it does just the same allocation that C++ keywords new and delete do. The others are introduced and discussed by module ALib Monomem.

As an exception to the naming conventions used by ALib, the members of this type start with a non-capital letter, although they are declared public. This was done to emphasize that an indirect use of this type through type AllocatorInterface is available with operator()(), and such usage is preferred.

Definition at line 150 of file allocation.hpp.

#include <allocation.hpp>

Public Type Index:
using	ChainedAllocator = TAllocator

Public Static Field Index:
static constexpr size_t	MAX_ALIGNMENT
static constexpr size_t	MIN_ALIGNMENT

Public Static Method Index:
static constexpr bool	allowsMemSplit () noexcept

Public Field Index:
const char *	DbgName

Public Method Index:
void *	allocate (size_t &size, size_t alignment)
template<typename TSize >
void	dbgAcknowledgeIncreasedAllocSize (void *mem, TSize allocSize) const
template<typename TSize >
void	dbgCheckMemory (void *mem, TSize size) const
void	free (void *mem, size_t size)
AllocatorInterface< Allocator >	operator() ()
void *	reallocate (void *mem, size_t oldSize, size_t &newSize, size_t alignment)

Type Definition Details:

ChainedAllocator

using ChainedAllocator = TAllocator

The type of the allocator that this allocator uses underneath for its allocations. In case of HeapAllocator, this type is defined as void.
Allocators provided by ALib allow to access the instance with publicly inherited methods GetAllocator and AI.

Definition at line 156 of file allocation.hpp.

Field Details:

DbgName

const char* DbgName

Allocator name. This is a pure debug-field that helps to identify leaks and other issues with allocators. The field is public an may be changed as wanted by a user of the library.

Class MonoAllocator requires a name as the first parameter with every overloaded constructor. Consequently, this argument has to be passed enclosed in macro ALIB_DBG (with a trailing comma) to have it pruned with release-builds.

Class PoolAllocator grabs this name from its chained allocator, which most often is an already named MonoAllocator. Thus, no constructor argument is available. Its name may be changed after construction as appropriate.

Definition at line 232 of file allocation.hpp.

MAX_ALIGNMENT

size_t MAX_ALIGNMENT

staticconstexpr

The maximum alignment an allocator supports.

See also

Chapter 11.1 Alignment of the Programmer's Manual of module ALib Monomem.

Definition at line 167 of file allocation.hpp.

MIN_ALIGNMENT

size_t MIN_ALIGNMENT

staticconstexpr

The minimum alignment an allocator supports, respectively uses even if lower values are requested.

See also

Chapter 11.1 Alignment of the Programmer's Manual of module ALib Monomem.

Definition at line 162 of file allocation.hpp.

Method Details:

allocate()

void * allocate	(	size_t &	size,
		size_t	alignment )

Allocate memory using the allocator.
Note, that parameter size is provided as a reference. If an allocator implementation allocates bigger pieces than requested (which is true for PoolAllocator), then this parameter is modified to this higher value.

Parameters

[in,out]	size	The size of memory the block to allocate in bytes. This is an input and output parameter. Might be increased to the truly allocated size. In case it was increased, the new value does not need to be passed back to reallocate or free. Allocators are agnostic which of the sizes are passed back, the requested, or the true size of the block.
	alignment	The (minimum) alignment of the memory block to allocate in bytes.

Returns

Pointer to the allocated memory.

allowsMemSplit()

static constexpr bool allowsMemSplit ( )

staticconstexprnoexcept

This is a constexpr static method that determines if a type allows splitting memory and later passing the pieces back to free.
Of the allocators exposed by module ALib Monomem, only TMonoAllocator returns true. This is because this allocator has an empty free method and thus is agnostic about the memory freed. If compiler symbol ALIB_DEBUG_ALLOCATIONS is set, then also this allocator returns false.

Returns

true if this allocator is agnostic against freeing of objects which have not been allocated as given.

dbgAcknowledgeIncreasedAllocSize()

template<typename TSize >

void dbgAcknowledgeIncreasedAllocSize	(	void *	mem,
		TSize	allocSize ) const

This method has to be called to set the correct object size in the case that: a) An allocation method returned a higher allocation size (as of the current ALib release, this only happens with the use of class PoolAllocator, and b) this higher size is not ignored by the using code and, c) this higher size is reported to one of the free-methods on object destruction.

Within ALib a sample of such a type is class AString: this type requests a string buffer as needed but acknowledges if the returned buffer is lager. With destruction, this higher capacity is passed when the buffer is deleted. Thus, this type invokes this method after performing allocations.

Note that this method is empty and optimized out, when compiler symbol ALIB_DEBUG_ALLOCATIONS is not set. If set, an ALib assertion is raised if either the magic bytes around the memory are not found, or the given allocSize does not

See also

Chapter 11.4 Debugging of the Programmer's Manual.

Template Parameters

TSize

The type of parameter allocSize. (Deduced by the compiler.)

Parameters

mem	The address of the allocated object.
allocSize	The true allocation size returned by the method allocate .

dbgCheckMemory()

template<typename TSize >

void dbgCheckMemory	(	void *	mem,
		TSize	size ) const

If the compiler symbol ALIB_DEBUG_ALLOCATIONS is not set, this method is empty and will be optimized out. Otherwise, this will raise an ALib assertion if the piece of allocated memory is corrupted or its allocation size is not rightfully given by the using code.

See also

Chapter 11.4 Debugging of the Programmer's Manual.

Template Parameters

TSize

The type of parameter size. (Deduced by the compiler.)

Parameters

mem	The address of the allocated object.
size	The requested allocation size of the object.

free()

void free	(	void *	mem,
		size_t	size )

Frees memory that was previously allocated with the same allocator.

Parameters

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

operator()()

AllocatorInterface< Allocator > operator()

(

)

Returns a temporary object (which is usually optimized out together with a call to this operator) providing high-level convenience methods for allocation.

See also

Class lang::AllocatorInterface

Returns

A temporary high-level interface into the allocator.

reallocate()

void * reallocate	(	void *	mem,
		size_t	oldSize,
		size_t &	newSize,
		size_t	alignment )

Shrinks or grows a piece of memory. If a new allocation was performed the existing data is copied. Note, that parameter newSize is provided as a reference. If an allocator implementation allocates bigger pieces than requested (which is true for PoolAllocator), then this parameter is modified to this higher value.

Parameters

	mem	The memory to reallocate.
	oldSize	The current size of mem.
[in,out]	newSize	The new size of memory requested to allocate in bytes. This is an input and output parameter. It might be increased to the truly allocated size.
	alignment	The (minimum) alignment of the memory block to allocate in bytes.

Returns

Pointer to the re-allocated memory.

---

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

• allocation.hpp