User interface for allocating memory that caches constructed objects. More...

#include <ArenaCachingHandle.h>

Inheritance diagram for SG::ArenaCachingHandle< T, ALLOC >:

Collaboration diagram for SG::ArenaCachingHandle< T, ALLOC >:

Public Types
typedef ArenaHandleBaseT< T, ALLOC >	Base
	Shorthand for our base class. More...

typedef T *	pointer
	Pointer to an element. More...

typedef Base::iterator	iterator
	Iterators over elements. More...

typedef Base::const_iterator	const_iterator

typedef ALLOC::template initParams< T, false >	defaultParams_t
	The class that initializes the default parameter set. More...

typedef ALLOC	alloc_t
	The `Allocator` we use. More...

Public Member Functions
	ArenaCachingHandle (ArenaHeader *header, size_t index)
	Constructor, passing in an index. More...

	ArenaCachingHandle (const typename ALLOC::Params *params=nullptr)
	Constructor, passing in an optional parameter set. More...

	ArenaCachingHandle (ArenaHeader header, const typename ALLOC::Params params=nullptr)
	Constructor, passing in a Header and an optional parameter set. More...

	ArenaCachingHandle (ArenaHeader header, const EventContext &ctx, const typename ALLOC::Params params=nullptr)
	Constructor, passing in a Header, context, and an optional parameter set. More...

	ArenaCachingHandle (Arena arena, const typename ALLOC::Params params=nullptr)
	Constructor, passing in an Arena and an optional parameter set. More...

pointer	allocate ()
	Allocate a new element. More...

iterator	begin ()
	Starting iterator. More...

const_iterator	begin () const
	Starting const iterator. More...

iterator	end ()
	Ending iterator. More...

const_iterator	end () const
	Ending const iterator. More...

void	free (pointer p)
	Free an element. More...

void	resetTo (pointer p)
	Reset pool back to a previous state. More...

const ALLOC::Params &	params () const
	Return our Allocator's parameters. More...

void	reset ()
	Free all allocated elements (of this type in the current Arena). More...

void	erase ()
	Free all allocated elements and release memory back to the system (of this type in the current Arena). More...

void	reserve (size_t size)
	Set the total number of elements cached by the allocator (in the current Arena). More...

ArenaAllocatorBase::Stats	stats () const
	Return the statistics block for this allocator, for the current Arena. More...

Static Public Member Functions
static std::unique_ptr< ArenaAllocatorBase >	makeAllocator (const typename ALLOC::Params &params)
	Internal helper: create a new Allocator instance. More...

Protected Member Functions
ALLOC *	allocator ()
	Return our current Allocator. More...

const ALLOC *	allocator () const
	Return our current Allocator. More...

ArenaAllocatorBase *	baseAllocator ()
	Return the current Allocator which we are referencing. More...

const ArenaAllocatorBase *	baseAllocator () const
	Return the current Allocator which we are referencing. More...

Static Protected Member Functions
template<class HANDLE , class DEFPARAMS >
static size_t	makeIndex (const typename ALLOC::Params *params)
	Find the index for creating an allocator. More...

Private Attributes
LockedAllocator	m_allocator
	The associated allocator object. More...

Detailed Description

template<class T, class ALLOC>
class SG::ArenaCachingHandle< T, ALLOC >

User interface for allocating memory that caches constructed objects.

See Arena.h for an overview of the arena-based memory allocators.

A Handle is the interface the application uses to allocate memory. A Handle is templated on the type being allocated as well as on the underlying Allocator. When a Handle is constructed, it is associated with the Allocator associated with the Arena that is current at that time (a new Allocator is automatically created if required). Therefore, a Handle should not be passed between threads, and Handle objects should not exist across any point where the current store/Arena may be changed.

This particular Handle implementation calls the element constructor only when the memory is first allocated by the system, and calls the destructor only when the memory is returned to the system. The allocate method thus returns an already-initialized pointer to the element. The element's default constructor must work for this.

