#include "lib/allocation-cluster.hpp"

Description

A pile of objects sharing common allocation and lifecycle.

AllocationCluster owns a heterogeneous collection of objects of various types. Typically, allocation happens during a short time span when building a new segment, and objects are used together until the segment is discarded. The primary leverage is to bulk-allocate memory, and to avoid invoking destructors (and thus to access a lot of cache-cold memory pages on clean-up). A Stdlib compliant #Allocator is provided for use with STL containers. The actual allocation uses heap memory in extents of hard-wired size, maintained by the accompanying StorageManager.

Warning: use createDisposable whenever possible, but be sure to understand the ramifications of not invoking an object's destructor.

Definition at line 87 of file allocation-cluster.hpp.

Classes
struct	AllocationWithDestructor

struct	Allocator

class	Destructor

struct	Storage
	maintaining the Allocation More...

class	StorageManager
	An overlay view for the AllocationCluster to add functionality for adding / clearing extents and registering optional deleter functions. More...

Static Public Attributes
static constexpr size_t	EXTENT_SIZ = 256
	hard wired size of storage extents

Static Public Member Functions
static constexpr size_t	max_size ()
	Maximum individual allocation size that can be handled.

Public Member Functions
	AllocationCluster ()
	Prepare a new clustered allocation to be expanded by extents of size EXTENT_SIZ, yet discarded all at once when the dtor is called.

	~AllocationCluster () noexcept
	The shutdown of an AllocationCluster walks all extents and invokes all registered deleter functions and then discards the complete storage.

size_t	numExtents () const

size_t	numBytes () const

template<class TY , typename... ARGS>
TY &	create (ARGS &&...)

template<class TY , typename... ARGS>
TY &	createDisposable (ARGS &&...)

template<typename X >
Allocator< X >	getAllocator ()

bool	canAdjust (void *loc, size_t oldSiz, size_t newSiz) const

void	doAdjust (void *loc, size_t oldSiz, size_t newSiz)
	Adjust the size of the latest raw memory allocation dynamically.

template<class TY , typename... ARGS>
TY &	createDisposable (ARGS &&...args)
	Factory function: place a new instance into this AllocationCluster, but without invoking its destructor on clean-up (for performance reasons).

template<class TY , typename... ARGS>
TY &	create (ARGS &&...args)
	Factory function: place a new instance into this AllocationCluster; the object will be properly destroyed when the cluster goes out of scope.

Friends
class	test::AllocationCluster_test

Private Member Functions
void *	allotMemory (size_t bytes, size_t alignment)
	portion out the requested amount of memory, possibly claiming a new pool block.

template<typename X >
X *	allot (size_t cnt=1)

void	expandStorage (size_t)
	Expand the alloted storage pool by a block, suitable to accommodate at least the indicated request.

void	registerDestructor (Destructor &)

void	__enforce_limits (size_t, size_t)
	Allocation cluster uses a comparatively small tile size for its extents, which turns out to be a frequently encountered limitation in practice.

Private Member Functions inherited from MoveOnly
	~MoveOnly ()=default

	MoveOnly ()=default

	MoveOnly (MoveOnly &&)=default

	MoveOnly (MoveOnly const &)=delete

MoveOnly &	operator= (MoveOnly &&)=delete

MoveOnly &	operator= (MoveOnly const &)=delete

Private Attributes
Storage	storage_

Constructor & Destructor Documentation

◆ AllocationCluster()

AllocationCluster ( )

Prepare a new clustered allocation to be expanded by extents of size EXTENT_SIZ, yet discarded all at once when the dtor is called.

The constructor does not allocate anything immediately.

Definition at line 207 of file allocation-cluster.cpp.

◆ ~AllocationCluster()

~AllocationCluster ( )

noexcept

The shutdown of an AllocationCluster walks all extents and invokes all registered deleter functions and then discards the complete storage.

Note: it is possible to allocate objects as disposable — meaning that no destructors will be enrolled and called for such objects.

Definition at line 220 of file allocation-cluster.cpp.

References AllocationCluster::StorageManager::access(), and AllocationCluster::StorageManager::discardAll().

Here is the call graph for this function:

Member Function Documentation

◆ max_size()

size_t constexpr max_size ( )

staticconstexpr

Maximum individual allocation size that can be handled.

