#include <CUFreeList.h>

Inheritance diagram for cugl::FreeList< T >:

Public Member Functions
	FreeList ()

	~FreeList ()

void	dispose ()

bool	init (size_t capacity)

bool	init (size_t capacity, bool expand)

size_t	getAvailable () const

size_t	getCapacity () const

size_t	getUsage () const

size_t	getPeakUsage () const

bool	isExpandable () const

const T *	getPreallocated () const

T *	malloc ()

void	free (T *obj)

virtual void	clear ()

Static Public Member Functions
static std::shared_ptr< FreeList< T > >	alloc (size_t capacity=0, bool expand=false)

Protected Attributes
size_t	_allocated

size_t	_released

size_t	_peaksize

T *	_prealloc

size_t	_capacity

std::queue< T * >	_freeobjs

bool	_expandable

std::queue< T * >	_expansion

Detailed Description

template<class T>
class cugl::FreeList< T >

Template for a free list class

A free list provides a way to recycle heap allocations. Instead of using the operations new and delete, you use the methods malloc() and free() in this class (remember that alloc() is used to allocate the free list itself). Hence an instance of this class effectively plays the role of your heap.

The method ,alloc() looks to see if there is any recycled memory, and uses that before allocating a new object. In addition, the user can allocated memory in the constructor of the free list, providing an initial list of preallocated memory at the start. If both the recycled and preallocated memory are exhausted, then this class will start to allocate new memory.

The exception is the case in which the free list is not expandable. In that case, the free list never has any more memory beyond what was allocated at the beginning. Any attempts to allocate memory beyond this bound will return a null pointer.

In order to work properly, the objects allocated must all have the method

void reset();

This method resets the object when it is recycled. It is like a destructor, except that the object is not actually deleted. The class does not have to formally subclass anything or implement an interface (C++ does not work that way). It just has to have this method. In addition, the class must have a default constructor with no arguments. You should have an init() method if you need to initialize the object after allocation.

This class owns all memory that it allocates. When the free list is deleted, all of the objects that it allocated will be deleted also.

A free list is not an all-purpose memory allocator. It is restricted to a single class. It should only be used for specialized applications.

Constructor & Destructor Documentation

◆ FreeList()

template<class T >

cugl::FreeList< T >::FreeList ( )

inline

Creates a new free list with no capacity.

You must initialize this free list before use.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a free list on the heap, use one of the static constructors instead.

◆ ~FreeList()

template<class T >

cugl::FreeList< T >::~FreeList ( )

inline

Deletes this free list, releasing all memory.

A free list is the owner of all memory it allocates. Any object allocated by this free list will be deleted and unsafe to access.

Member Function Documentation

◆ alloc()

template<class T >

static std::shared_ptr<FreeList<T> > cugl::FreeList< T >::alloc	(	size_t	capacity = `0`,
		bool	expand = `false`
	)

inlinestatic

Returns a newly allocated free list with the given capacity.

If capacity is non-zero, then it will allocate that many objects ahead of time. If expand is false, then it will never allocate any objects beyond those preallocated in this constructor.

Parameters

capacity	the number of objects to preallocate
expand	whether to allow non-preallocated objects

Returns: a newly allocated free list with the given capacity.

◆ clear()

template<class T >

void cugl::FreeList< T >::clear ( )

virtual

Clears this free list, restoring it to its original state.

This method (1) empties the free list, (2) resets all preallocated objects allowing them to be reused and (3) deletes any other objects that might have been allocated.

◆ dispose()

template<class T >

void cugl::FreeList< T >::dispose ( )

inline

Disposes this free list, releasing all memory.

A disposed free list can be safely reinitialized. However, a free list is the owner of all memory it allocates. Any object allocated by this free list will be deleted and unsafe to access.

◆ free()

template<class T >

void cugl::FreeList< T >::free ( T * obj )

Frees the object, adding it to the free list.

This method will call the reset() method in the object, erasing its contents. The class should be designed so that it cannot be used until it is reintialized.

