Description:

template<typename T, typename TAllocator>
struct alib::lang::StdContainerAllocator< T, TAllocator >

This struct is an implementation of C++ standard library type std::allocator. It is to be used with container types provided by the C++ standard library in combination with ALib Allocators.

With the inclusion of module ALib Monomem in the ALib Build, this allocator is suitable to use cases of strict or weak monotonic allocation.

Shortcuts for Specific ALib Allocators

The following alias type definitions exist for this type, each addressing a specific allocator:

SCAMono, and
SCAPool.

Along with this, shortcuts to the container types are likewise provided with:

Resetting A Container

While the dedicated container types provided with module ALib Containers offer a method named Reset (see for example HashTable::Reset), the C++ standard containers do not. This is a challenge because their internal memory will be invalid with a reset. For example, if allocator type MonoAllocator was used with calss std::vector, there is no interface method that makes the vector "forget" its internal data array. Its method shrink_to_fit by its specification is not forced to shrink anything or even dispose the data if the size was 0 when called. This is implementation-dependent.

The way out is as simple as radical: The container is just to be destructed and reconstructed "in place". This can be done using a C++ placement-new. The following code snippet demonstrates this:

// field members  or global objects
alib::MonoAllocator allocator( ALIB_DBG("MyAllocator",)  4);
std::vector<MyData, SCAMono<MyData>> transactionObjects( allocator );
 
// method using the allocator and the vector
void processTransaction( /* transaction data */)
{
    // perform transaction, collecting stuff in vector and/or allocator
    // ...
    // ...
    // ...
 
    // before we leave we reset the vector and the allocator:
 
    // 1. Destruct the container and contained objects.
    //    (In case contained objects are trivially destructible, this is not
    //    needed and usually optimized out by the compiler.)
    allocator().Delete(&transactionObjects);
 
    // 2. Reset allocator
    allocator.Reset();
 
    // 3. Placement new on the vector object
    new( &transactionObjects ) std::vector<MyData, SCAMono<MyData>>( allocator );
}
 

See also

An alternative version that recycles nodes (and also bucket arrays in case of std::unordered_set and std::unordered_map), is provided with sibling type StdContainerAllocatorRecycling.
Type definitions SCAMono and SCAPool given with module ALib Monomem.
Further shortcuts for standard container types, given with StdVectorMono, StdVectorPool, StdListMono, StdListPool, StdDequeMono, and StdDequePool.

Template Parameters

T	The type of objects to be allocated.
TAllocator	The allocator type, as prototyped with Allocator.

Definition at line 89 of file stdcontainerallocator.inl.

Inheritance diagram for alib::lang::StdContainerAllocator< T, TAllocator >:

[legend]

Collaboration diagram for alib::lang::StdContainerAllocator< T, TAllocator >:

[legend]

Public Type Index:
using	allocBase = AllocatorMember<TAllocator>
	The allocator type that TAllocator specifies.

Public Type Index: inherited from alib::lang::detail::StdContainerAllocatorBase< T, TAllocator >
using	AllocatorType = TAllocator
	The allocator type that TAllocator specifies.

using	const_reference = const T&
	Type definition as required by C++ library standards.

using	difference_type = ptrdiff_t
	Type definition as required by C++ library standards.

using	is_always_equal = std::false_type
	Type definition as required by C++ library standards.

using	reference = T&
	Type definition as required by C++ library standards.

using	size_type = size_t
	Type definition as required by C++ library standards.

using	value_type = T
	Type definition as required by C++ library standards.

Public Type Index: inherited from alib::lang::AllocatorMember< TAllocator >
using	AllocatorType = TAllocator
	Exposes the allocator type.

Public Method Index:
	StdContainerAllocator ()=default
	Parameterless constructor used with heap allocation.

constexpr	StdContainerAllocator (const StdContainerAllocator &) noexcept=default
	Defaulted copy constructor.

template<typename TSibling>
	StdContainerAllocator (const StdContainerAllocator< TSibling, TAllocator > &origin)

template<typename TSibling> requires alib::lang::IsAllocator<typename TSibling::allocator>
	StdContainerAllocator (const TSibling &origin)

constexpr	StdContainerAllocator (StdContainerAllocator &&) noexcept=default
	Defaulted move constructor.

	StdContainerAllocator (TAllocator &pAllocator)

T *	allocate (size_t n, const void *=nullptr)

void	deallocate (T *p, std::size_t n)

template<typename U>
bool	operator!= (const StdContainerAllocator< U, TAllocator > &rhs) const noexcept

template<typename U>
bool	operator== (const StdContainerAllocator< U, TAllocator > &rhs) const noexcept