Remarks: AllocationCluser expands its storage buffer in steps of fixed sized tiles or extents. Doing so can be beneficial when clusters are frequently created and thrown away (which is the intended usage pattern). However, using such extents is inherently wasteful, and thus the size must be rather tightly limited.

Definition at line 234 of file allocation-cluster.hpp.

References AllocationCluster::EXTENT_SIZ.

Referenced by AllocationCluster::__enforce_limits(), AllocationCluster::StorageManager::calcAllocInCurrentBlock(), SeveralBuilder_test::check_CustomAllocator(), AllocationCluster::expandStorage(), AllocationCluster::numBytes(), and AllocationCluster::StorageManager::prependNextBlock().

Here is the caller graph for this function:

◆ numExtents()

size_t numExtents ( ) const

Definition at line 285 of file allocation-cluster.cpp.

References AllocationCluster::StorageManager::access(), and AllocationCluster::StorageManager::determineExtentCnt().

Referenced by SeveralBuilder_test::check_CustomAllocator(), AllocationCluster_test::checkLifecycle(), AllocationCluster_test::dynamicAdjustment(), AllocationCluster::numBytes(), AllocationCluster_test::simpleUsage(), AllocationCluster_test::use_as_Allocator(), and AllocationCluster_test::verifyInternals().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ numBytes()

size_t numBytes ( ) const

Warning: whenever there are more than one extent, the returned byte count is guessed only (upper bound), since actually allocated size is not tracked to save some overhead.

Definition at line 296 of file allocation-cluster.cpp.

References AllocationCluster::StorageManager::access(), AllocationCluster::StorageManager::calcAllocInCurrentBlock(), AllocationCluster::max_size(), and AllocationCluster::numExtents().

Referenced by SeveralBuilder_test::check_CustomAllocator(), AllocationCluster_test::dynamicAdjustment(), LinkedElements_test::verify_customAllocator(), and AllocationCluster_test::verifyInternals().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create() [1/2]

template<class TY , typename... ARGS>

TY & create ( ARGS && ... )

Referenced by SeveralBuilder_test::check_CustomAllocator(), LinkedElements_test::UseAllocationCluster::create(), AllocationCluster_test::dynamicAdjustment(), lib::test::anonymous_namespace{allocation-cluster-test.cpp}::place_object(), AllocationCluster_test::simpleUsage(), and AllocationCluster_test::verifyInternals().

Here is the caller graph for this function:

◆ createDisposable() [1/2]

template<class TY , typename... ARGS>

TY & createDisposable ( ARGS && ... )

Referenced by AllocationCluster_test::checkLifecycle(), and AllocationCluster_test::verifyInternals().

Here is the caller graph for this function:

◆ getAllocator()

template<typename X >

Allocator< X > getAllocator ( )

inline

Definition at line 160 of file allocation-cluster.hpp.

Referenced by AllocationCluster_test::use_as_Allocator(), and LinkedElements_test::verify_customAllocator().

Here is the caller graph for this function:

◆ canAdjust()

bool canAdjust	(	void *	loc,
		size_t	oldSiz,
		size_t	newSiz
	)		const

inline

Definition at line 291 of file allocation-cluster.hpp.

References AllocationCluster::Storage::hasReserve(), AllocationCluster::Storage::matches_last_allocation(), and AllocationCluster::storage_.

Referenced by AllocationCluster::doAdjust(), and AllocationCluster_test::dynamicAdjustment().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ doAdjust()

void doAdjust	(	void *	loc,
		size_t	oldSiz,
		size_t	newSiz
	)

inline

Adjust the size of the latest raw memory allocation dynamically.

Parameters

loc	an allocation provided by this AllocationCluster
oldSiz	the size requested for the allocation loc
newSiz	desired new size for this allocation

Remarks: since AllocationCluster must be used in a single threaded environment, the invoking code can sometimes arrange to adapt the latest allocation to a dynamically changing situation, like e.g. populating a container with a previously unknown number of elements. Obviously, the overall allocation must stay within the confines of the current extent; it is thus mandatory to check the ability beforehand.

Definition at line 283 of file allocation-cluster.hpp.

References AllocationCluster::Storage::adjustPos(), AllocationCluster::canAdjust(), and AllocationCluster::storage_.

Referenced by AllocationCluster_test::dynamicAdjustment().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ allotMemory()