Note that it's possible to set up an additional clear method that's called when the element is freed; see ArenaAllocatorBase.

Here's an example of how you might create the Handle and allocate memory:

SG::ArenaCachingHandle<MyObj, SG::ArenaPoolAllocator> handle;

MyObj* obj = handle.allocate();

This associates the Handle with the default ArenaHeader. You can then erase all objects allocated though this Handle in the current Allocator with

handle.reset();

Note that most of the public interface for this class is inherited from the base classes.

Be aware that a handle holds a lock on the underlying allocator. Therefore, if you try to create two handle instances referencing the same allocator (i.e, same type and same thread), you'll get a deadlock.

Definition at line 76 of file ArenaCachingHandle.h.

Member Typedef Documentation

◆ alloc_t

template<typename ALLOC >

typedef ALLOC SG::ArenaHandleBaseAllocT< ALLOC >::alloc_t

inherited

The Allocator we use.

Definition at line 57 of file ArenaHandleBaseAllocT.h.

◆ Base

template<class T , class ALLOC >

typedef ArenaHandleBaseT<T, ALLOC> SG::ArenaCachingHandle< T, ALLOC >::Base

Shorthand for our base class.

Definition at line 81 of file ArenaCachingHandle.h.

◆ const_iterator

template<class T , class ALLOC >

typedef Base::const_iterator SG::ArenaCachingHandle< T, ALLOC >::const_iterator

Definition at line 89 of file ArenaCachingHandle.h.

◆ defaultParams_t

template<class T , class ALLOC >

typedef ALLOC::template initParams<T, false> SG::ArenaCachingHandle< T, ALLOC >::defaultParams_t

The class that initializes the default parameter set.

Definition at line 102 of file ArenaCachingHandle.h.

◆ iterator

template<class T , class ALLOC >

typedef Base::iterator SG::ArenaCachingHandle< T, ALLOC >::iterator

Iterators over elements.

(May only be instantiated if the underlying Allocator supports them.)

Definition at line 88 of file ArenaCachingHandle.h.

◆ pointer

template<class T , class ALLOC >

typedef T* SG::ArenaCachingHandle< T, ALLOC >::pointer

Pointer to an element.

Definition at line 84 of file ArenaCachingHandle.h.

Constructor & Destructor Documentation

◆ ArenaCachingHandle() [1/5]

template<class T , class ALLOC >

SG::ArenaCachingHandle< T, ALLOC >::ArenaCachingHandle	(	ArenaHeader *	header,
		size_t	index
	)

Constructor, passing in an index.

(For internal/testing use.)

Parameters

header	The group of Arenas which this Handle may reference. May be null to select the global default.
index	The index of this Handle's Allocator type.

◆ ArenaCachingHandle() [2/5]

template<class T , class ALLOC >

SG::ArenaCachingHandle< T, ALLOC >::ArenaCachingHandle ( const typename ALLOC::Params * params = nullptr )

Constructor, passing in an optional parameter set.

Parameters

params Parameters to pass to the Allocator, or nullptr to use the defaults.

◆ ArenaCachingHandle() [3/5]

template<class T , class ALLOC >

SG::ArenaCachingHandle< T, ALLOC >::ArenaCachingHandle	(	ArenaHeader *	header,
		const typename ALLOC::Params *	params = `nullptr`
	)

Constructor, passing in a Header and an optional parameter set.

Parameters

header	The group of Arenas which this Handle may reference. May be null to select the global default.
params	Parameters to pass to the Allocator, or nullptr to use the defaults.

◆ ArenaCachingHandle() [4/5]

template<class T , class ALLOC >

SG::ArenaCachingHandle< T, ALLOC >::ArenaCachingHandle	(	ArenaHeader *	header,
		const EventContext &	ctx,
		const typename ALLOC::Params *	params = `nullptr`
	)