Public Method Index: inherited from alib::lang::AllocatorMember< TAllocator >
	AllocatorMember ()=delete
	Deleted default constructor. (The allocator has to be given with construction)

	AllocatorMember (TAllocator &pAllocator) noexcept

AllocatorInterface< TAllocator >	AI () const noexcept

TAllocator &	GetAllocator () const noexcept

Additional Inherited Members
Protected Field Index: inherited from alib::lang::AllocatorMember< TAllocator >
TAllocator &	allocator
	A reference to the allocator.

Type Definition Details:

◆ allocBase

template<typename T, typename TAllocator>

using alib::lang::StdContainerAllocator< T, TAllocator >::allocBase = AllocatorMember<TAllocator>

The allocator type that TAllocator specifies.

Definition at line 93 of file stdcontainerallocator.inl.

Constructor(s) / Destructor Details:

◆ StdContainerAllocator() [1/3]

template<typename T, typename TAllocator>

template<typename TSibling>
requires alib::lang::IsAllocator<typename TSibling::allocator>

alib::lang::StdContainerAllocator< T, TAllocator >::StdContainerAllocator ( const TSibling & origin )

inline

Copy constructor using an instance of a different template type.

Template Parameters

TSibling The originating allocator's type (StdContainerAllocator<X>).

Parameters

origin The originating allocator of type TSibling .

Definition at line 106 of file stdcontainerallocator.inl.

◆ StdContainerAllocator() [2/3]

template<typename T, typename TAllocator>

template<typename TSibling>

alib::lang::StdContainerAllocator< T, TAllocator >::StdContainerAllocator ( const StdContainerAllocator< TSibling, TAllocator > & origin )

inline

Copy constructor using an instance of different template type.

Template Parameters

TSibling The originating allocator's type (StdContainerAllocator<X>).

Parameters

origin The originating allocator of type TSibling .

Definition at line 114 of file stdcontainerallocator.inl.

◆ StdContainerAllocator() [3/3]

template<typename T, typename TAllocator>

alib::lang::StdContainerAllocator< T, TAllocator >::StdContainerAllocator ( TAllocator & pAllocator )

inline

Constructor for the initial allocator instantiation.

Parameters

pAllocator The allocator.

Definition at line 120 of file stdcontainerallocator.inl.

Method Details:

◆ allocate()

template<typename T, typename TAllocator>

T * alib::lang::StdContainerAllocator< T, TAllocator >::allocate	(	size_t	n,
		const void *	= nullptr )

inlinenodiscard

Passes the allocation request to the AllocatorMember.

Parameters

n	The number of requested objects to allocate storage for.

Returns: Pointer to the start of the array of n objects of type T.

Definition at line 162 of file stdcontainerallocator.inl.

◆ deallocate()

template<typename T, typename TAllocator>

void alib::lang::StdContainerAllocator< T, TAllocator >::deallocate	(	T *	p,
		std::size_t	n )

inline

Frees the given array of objects.

Parameters

p	Pointer to the previously allocated memory.
n	The number of objects allocated.

Definition at line 170 of file stdcontainerallocator.inl.

◆ operator!=()

template<typename T, typename TAllocator>

template<typename U>

bool alib::lang::StdContainerAllocator< T, TAllocator >::operator!= ( const StdContainerAllocator< U, TAllocator > & rhs ) const

inlinenoexcept

Comparison operator.

Template Parameters

U	The allocation type of the other allocator.

Parameters

rhs	The right hand side allocator.

Returns: false if this and rhs use the same allocator, true otherwise.

Definition at line 146 of file stdcontainerallocator.inl.

◆ operator==()

template<typename T, typename TAllocator>

template<typename U>

bool alib::lang::StdContainerAllocator< T, TAllocator >::operator== ( const StdContainerAllocator< U, TAllocator > & rhs ) const

inlinenoexcept

Comparison operator.

Template Parameters

U	The allocation type of the other allocator.

Parameters

rhs	The right hand side allocator.

Returns: true if this and rhs use the same allocator, false otherwise.

Definition at line 136 of file stdcontainerallocator.inl.

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

stdcontainerallocator.inl

Description:

Shortcuts for Specific ALib Allocators

Resetting A Container

Public Type Index:

Public Method Index:

Additional Inherited Members

Type Definition Details:

◆ allocBase

Constructor(s) / Destructor Details:

◆ StdContainerAllocator() [1/3]

◆ StdContainerAllocator() [2/3]

◆ StdContainerAllocator() [3/3]

Method Details:

◆ allocate()

◆ deallocate()

◆ operator!=()

◆ operator==()