Description:

template<typename TContained>
class alib::monomem::SelfContained< TContained >

This templated class supports the implementation of types whose fields are allocated within a MonoAllocator . In addition the monotonic allocator itself is also self-contained. This results in the following:

The size of an instance of this class is equal to the size of a single C++ pointer. The only member is a pointer to an object of internal type Fields .
A single dynamic memory allocation is performed to create a derived instance of the class.
With method Allocator, the self-contained MonoAllocator can be used to allocate further objects.

ALib uses this type in various areas. A prominent sample is class Exception which is the unique C++ throwable used by the library.
The general use-case for this type is similar to the use-case of class MonoAllocator, with the addition that the life-cycle of the allocated objects are bound to the life-cycle of an instance of the derived type. A well understandable sample for this is found with type Variable implemented in module ALib Configuration .

The proposed schematic for using this class is as follows:

A struct or class named for example MyTypesFields, that incorporates all fields of the self-contained class MyType is to be declared.
Such declaration might be placed in a sub-namespace called detail.
Type MyType inherits this class SelfContained using MyTypesFields as template parameter.
Constructors of MyType invoke the constructor of SelfContained providing the chunk size of the allocator along with the arguments for the construction of MyTypesFields.
The copy-constructor of MyType should either be deleted (the usual case as self-contained objects most probably are not copyable) or defined to create another self-contained object of the derived type.
A move-constructor of MyType should be defined that just invokes this struct's move constructor, forwarding the argument using std::move.
Instead of keyword this, methods of MyType use method Self to access field members (which are defined in helper struct MyTypesFields).
Methods of the derived type might allocate further objects using the internal monotonic allocator, which is accessed with method Allocator.

A quick sample code of this schematic is given with chapter 5.1 Self-Contained Allocators of the Programmer's Manual of this ALib Module .

It is superfluous to say that instances of derived types should not be created using C++ keyword new but instead should be created on stack memory or embedded as value members in other types.

Finally this type supports memory resets. For this, a MonoAllocator::Snapshot is created right after construction. Method Reset resets the internal monotonic allocator using this snapshot. Before that, the TContained object is destructed and afterwards is "re-constructed" using C++ placement new. For the latter, variadic construction parameters are accepted by method Reset.
The memory reserved by Reset can be increased with method TakeSnapshot. Furthermore, the monotonic allocator's pair of methods Reset and TakeSnapshot are also allowed to be used to implement more complex (nested) snapshots.

Template Parameters

TContained Default-constructible type of the stored object.

See also: Chapter 5.1 Self-Contained Allocators of the Programmer's Manual of this ALib Module .
For more complex sample (code) see classes Exception and/or Variable , which uses the mechanisms provided by this type.

Definition at line 83 of file selfcontained.hpp.

#include <selfcontained.hpp>

Collaboration diagram for SelfContained< TContained >:

[legend]

Inner Type Index:
struct	Fields

Public Method Index:
	SelfContained ()=delete

	SelfContained (SelfContained &&move) noexcept

	SelfContained (SelfContained &)=delete

template<typename... TArgs>
	SelfContained (size_t initialChunkSize, unsigned int chunkGrowthInPercent, TArgs &&... args)

	~SelfContained ()

MonoAllocator &	Allocator ()

const MonoAllocator &	Allocator () const

SelfContained &	operator= (SelfContained &&src)

SelfContained &	operator= (SelfContained &)=delete

template<typename... TArgs>
void	Reset (TArgs &&... args)

TContained &	Self ()

const TContained &	Self () const

void	TakeSnapshot ()

Field Details:

◆ fields

template<typename TContained >

Fields* fields

protected

The only member of this class. It points to the start of the 'effective' members, residing in the first chunk of the mono allocator.

Definition at line 125 of file selfcontained.hpp.

Constructor(s) / Destructor Details::

◆ SelfContained() [1/4]

template<typename TContained >

template<typename... TArgs>

SelfContained	(	size_t	initialChunkSize,
		unsigned int	chunkGrowthInPercent,
		TArgs &&...	args )

inline

Creates object fields allocated in the first chunk of the monotonic allocator which is found in that struct.

The instance of custom type TContained which is found in fields will be constructed using the given variadic arguments args .

Template Parameters

TArgs The argument types used for constructing TContained .

Parameters

initialChunkSize	The initial size of memory chunks used with the monotonic allocator.
chunkGrowthInPercent	Optional growth factor in percent (*100), applied to each allocation of a next chunk size. Values provided should be greater than 100.
args	The arguments to construct the instance of TContained .

