SG::ArenaAllocatorBase Class Reference

Common base class for arena allocator classes. More...

#include <ArenaAllocatorBase.h>

Inheritance diagram for SG::ArenaAllocatorBase:

Collaboration diagram for SG::ArenaAllocatorBase:

Classes
struct	initParams
	Helper to initialize a parameters structure. More...
struct	Params
	Allocator parameters. More...
struct	Stats
	Statistics for an allocator. More...

Public Types
typedef char *	pointer
	Type for pointers to elements.
typedef const char *	const_pointer
	And a const version of the pointer.
typedef void	func_t(pointer)
	Type of functions for constructor, etc.

Public Member Functions
virtual	~ArenaAllocatorBase ()
	Destructor.
virtual void	reset ()=0
	Free all allocated elements.
virtual void	erase ()=0
	Free all allocated elements and release memory back to the system.
virtual void	reserve (size_t size)=0
	Set the total number of elements cached by the allocator.
virtual Stats	stats () const =0
	Return the statistics block for this allocator.
virtual const std::string &	name () const =0
	Return the name of this allocator.
virtual void	report (std::ostream &os) const
	Generate a report on the memory usage of this allocator.

Static Public Member Functions
template<class T>
static func_t *	makeConstructor (const std::false_type &)
	Make a constructor function pointer for a non-trivial constructor.
template<class T>
static func_t *	makeConstructor (const std::true_type &)
	Make a constructor function pointer for a trivial constructor.
template<class T>
static func_t *	makeDestructor (const std::false_type &)
	Make a constructor function pointer for a non-trivial destructor.
template<class T>
static func_t *	makeDestructor (const std::true_type &)
	Make a constructor function pointer for a trivial destructor.
template<class T>
static func_t *	makeClear (const std::false_type &)
	Make a function pointer for a clear function.
template<class T>
static func_t *	makeClear (const std::true_type &)
	Make a dummy clear function pointer.

Static Private Member Functions
template<typename T>
static void	construct_fcn (pointer p)
	Call T's default constructor on the object at p.
template<typename T>
static void	destroy_fcn (pointer p)
	Call T's destructor on the object at p.
template<typename T>
static void	clear_fcn (pointer p)
	Call T::clear on the object at p.

Detailed Description

Common base class for arena allocator classes.

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

This base class provides the interfaces and common behavior for arena allocator classes. An allocator class is responsible for the actual allocation and deletion of objects. It is expected that unallocated objects may be maintained in a pool for efficiency. In addition, it should be possible to free at once all the objects that this allocator has allocated. See below for the details of the interface that classes deriving from this should implement.

A matter of terminology. The objects that we allocate and free are called ‘elements’. As mentioned, it is expected that the memory will be allocated from the system for large groups of elements at any one time; these groups are called ‘blocks’.

The allocator classes do not themselves depend on the type of the object being allocated. Instead, the necessary information is included in a parameters object of class Params that is passed to the allocator on construction. These parameters include:

• name: The name of this allocator. This is used both in printed reports and to identify this allocator in the registry.
• eltSize: The size in bytes of the individual elements we're allocating.
• minSize: The minimum size that this Allocator allows for an element.
• nblock: A hint for the number of elements to allocate in a single block. This is only a hint; the allocator may allocate a different number if that would be more efficient.
• linkOffset: Some allocators may require keeping a pointer along with the element. This gives the offset (in bytes) from the start of the element where that pointer lives. In some cases, it may be safe to save space by allowing this pointer to overlap part of the element. Calling code is responsible for setting this up correctly.
• constructor, destructor: It may be more efficient to call the element's constructor and destructor not each time the element is allocated and freed, but instead just when the element's block is allocated from or freed to the system. We thus cache a free pool of already-initialized objects. These parameters are to support this case. These are pointers to functions with the signature void (*)(char*). The constructor function is called when an element is first allocated from the system, and the destructor function is called when the element is finally released to the system. Either may be 0 to skip the call.
• clear: In addition to the constructor and destructor, it may be necessary to reset the element state after the application releases it. If clear is not-null, this function will be called when an application frees an element.
• canReclear: If true (the default), then it is safe to call clear more than once on a given element after it has been released.
• mustClear: If true, then clear must be called before calling destructor. Otherwise (the default), destructor may be called directly without calling clear.

The allocator class should maintain statistics for the memory it has allocated. These are grouped in the Stats structure. It should report the amount of space in use, the amount of free space (allocated from the system but not allocated by the application), and the total space allocated from the system, broken down into blocks, elements, and bytes. The derived allocator class may of course extend the provided statistics.

The interface provided by derived allocator classes should consist of at least the following:

