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 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 to free a single element.
clear will be called on the element if it was provided.
- Optionally, an implementation of the non-virtual method
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.
| 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.
1.8.18