sparta::SpartaSharedPointerAllocator< PointerT > Class Template Reference

A memory allocator complementing SpartaSharedPointer that reuses old memory. More...

#include <SpartaSharedPointerAllocator.hpp>

Inheritance diagram for sparta::SpartaSharedPointerAllocator< PointerT >:

Collaboration diagram for sparta::SpartaSharedPointerAllocator< PointerT >:

Public Types
using	element_type = PointerT
	Handy typedef.
using	WaterMarkWarningCallback = std::function< void(const SpartaSharedPointerAllocator &)>
using	OverAllocationCallback = std::function< void(const SpartaSharedPointerAllocator &)>

Public Member Functions
	SpartaSharedPointerAllocator (const size_t max_num_blocks, const size_t water_mark)
	Construct this allocator with num_blocks of initial memory.
	SpartaSharedPointerAllocator (const SpartaSharedPointerAllocator &)=delete
	Disallow copies/assignments/moves.
	SpartaSharedPointerAllocator (SpartaSharedPointerAllocator &&)=delete
	Disallow copies/assignments/moves.
SpartaSharedPointerAllocator	operator= (const SpartaSharedPointerAllocator &)=delete
	Disallow copies/assignments/moves.
	~SpartaSharedPointerAllocator ()
	Clean up the allocator – will warn if there are objects not returned to the allocator.
size_t	getNumFree () const
	Return the number of freed objects this allocator holds.
size_t	getNumAllocated () const
	Return the number of allocated objects this allocator allocated over time.
bool	hasOutstandingObjects () const
	Query to see if the allocator has any outstanding memory not yet returned.
std::vector< const PointerT * >	getOutstandingAllocatedObjects () const
	Return a vector of objects that have not been deleted/not yet returned to the allocator.
void	registerCustomWaterMarkCallback (const WaterMarkWarningCallback &callback)
	Set a custom watermark warning callback.
void	registerCustomOverAllocationCallback (const OverAllocationCallback &callback)
	Set a custom over allocation callback.

Friends
class	SpartaSharedPointer< PointerT >
template<typename PtrT , typename... Args>
SpartaSharedPointer< PtrT >	allocate_sparta_shared_pointer (SpartaSharedPointerAllocator< PtrT > &, Args &&...args)

Detailed Description

template<class PointerT>
class sparta::SpartaSharedPointerAllocator< PointerT >

A memory allocator complementing SpartaSharedPointer that reuses old memory.

First off, this allocator DOES NOT follow the semantics of std::allocator_traits. This is done on purpose to prevent others from using this class with std types like std::shared_ptr, std::vector, etc. Also, this class is not thread safe. Do not expect it to work in a threaded application where multiple threads are allocating/deallocating with the same sparta::SpartaSharedPointerAllocator<PointerT> instance.

Also, the allocator must outlive any simulator componentry that uses objects allocated by this allocator. If not, random seg faults will plague the developer. Suggested use is to make this allocator global, with user-defined atomic operations if desired.

Another suggestion for Sparta developers using these allocators is to create an Allocator class type that derives from sparta::TreeNode and place that class somewhere in the simulation under root:

// Define a specific TreeNode that is just allocators
class OurAllocators : public sparta::TreeNode
{
public:
     // Constructors and what-not...
 
     // Allocators
     using MyAllocator = sparta::SpartaSharedPointerAllocator<MyClassIUseALot>;
     MyAllocator my_allocator(100, 200);  // whatever params you chose
};

And in the modeler's block, they would retrive the OurAllocators node and get the allocator:

class MyDevice : public sparta::Unit
{
public:
    MyDevice(sparta::TreeNode * my_container, sparta::ParameterSet *) :
        my_allocator_(customUtilToFindTheAllocatorTreeNode(my_container)->my_allocator)
    {}
 
private:
 
    OurAllocators::MyAllocator & my_allocator_;
};

The class is not intended to be used directly, but rather in compliment with the allocator method sparta::allocate_sparta_shared_pointer.

A typical use of this class is when a modeler is creating/destroying lots and lots and lots of little objects throughout simulation. Using the std::allocator or boost::pool_allocator does help, but not as much as this allocator, which is tuned/focused on the exact modeling use case.

As an example of a healthy performance uplift, the CoreExample saw a 20% boost in performance using this allocation coupled with the SpartaSharedPointer over using std::shared_ptr created via std::allocate_shared. See a performance example in the SpartaSharedPointer unit test.

To use this allocator, create a singleton of it in the application for the given type:

// .cpp file
 
// Instance of the allocator in source.  Set it up to
// initially allocate 100 blocks of memory.
 
namespace mysimulator {
    const size_t max_blocks_allowed = 100;
    const size_t water_mark_complaining_point = 80;
    sparta::SpartaSharedPointerAllocator<MyClassIUseALot>
                                     my_class_i_use_a_lot_allocator(max_blocks_allowed,
                                                                    water_mark_complaining_point);
}

namespace mysimulator {
    // .hpp file
    class MyClassIUseALot
    {
    public:
        // Constructor with two args
        MyClassIUseALot(uint32_t, const std::string&);
    };
 
    // The Allocator to use with the class
    extern sparta::SpartaSharedPointerAllocator<MyClassIUseALot>
                                      my_class_i_use_a_lot_allocator;
}

In runtime code, use allocate_sparta_shared_pointer method to allocate instances of the SpartaSharedPointer:

void foo()
{
    sparta::SpartaSharedPointer<MyClassIUseALot> ptr =
        sparta::allocate_sparta_shared_pointer<MyClassIUseALot>(my_class_i_use_a_lot_allocator,
                                                                30, "hello");
    ptr.reset(); // put back the allocated object in a pool
}