• A constructor from a Params structure.
• Implementations of the virtual methods reset, erase, reserve, name, stats. See documentation below.
• An implementation of the method

  pointer allocate();

  This should be non-virtual, and may be inlined. It should return a pointer to an new element. If constructor was provided, then it should have been called on the element.
• Optionally, an implementation of the non-virtual method

  void free (pointer);

  to free a single element. clear will be called on the element if it was provided.
• Optionally, an implementation of the non-virtual method

  void resetTo (pointer);

  pointer should be a pointer to an element that was allocated from this allocator. That element and all elements that were allocated after it will be freed.
• Optionally, iterator and const_iterator types and the corresponding const and non-const begin and end methods. These iterators should range over all allocated elements. The value_type should be pointer, and they should be at least forward iterators.

Definition at line 133 of file ArenaAllocatorBase.h.

Member Typedef Documentation

const_pointer

typedef const char* SG::ArenaAllocatorBase::const_pointer

And a const version of the pointer.

Definition at line 140 of file ArenaAllocatorBase.h.

func_t

typedef void SG::ArenaAllocatorBase::func_t(pointer)

Type of functions for constructor, etc.

Definition at line 143 of file ArenaAllocatorBase.h.

pointer

typedef char* SG::ArenaAllocatorBase::pointer

Type for pointers to elements.

Definition at line 137 of file ArenaAllocatorBase.h.

Constructor & Destructor Documentation

~ArenaAllocatorBase()

virtual SG::ArenaAllocatorBase::~ArenaAllocatorBase ( )

inlinevirtual

Destructor.

Definition at line 228 of file ArenaAllocatorBase.h.

{}

Member Function Documentation

clear_fcn()

template<typename T>

void SG::ArenaAllocatorBase::clear_fcn ( pointer p )

staticprivate

Call T::clear on the object at p.

Parameters

p	The object on which to run the clear.

construct_fcn()

template<typename T>

void SG::ArenaAllocatorBase::construct_fcn ( pointer p )

staticprivate

Call T's default constructor on the object at p.

Parameters

p	The object on which to run the constructor.

destroy_fcn()

template<typename T>

void SG::ArenaAllocatorBase::destroy_fcn ( pointer p )

staticprivate

Call T's destructor on the object at p.

Parameters

p	The object on which to run the destructor.

erase()

virtual void SG::ArenaAllocatorBase::erase ( )

pure virtual

Free all allocated elements and release memory back to the system.

All elements allocated 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).

Implemented in SG::ArenaBlockAllocatorBase, SG::ArenaHeapAllocator, and SG::ArenaPoolAllocator.

makeClear() [1/2]

template<class T>

func_t * SG::ArenaAllocatorBase::makeClear ( const std::false_type & )

static

Make a function pointer for a clear function.

makeClear() [2/2]

template<class T>

func_t * SG::ArenaAllocatorBase::makeClear ( const std::true_type & )

static

Make a dummy clear function pointer.

makeConstructor() [1/2]

template<class T>

func_t * SG::ArenaAllocatorBase::makeConstructor ( const std::false_type & )

static

Make a constructor function pointer for a non-trivial constructor.

makeConstructor() [2/2]

template<class T>

func_t * SG::ArenaAllocatorBase::makeConstructor ( const std::true_type & )

static

Make a constructor function pointer for a trivial constructor.

makeDestructor() [1/2]

template<class T>

func_t * SG::ArenaAllocatorBase::makeDestructor ( const std::false_type & )

static

Make a constructor function pointer for a non-trivial destructor.

makeDestructor() [2/2]

template<class T>

func_t * SG::ArenaAllocatorBase::makeDestructor ( const std::true_type & )

static

Make a constructor function pointer for a trivial destructor.

name()

virtual const std::string & SG::ArenaAllocatorBase::name ( ) const

pure virtual

Return the name of this allocator.

Implemented in SG::ArenaBlockAllocatorBase.

report()

void SG::ArenaAllocatorBase::report ( std::ostream & os ) const

virtual

Generate a report on the memory usage of this allocator.

Parameters

os	Stream to which the report should be written.

Definition at line 130 of file ArenaAllocatorBase.cxx.

{
  os << " " << stats() << "  " << name() << std::endl;
}

reserve()

virtual void SG::ArenaAllocatorBase::reserve ( size_t size )

pure virtual

Set the total number of elements cached by the allocator.

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.

Implemented in SG::ArenaBlockAllocatorBase.

reset()

virtual void SG::ArenaAllocatorBase::reset ( )

pure virtual

Free all allocated elements.

All elements allocated 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.

Implemented in SG::ArenaHeapAllocator, and SG::ArenaPoolAllocator.

stats()

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

pure virtual

Return the statistics block for this allocator.

Implemented in SG::ArenaBlockAllocatorBase.

---

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

• ArenaAllocatorBase.h
• ArenaAllocatorBase.cxx