StdContMA< T > Struct Template Reference

#include <stdcontainerma.hpp>

Inheritance diagram for StdContMA< T >:

Collaboration diagram for StdContMA< T >:

Class Description

template<typename T>
struct aworx::lib::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
aworx::MonoAllocator allocator( 4096 );
std::vector<MyData, aworx::StdContMA<MyData>> transactionObjects(
    ( aworx::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, aworx::StdContMA<MyData>>(
        aworx::StdContMA<MyData>( allocator ) );
}
 

Template Parameters

T	The type of objects to be allocated.

Definition at line 161 of file stdcontainerma.hpp.

Inner Classes
struct	rebind

Public Fields
MonoAllocator &	allocator
bool	dbgDeallocationWarning

Public Methods
	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)
ALIB_NODISCARD 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 Methods inherited from StdContainerMABase< T >
const_pointer	address (const_reference x) const noexcept
pointer	address (reference x) const noexcept
template<typename U , typename... Args>
void	construct (U *p, Args &&... args)
template<typename U >
void	destroy (U *p)
size_t	max_size () const noexcept

Additional Inherited Members
Public Types inherited from StdContainerMABase< T >
using	const_pointer = const T *
using	const_reference = const 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	pointer = T *
using	reference = T &
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.

Constructor & Destructor Documentation

StdContMA() [1/5]

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. Due to the fact that 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]

constexpr StdContMA ( const StdContMA< T > &  )

constexprdefaultnoexcept

Defaulted copy constructor

StdContMA() [3/5]

constexpr StdContMA ( StdContMA< T > &&  )

constexprdefaultnoexcept

Defaulted move constructor

StdContMA() [4/5]

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 222 of file stdcontainerma.hpp.

StdContMA() [5/5]

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.

Member Function Documentation

allocate()

ALIB_NODISCARD 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 289 of file stdcontainerma.hpp.

Here is the call graph for this function:

deallocate()

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 300 of file stdcontainerma.hpp.

operator!=()

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 272 of file stdcontainerma.hpp.

operator==()

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 260 of file stdcontainerma.hpp.

Member Data Documentation

allocator

MonoAllocator& allocator

The allocator to use.

Definition at line 184 of file stdcontainerma.hpp.

dbgDeallocationWarning

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 190 of file stdcontainerma.hpp.

---

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

• stdcontainerma.hpp