Description:

template<typename T>
struct alib::monomem::StdContMA< T >

Implementation of std::allocator to be used with container types provided by the C++ standard library.

This allocator is suitable to use cases of strict or weak monotonic allocation. An alternative version that recycles nodes (and for example bucket arrays in case of std::unordered_set and std::unordered_map), is provided with sibling type StdContMARecycling .

A further alternative is given with type StdContMAOptional , which accepts a pointer instead of a reference to an allocator and allows this pointer to be nullptr, which switches to dynamic allocation.

Resetting A Container

While the dedicated container types provided with this ALib Module offer a method named Reset (see for example HashTable::Reset ), the C++ std containers of-course do not. This is a challenge, because their internal memory will be invalid with a reset of the monotonic allocator used, and for example with class std::vector there is no interface method that makes them "forget" their 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 reconstructed without prior destruction. This can be done using a C++ placement new. The following code snippet demonstrates this:

// field members  or global objects
alib::MonoAllocator allocator( 4096 );
std::vector<MyData, alib::StdContMA<MyData>> transactionObjects(
    ( alib::StdContMA<MyData>( 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 contained objects. Not needed if trivially destructible.
    transactionObjects.clear();
 
    // 2. Reset allocator
    allocator.Reset();
 
    // 3. Placement new on the vector object
    new( &transactionObjects ) std::vector<MyData, alib::StdContMA<MyData>>(
        alib::StdContMA<MyData>( allocator ) );
}
 

Template Parameters

T	The type of objects to be allocated.

Definition at line 93 of file stdcontainerma.hpp.

#include <stdcontainerma.hpp>

Inheritance diagram for StdContMA< T >:

[legend]

Collaboration diagram for StdContMA< T >:

[legend]

Public Field Index:
MonoAllocator &	allocator

bool	dbgDeallocationWarning

Public Method Index:
	StdContMA ()

constexpr	StdContMA (const StdContMA &) noexcept=default

constexpr	StdContMA (MonoAllocator &pAllocator, bool dbgDeallocationWarning=true)

constexpr	StdContMA (StdContMA &&) noexcept=default

template<typename TSibling >
	StdContMA (TSibling &origin)

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

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

template<typename U >
bool	operator!= (const StdContMA< U > &rhs) const noexcept

template<typename U >
bool	operator== (const StdContMA< U > &rhs) const noexcept

Public Method Index: inherited from StdContainerMABase< T >
size_t	max_size () const noexcept

Additional Inherited Members
Public Type Index: inherited from StdContainerMABase< T >
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	size_type = size_t
	Type definition as required by C++ library standards.

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

Field Details:

◆ allocator

template<typename T >

MonoAllocator& allocator

The allocator to use.

Definition at line 99 of file stdcontainerma.hpp.

◆ dbgDeallocationWarning

template<typename T >

bool dbgDeallocationWarning

If true warnings about de-allocation of objects are suppressed. this should be set prior to destructing a container that uses this allocator.
Available only in debug builds.

Definition at line 105 of file stdcontainerma.hpp.

Constructor(s) / Destructor Details::

◆ StdContMA() [1/5]

template<typename T >

StdContMA ( )

inline

Default constructor declared, but not defined.

Attention: Due to the way standard container types use template struct std::allocator) that this object implements, the default constructor has to be declared. However, because field allocator is of reference type, no declaration can be made.
With the construction of a container type that uses this allocator, it has to be assured that a valid instance is passed. Otherwise the compiler will complain about not finding this constructor's definition.

◆ StdContMA() [2/5]

template<typename T >

constexpr StdContMA ( const StdContMA< T > & )

constexprdefaultnoexcept

Defaulted copy constructor

◆ StdContMA() [3/5]

template<typename T >

constexpr StdContMA ( StdContMA< T > && )

constexprdefaultnoexcept

Defaulted move constructor

◆ StdContMA() [4/5]

template<typename T >

template<typename TSibling >

StdContMA ( TSibling & origin )

inline

Copy constructor using an instance of different template type.

Template Parameters

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

Parameters

origin The originating allocator of type TSibling .

Definition at line 137 of file stdcontainerma.hpp.

◆ StdContMA() [5/5]

template<typename T >

constexpr StdContMA	(	MonoAllocator &	pAllocator,
		bool	dbgDeallocationWarning = true )

constexpr

Constructor for the initial allocator instantiation.

Parameter dbgDisableDeallocationWarning , which defaults to true might be given after a code is tested to be stict in respect to allocation. (Note: unfortunately, due to the ^design of std::allocator and its use, this flag can not be changed once a container is constructed. This is why it has to be decided upfront if a warning is to be raised or not). ^

Parameters

pAllocator	The recycler for allocations and de-allocations.
dbgDeallocationWarning	As described with this method. Available only in debug builds.

Method Details:

◆ allocate()

template<typename T >

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

inline

Passes the allocation request to field allocator.

Parameters

n	The number of requested objects to allocate storage for.

Returns: Pointer to the first byte of a memory block suitably aligned and sufficient to hold an array of n objects of type T .

Definition at line 204 of file stdcontainerma.hpp.

Here is the call graph for this function:

◆ deallocate()

template<typename T >

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

inline

If allocator is not set, invokes std::free(p). Otherwise does nothing.

Parameters

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

Definition at line 215 of file stdcontainerma.hpp.

◆ operator!=()

template<typename T >

template<typename U >

bool operator!= ( const StdContMA< U > & 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 187 of file stdcontainerma.hpp.

◆ operator==()

template<typename T >

template<typename U >

bool operator== ( const StdContMA< U > & 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 175 of file stdcontainerma.hpp.

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

stdcontainerma.hpp

Description:

Resetting A Container

Public Field Index:

Public Method Index:

Additional Inherited Members

Field Details:

◆ allocator

◆ dbgDeallocationWarning

Constructor(s) / Destructor Details::

◆ StdContMA() [1/5]

◆ StdContMA() [2/5]

◆ StdContMA() [3/5]

◆ StdContMA() [4/5]

◆ StdContMA() [5/5]

Method Details:

◆ allocate()

◆ deallocate()

◆ operator!=()

◆ operator==()