Definition at line 145 of file selfcontained.hpp.

Here is the call graph for this function:

◆ SelfContained() [2/4]

template<typename TContained >

SelfContained ( )

delete

Deleted default constructor.

◆ SelfContained() [3/4]

template<typename TContained >

SelfContained ( SelfContained< TContained > & )

delete

Deleted copy constructor.

◆ SelfContained() [4/4]

template<typename TContained >

SelfContained ( SelfContained< TContained > && move )

inlinenoexcept

Move constructor. Sets field fields of src to nullptr.

Parameters

move	The object to move.

Definition at line 207 of file selfcontained.hpp.

◆ ~SelfContained()

template<typename TContained >

~SelfContained ( )

inline

Destructor. If fields is not nullptr, the destructors of TContained and the monotonic allocator are explicitly invoked.

Definition at line 237 of file selfcontained.hpp.

Here is the call graph for this function:

Method Details:

◆ Allocator() [1/2]

template<typename TContained >

MonoAllocator & Allocator ( )

inline

Returns a non-constant reference to the self-contained allocator object.

Returns: A reference to the self-contained allocator object.

Definition at line 269 of file selfcontained.hpp.

◆ Allocator() [2/2]

template<typename TContained >

const MonoAllocator & Allocator ( ) const

inline

Returns a constant reference to the self-contained allocator object.

Returns: A constant reference to the self-contained allocator object.

Definition at line 278 of file selfcontained.hpp.

◆ operator=() [1/2]

template<typename TContained >

SelfContained & operator= ( SelfContained< TContained > && src )

inline

Move assignment operator. Sets field fields of src to nullptr.

Parameters

src	The object to move.

Returns: A reference to this object.

Definition at line 225 of file selfcontained.hpp.

◆ operator=() [2/2]

template<typename TContained >

SelfContained & operator= ( SelfContained< TContained > & )

delete

Deleted copy constructor.

Returns: Nothing (deleted).

◆ Reset()

template<typename TContained >

template<typename... TArgs>

void Reset ( TArgs &&... args )

inline

Resets the monotonic allocator that this object is contained in to the snapshot created right after construction. The allocated memory chunks will remain allocated and reused. Prior to resetting, the destructor of the custom object of type TContained is invoked and after the reset, in-place construction is performed.

To preserve further custom objects that might have been initially allocated, method TakeSnapshot might be used after the initial allocations (aka after construction of the derived type). In this case, a derived type should expose an own version of this method which prior and after the invocation this base implementation, either destroys and reconstructs own objects or just leaves them intact.

It is up to the implementation of the derived class if this method should be exposed or not.

It is furthermore allowed to use methods MonoAllocator::TakeSnapshot and MonoAllocator::Reset directly, to allow more flexible, nested snapshots.

Template Parameters

TArgs The argument types used for re-constructing TContained .

Parameters

args	The arguments to re-construct the instance of TContained .

Definition at line 182 of file selfcontained.hpp.

Here is the call graph for this function:

◆ Self() [1/2]

template<typename TContained >

TContained & Self ( )

inline

Returns a non-constant reference to the stored object of type TContained .

Returns: A reference to TContained .

Definition at line 251 of file selfcontained.hpp.

◆ Self() [2/2]

template<typename TContained >

const TContained & Self ( ) const

inline

Returns a constant reference to the stored object of type TContained .

Returns: A constant reference to TContained .

Definition at line 260 of file selfcontained.hpp.

◆ TakeSnapshot()

template<typename TContained >

void TakeSnapshot ( )

inline

With the construction of a self-contained object, a MonoAllocator::Snapshot is taken, used with method Reset to clear the allocator without disposing the memory of the self-contained object itself.

With this method, this snapshot can be modified to use the current fill of the allocator. Note that it is still allowed to reset the monotonic allocator "manually", using custom snapshot objects received with MonoAllocator::TakeSnapshot .

Definition at line 292 of file selfcontained.hpp.

Here is the call graph for this function:

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

selfcontained.hpp

Description:

Inner Type Index:

Public Method Index:

Field Details:

◆ fields

Constructor(s) / Destructor Details::

◆ SelfContained() [1/4]

◆ SelfContained() [2/4]

◆ SelfContained() [3/4]

◆ SelfContained() [4/4]

◆ ~SelfContained()

Method Details:

◆ Allocator() [1/2]

◆ Allocator() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Reset()

◆ Self() [1/2]

◆ Self() [2/2]

◆ TakeSnapshot()