CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
cugl::FreeList< T > Class Template Reference

#include <CUFreeList.h>

Inheritance diagram for cugl::FreeList< T >:
cugl::GreedyFreeList< 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 TgetPreallocated () const
 
Tmalloc ()
 
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
capacitythe number of objects to preallocate
expandwhether 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
objthe 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
capacitythe 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
capacitythe number of objects to preallocate
expandwhether 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.

Member Data Documentation

◆ _allocated

template<class T >
size_t cugl::FreeList< T >::_allocated
protected

The number of objects allocated so far

◆ _capacity

template<class T >
size_t cugl::FreeList< T >::_capacity
protected

The capacity of the preallocated objects

◆ _expandable

template<class T >
bool cugl::FreeList< T >::_expandable
protected

Whether or not we can add objects beyond the ones preallocated

◆ _expansion

template<class T >
std::queue<T*> cugl::FreeList< T >::_expansion
protected

Place to put the expanded objects

◆ _freeobjs

template<class T >
std::queue<T*> cugl::FreeList< T >::_freeobjs
protected

The list of objects in the free list

◆ _peaksize

template<class T >
size_t cugl::FreeList< T >::_peaksize
protected

The memory high water mark

◆ _prealloc

template<class T >
T* cugl::FreeList< T >::_prealloc
protected

The array of preallocated objects

◆ _released

template<class T >
size_t cugl::FreeList< T >::_released
protected

The number of objects released.


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