#include <selfcontained.hpp>

Collaboration diagram for SelfContained< TContained >:

Class Description

template<typename TContained>
class aworx::lib::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 87 of file selfcontained.hpp.

Inner Classes
struct	Fields

Public Methods
	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 ()

Protected Fields
Fields *	fields

Constructor & Destructor Documentation

◆ SelfContained() [1/4]

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 149 of file selfcontained.hpp.

◆ SelfContained() [2/4]

SelfContained ( )

delete

Deleted default constructor.

◆ SelfContained() [3/4]

SelfContained ( SelfContained< TContained > & )

delete

Deleted copy constructor.

◆ SelfContained() [4/4]

SelfContained ( SelfContained< TContained > && move )

inlinenoexcept

Move constructor. Sets field fields of src to nullptr.

Parameters

move	The object to move.

Definition at line 211 of file selfcontained.hpp.

◆ ~SelfContained()

~SelfContained ( )

inline

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

Definition at line 241 of file selfcontained.hpp.

Member Function Documentation

◆ Allocator() [1/2]

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 273 of file selfcontained.hpp.

◆ Allocator() [2/2]

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 282 of file selfcontained.hpp.

◆ operator=() [1/2]

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 229 of file selfcontained.hpp.

◆ operator=() [2/2]

SelfContained& operator= ( SelfContained< TContained > & )

delete

Deleted copy constructor.

Returns: Nothing (deleted).

◆ Reset()

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(const Snapshot&) 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 186 of file selfcontained.hpp.

◆ Self() [1/2]

TContained& Self ( )

inline

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

Returns: A reference to TContained.

Definition at line 255 of file selfcontained.hpp.

◆ Self() [2/2]

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 264 of file selfcontained.hpp.

◆ TakeSnapshot()

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 296 of file selfcontained.hpp.

Member Data Documentation

◆ fields

Fields* fields

protected

The monotonic allocator created with MonoAllocator::Create, hence self-contained in its first chunk.

Definition at line 129 of file selfcontained.hpp.

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

selfcontained.hpp

Class Description

template<typename TContained> class aworx::lib::monomem::SelfContained< TContained >

Inner Classes

Public Methods

Protected Fields

Constructor & Destructor Documentation

◆ SelfContained() [1/4]

◆ SelfContained() [2/4]

◆ SelfContained() [3/4]

◆ SelfContained() [4/4]

◆ ~SelfContained()

Member Function Documentation

◆ Allocator() [1/2]

◆ Allocator() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Reset()

◆ Self() [1/2]

◆ Self() [2/2]

◆ TakeSnapshot()

Member Data Documentation

◆ fields

template<typename TContained>
class aworx::lib::monomem::SelfContained< TContained >