Constructor, passing in a Header, context, and an optional parameter set.

Parameters

header	The group of Arenas which this Handle may reference. May be null to select the global default.
ctx	Event context identifying the event slot.
params	Parameters to pass to the Allocator, or nullptr to use the defaults.

◆ ArenaCachingHandle() [5/5]

template<class T , class ALLOC >

SG::ArenaCachingHandle< T, ALLOC >::ArenaCachingHandle	(	Arena *	arena,
		const typename ALLOC::Params *	params = `nullptr`
	)

Constructor, passing in an Arena and an optional parameter set.

Parameters

arena	The Arena in which to create the Allocator.
params	Parameters to pass to the Allocator, or nullptr to use the defaults.

Member Function Documentation

◆ allocate()

template<class T , class ALLOC >

pointer SG::ArenaCachingHandle< T, ALLOC >::allocate ( )

Allocate a new element.

This returns an already-initialized element.

◆ allocator() [1/2]

template<typename ALLOC >

ALLOC* SG::ArenaHandleBaseAllocT< ALLOC >::allocator ( )

protectedinherited

Return our current Allocator.

◆ allocator() [2/2]

template<typename ALLOC >

const ALLOC* SG::ArenaHandleBaseAllocT< ALLOC >::allocator ( ) const

protectedinherited

Return our current Allocator.

◆ baseAllocator() [1/2]

ArenaAllocatorBase* SG::ArenaHandleBase::baseAllocator ( )

protectedinherited

Return the current Allocator which we are referencing.

This may cause a new Allocator to be created.

◆ baseAllocator() [2/2]

const ArenaAllocatorBase* SG::ArenaHandleBase::baseAllocator ( ) const

protectedinherited

Return the current Allocator which we are referencing.

This may cause a new Allocator to be created.

◆ begin() [1/2]

template<class T , class ALLOC >

iterator SG::ArenaHandleBaseT< T, ALLOC >::begin ( )

inherited

Starting iterator.

This will iterate over all allocated elements (in unspecified order). It is at least a forward_iterator. This may only be instantiated if the underlying Allocator supports iterators.

◆ begin() [2/2]

template<class T , class ALLOC >

const_iterator SG::ArenaHandleBaseT< T, ALLOC >::begin ( ) const

inherited

Starting const iterator.

This will iterate over all allocated elements (in unspecified order). It is at least a forward_iterator. This may only be instantiated if the underlying Allocator supports iterators.

◆ end() [1/2]

template<class T , class ALLOC >

iterator SG::ArenaHandleBaseT< T, ALLOC >::end ( )

inherited

Ending iterator.

This may only be instantiated if the underlying Allocator supports iterators.

◆ end() [2/2]

template<class T , class ALLOC >

const_iterator SG::ArenaHandleBaseT< T, ALLOC >::end ( ) const

inherited

Ending const iterator.

This may only be instantiated if the underlying Allocator supports iterators.

◆ erase()

void SG::ArenaHandleBase::erase ( )

inherited

Free all allocated elements and release memory back to the system (of this type in the current Arena).

All elements allocated in the current Arena by our associated Allocator are freed, and all allocated blocks of memory are released back to the system. destructor should be called on them if it was provided (preceded by clear if provided and mustClear was set).

Definition at line 87 of file ArenaHandleBase.cxx.

 {
   return baseAllocator()->erase();
 }

◆ free()

template<class T , class ALLOC >

void SG::ArenaHandleBaseT< T, ALLOC >::free ( pointer p )

inherited

Free an element.

Parameters

p	The element to be freed.

clear() will be called on the element at this point, if it has been defined.

This may only be instantiated if it's supported by the underlying Allocator.

◆ makeAllocator()

template<class T , class ALLOC >

static std::unique_ptr<ArenaAllocatorBase> SG::ArenaCachingHandle< T, ALLOC >::makeAllocator ( const typename ALLOC::Params & params )