It is possible to add an object that was not originally allocated by this free list. Doing so will make the object available for allocation. However, the free list will not assert ownership of the object, and will not delete it when it is cleaning up.

Parameters

obj	the object to free

◆ getAvailable()

template<class T >

size_t cugl::FreeList< T >::getAvailable ( ) const

inline

Returns the number of objects that can be allocated without more memory.

This value is the number of elements in the free list plus the number of elements remaining in the preallocation list.

Returns: the number of objects that can be allocated without more memory.

◆ getCapacity()

template<class T >

size_t cugl::FreeList< T >::getCapacity ( ) const

inline

Returns the preallocated capacity of this list.

If the free list is not expandable, this it the maximum number of objects that may be allocated at any given time.

Returns: the preallocated capacity of this list.

◆ getPeakUsage()

template<class T >

size_t cugl::FreeList< T >::getPeakUsage ( ) const

inline

Returns the maximum usage value at any given time in this object's lifecycle.

This value represents the high-water mark for memory. It is very useful if this is an expandable free list.

Returns: the maximum usage value at any given time in this object's lifecycle.

◆ getPreallocated()

template<class T >

const T* cugl::FreeList< T >::getPreallocated ( ) const

inline

Returns the pointer to the preallocated memory (if any) of this object.

It is unsafe to modify this pointer. Hence it is returned as a constant.

Returns: the pointer to the preallocated memory (if any) of this object.

◆ getUsage()

template<class T >

size_t cugl::FreeList< T >::getUsage ( ) const

inline

Returns the number of objects that have been allocated but not released yet.

Allocating an object will increase this value; free an object will decrease the value.

Returns: the number of objects that have been allocated but not released yet.

◆ init() [1/2]

template<class T >

bool cugl::FreeList< T >::init ( size_t capacity )

inline

Initializes a free list with the given capacity, but not expandable.

As it is not expandable, it will never allocate any objects beyond those preallocated in this constructor. Hence the capacity must be non-zero.

Parameters

capacity the number of objects to preallocate

Returns: true if initialization was successful.

◆ init() [2/2]

template<class T >

bool cugl::FreeList< T >::init	(	size_t	capacity,
		bool	expand
	)

inline

Initializes a free list with the given capacity.

If capacity is non-zero, then it will allocate that many objects ahead of time. If expand is false, then it will never allocate any objects beyond those preallocated in this constructor.

Parameters

capacity	the number of objects to preallocate
expand	whether to allow non-preallocated objects

Returns: true if initialization was successful.

◆ isExpandable()

template<class T >

bool cugl::FreeList< T >::isExpandable ( ) const

inline

Returns whether this free list is allowed to allocate additional memory.

If the free list is not expandable, the capacity is the maximum number of objects that may be allocated at any given time.

Returns: whether this free list is allowed to allocate additional memory.

◆ malloc()

template<class T >

T * cugl::FreeList< T >::malloc ( )

Returns a pointer to a newly allocated T object.

If there are any objects on the free list, it will recycle them. Next, if there are any preallocated objects, it will use one of those. Finally, it checks to see if the list is expandable or not. If so, it will allocate an additional object. Otherwise, it will return nullptr.

Returns: a pointer to a newly allocated T object.

The number of objects released.

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

include/cugl/util/CUFreeList.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

template<class T> class cugl::FreeList< T >

Constructor & Destructor Documentation

◆ FreeList()

◆ ~FreeList()

Member Function Documentation

◆ alloc()

◆ clear()

◆ dispose()

◆ free()

◆ getAvailable()

◆ getCapacity()

◆ getPeakUsage()

◆ getPreallocated()

◆ getUsage()

◆ init() [1/2]

◆ init() [2/2]

◆ isExpandable()

◆ malloc()

Member Data Documentation

◆ _allocated

◆ _capacity

◆ _expandable

◆ _expansion

◆ _freeobjs

◆ _peaksize

◆ _prealloc

◆ _released

template<class T>
class cugl::FreeList< T >