void * allotMemory	(	size_t	bytes,
		size_t	alignment
	)

inlineprivate

portion out the requested amount of memory, possibly claiming a new pool block.

Definition at line 172 of file allocation-cluster.hpp.

References AllocationCluster::__enforce_limits(), AllocationCluster::Storage::allot(), AllocationCluster::allotMemory(), AllocationCluster::expandStorage(), and AllocationCluster::storage_.

Referenced by AllocationCluster::allot(), and AllocationCluster::allotMemory().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ allot()

template<typename X >

X * allot ( size_t cnt = 1 )

inlineprivate

Definition at line 183 of file allocation-cluster.hpp.

References AllocationCluster::allotMemory().

Here is the call graph for this function:

◆ expandStorage()

void expandStorage ( size_t allocRequest )

private

Expand the alloted storage pool by a block, suitable to accommodate at least the indicated request.

Remarks: Storage blocks are organised as linked list, allowing to de-allocate all blocks together.

Definition at line 241 of file allocation-cluster.cpp.

References AllocationCluster::StorageManager::access(), AllocationCluster::StorageManager::addBlock(), and AllocationCluster::max_size().

Referenced by AllocationCluster::allotMemory().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ registerDestructor()

void registerDestructor ( Destructor & dtor )

private

Definition at line 249 of file allocation-cluster.cpp.

References AllocationCluster::StorageManager::access(), and AllocationCluster::StorageManager::attach().

Referenced by AllocationCluster::create().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __enforce_limits()

void __enforce_limits	(	size_t	allocSiz,
		size_t	align
	)

private

Allocation cluster uses a comparatively small tile size for its extents, which turns out to be a frequently encountered limitation in practice.

This was deemed acceptable, due to its orientation towards performance.

Exceptions

err::Fatal when a desired allocation can not be accommodated

Definition at line 263 of file allocation-cluster.cpp.

References LERR_, and AllocationCluster::max_size().

Referenced by AllocationCluster::allotMemory().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ createDisposable() [2/2]

template<class TY , typename... ARGS>

TY & createDisposable ( ARGS &&... args )

inline

Factory function: place a new instance into this AllocationCluster, but without invoking its destructor on clean-up (for performance reasons).

Definition at line 246 of file allocation-cluster.hpp.

◆ create() [2/2]

template<class TY , typename... ARGS>

TY & create ( ARGS &&... args )

inline

Factory function: place a new instance into this AllocationCluster; the object will be properly destroyed when the cluster goes out of scope.

Note: whenever possible, the createDisposable variant should be preferred

Definition at line 258 of file allocation-cluster.hpp.

References AllocationCluster::registerDestructor().

Here is the call graph for this function:

Member Data Documentation

◆ storage_

Storage storage_

private

Definition at line 116 of file allocation-cluster.hpp.

Referenced by AllocationCluster::allotMemory(), AllocationCluster::canAdjust(), AllocationCluster::doAdjust(), and AllocationCluster_test::verifyInternals().

◆ EXTENT_SIZ

constexpr size_t EXTENT_SIZ = 256

staticconstexpr

hard wired size of storage extents

Definition at line 124 of file allocation-cluster.hpp.

Referenced by AllocationCluster::StorageManager::getCurrentBlockStart(), and AllocationCluster::max_size().

Friends And Related Symbol Documentation

◆ test::AllocationCluster_test

friend class test::AllocationCluster_test

friend

Definition at line 216 of file allocation-cluster.hpp.

Inheritance diagram for AllocationCluster:

Collaboration diagram for AllocationCluster:

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

Description

Classes

Static Public Attributes

Static Public Member Functions

Public Member Functions

Friends

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ AllocationCluster()

◆ ~AllocationCluster()

Member Function Documentation

◆ max_size()

◆ numExtents()

◆ numBytes()

◆ create() [1/2]

◆ createDisposable() [1/2]

◆ getAllocator()

◆ canAdjust()

◆ doAdjust()

◆ allotMemory()

◆ allot()

◆ expandStorage()

◆ registerDestructor()

◆ __enforce_limits()

◆ createDisposable() [2/2]

◆ create() [2/2]

Member Data Documentation

◆ storage_

◆ EXTENT_SIZ

Friends And Related Symbol Documentation

◆ test::AllocationCluster_test