static

Internal helper: create a new Allocator instance.

Parameters

params The parameters for the Allocator.

◆ makeIndex()

template<typename ALLOC >

template<class HANDLE , class DEFPARAMS >

static size_t SG::ArenaHandleBaseAllocT< ALLOC >::makeIndex ( const typename ALLOC::Params * params )

staticprotectedinherited

Find the index for creating an allocator.

Parameters

params Pointer to the supplied parameters. If null, use the result of DEFPARAMS().

We look up in the registry the Allocator name we get from params (if this is blank, a name is derived from ALLOC). If not found, then we register Allocator and return the new index.

◆ params()

template<typename ALLOC >

const ALLOC::Params& SG::ArenaHandleBaseAllocT< ALLOC >::params ( ) const

inherited

Return our Allocator's parameters.

◆ reserve()

void SG::ArenaHandleBase::reserve ( size_t size )

inherited

Set the total number of elements cached by the allocator (in the current Arena).

Parameters

size	The desired pool size.

This allows changing the number of elements that are currently free but cached. Any allocated elements are not affected by this call.

If size is greater than the total number of elements currently cached, then more will be allocated. This will preferably done with a single block, but that is not guaranteed; in addition, the allocator may allocate more elements than is requested.

If size is smaller than the total number of elements currently cached, as many blocks as possible will be released back to the system. It may not be possible to release the number of elements requested; this should be implemented on a best-effort basis.

Definition at line 111 of file ArenaHandleBase.cxx.

 {
   return baseAllocator()->reserve (size);
 }

◆ reset()

void SG::ArenaHandleBase::reset ( )

inherited

Free all allocated elements (of this type in the current Arena).

All elements allocated in the current Arena by our associated Allocator are returned to the free state. clear should be called on them if it was provided. The elements may continue to be cached internally, without returning to the system.

Definition at line 71 of file ArenaHandleBase.cxx.

 {
   return baseAllocator()->reset();
 }

◆ resetTo()

template<class T , class ALLOC >

void SG::ArenaHandleBaseT< T, ALLOC >::resetTo ( pointer p )

inherited

Reset pool back to a previous state.

Parameters

p	The pointer back to which to reset.

This will free (a la reset) the element p and all elements that have been allocated after it from this allocator.

This may only be instantiated if it's supported by the underlying Allocator.

◆ stats()

ArenaAllocatorBase::Stats SG::ArenaHandleBase::stats ( ) const

inherited

Return the statistics block for this allocator, for the current Arena.

Definition at line 121 of file ArenaHandleBase.cxx.

 {
   return baseAllocator()->stats();
 }

Member Data Documentation

◆ m_allocator

LockedAllocator SG::ArenaHandleBase::m_allocator

privateinherited

The associated allocator object.

Definition at line 160 of file ArenaHandleBase.h.

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

ArenaCachingHandle.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Attributes

Detailed Description

template<class T, class ALLOC> class SG::ArenaCachingHandle< T, ALLOC >

Member Typedef Documentation

◆ alloc_t

◆ Base

◆ const_iterator

◆ defaultParams_t

◆ iterator

◆ pointer

Constructor & Destructor Documentation

◆ ArenaCachingHandle() [1/5]

◆ ArenaCachingHandle() [2/5]

◆ ArenaCachingHandle() [3/5]

◆ ArenaCachingHandle() [4/5]

◆ ArenaCachingHandle() [5/5]

Member Function Documentation

◆ allocate()

◆ allocator() [1/2]

◆ allocator() [2/2]

◆ baseAllocator() [1/2]

◆ baseAllocator() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ erase()

◆ free()

◆ makeAllocator()

◆ makeIndex()

◆ params()

◆ reserve()

◆ reset()

◆ resetTo()

◆ stats()

Member Data Documentation

◆ m_allocator

template<class T, class ALLOC>
class SG::ArenaCachingHandle< T, ALLOC >