Use sparta::SpartaSharedPointer like a regular sparta::SpartaSharedPointer.

The allocator's constructor takes two arguments: a maximum number of blocks to allocate and a water mark. The maximum number of blocks is the hard upper limit of this allocator. Go beyond that and the allocator will throw an exception that it's "out of memory." If the allocator hits the watermark, it will warn that memory is dangerously close to being "used up." Watermark must be less than or equal to max_num_blocks.

The Allocator also keeps track of those objects in flight that have not returned to the allocator. Using the call to SpartaSharedPointerAllocator<PointerT>::getOutstandingAllocatedObjects, a modeler can determine which objects are still outstanding, where they might be, and help debug the situation.

Definition at line 154 of file SpartaSharedPointerAllocator.hpp.

Member Typedef Documentation

element_type

template<class PointerT >

using sparta::SpartaSharedPointerAllocator< PointerT >::element_type = PointerT

Handy typedef.

Definition at line 159 of file SpartaSharedPointerAllocator.hpp.

OverAllocationCallback

template<class PointerT >

using sparta::SpartaSharedPointerAllocator< PointerT >::OverAllocationCallback = std::function<void (const SpartaSharedPointerAllocator &)>

Used for defining a custom over allocation callback. Default is to throw an exception

Definition at line 167 of file SpartaSharedPointerAllocator.hpp.

WaterMarkWarningCallback

template<class PointerT >

using sparta::SpartaSharedPointerAllocator< PointerT >::WaterMarkWarningCallback = std::function<void (const SpartaSharedPointerAllocator &)>

Used for defining a custom watermark warning callback. Default is to print a warning

Definition at line 163 of file SpartaSharedPointerAllocator.hpp.

Constructor & Destructor Documentation

SpartaSharedPointerAllocator()

template<class PointerT >

sparta::SpartaSharedPointerAllocator< PointerT >::SpartaSharedPointerAllocator ( const size_t  max_num_blocks, const size_t  water_mark  )

inline

Construct this allocator with num_blocks of initial memory.

Parameters

max_num_blocks	The maximum number of blocks this allocator is allowed to use
water_mark	The point where this allocator will warn (once) if allocation passes this threshold

Allocate a SpartaSharedPointerAllocator with a large block of memory (up front) to use during simulation for the PointerT type. The water_mark is a warning spot to help developers tune their allocations for their uses.

Definition at line 180 of file SpartaSharedPointerAllocator.hpp.

~SpartaSharedPointerAllocator()

template<class PointerT >

sparta::SpartaSharedPointerAllocator< PointerT >::~SpartaSharedPointerAllocator ( )

inline

Clean up the allocator – will warn if there are objects not returned to the allocator.

Definition at line 202 of file SpartaSharedPointerAllocator.hpp.

Here is the call graph for this function:

Member Function Documentation

getNumAllocated()

template<class PointerT >

size_t sparta::SpartaSharedPointerAllocator< PointerT >::getNumAllocated ( ) const

inline

Return the number of allocated objects this allocator allocated over time.

Returns

Number of allocated objects

This count should always be <= getNumFree()

Definition at line 225 of file SpartaSharedPointerAllocator.hpp.

getNumFree()

template<class PointerT >

size_t sparta::SpartaSharedPointerAllocator< PointerT >::getNumFree ( ) const

inline

Return the number of freed objects this allocator holds.

Returns

Number of freed objects

Definition at line 215 of file SpartaSharedPointerAllocator.hpp.

getOutstandingAllocatedObjects()

template<class PointerT >

std::vector< const PointerT * > sparta::SpartaSharedPointerAllocator< PointerT >::getOutstandingAllocatedObjects ( ) const

inline

Return a vector of objects that have not been deleted/not yet returned to the allocator.

Returns

vector of PointerT objects that still have reference counts > 0

Definition at line 242 of file SpartaSharedPointerAllocator.hpp.

hasOutstandingObjects()

template<class PointerT >

bool sparta::SpartaSharedPointerAllocator< PointerT >::hasOutstandingObjects ( ) const

inline

Query to see if the allocator has any outstanding memory not yet returned.

Returns

True if there are outstanding blocks not yet returned to the allocator

Definition at line 233 of file SpartaSharedPointerAllocator.hpp.

registerCustomOverAllocationCallback()

template<class PointerT >

void sparta::SpartaSharedPointerAllocator< PointerT >::registerCustomOverAllocationCallback ( const OverAllocationCallback &  callback )

inline

Set a custom over allocation callback.

Parameters

callback

The callback to use when the allocator exceeds max blocks

The callback will be called only after the allocated exceeds the max blocks.

Definition at line 274 of file SpartaSharedPointerAllocator.hpp.

registerCustomWaterMarkCallback()

template<class PointerT >

void sparta::SpartaSharedPointerAllocator< PointerT >::registerCustomWaterMarkCallback ( const WaterMarkWarningCallback &  callback )

inline

Set a custom watermark warning callback.

Parameters

callback

The callback to use when the allocator hits the watermark

The callback will be called only once after the watermark was hit.

Definition at line 263 of file SpartaSharedPointerAllocator.hpp.

Friends And Related Symbol Documentation

SpartaSharedPointer< PointerT >

template<class PointerT >

friend class SpartaSharedPointer< PointerT >

friend

Definition at line 274 of file SpartaSharedPointerAllocator.hpp.

---

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

• /github/workspace/sparta/sparta/utils/SpartaSharedPointer.hpp
• /github/workspace/sparta/sparta/utils/SpartaSharedPointerAllocator.hpp