Class GorgonPool<T>

A memory allocation strategy that uses a standar pool/free list allocator to perform memory allocations.

Inheritance

object

GorgonPool<T>

Implements

IGorgonAllocator<T>

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.Memory

Assembly: Gorgon.Core.dll

Syntax

public class GorgonPool<T> : IGorgonAllocator<T> where T : class

Type Parameters

Name	Description
T	The type of objects to allocate. These must be a reference type.

Remarks

While the .NET memory manager is quite fast (e.g. new), and is useful for most cases, it does have the problem of creating garbage. When these items are created and discarded, the garbage collector may kick in at any given time, causing performance issues during time critical code (e.g. a rendering loop). By allocating a large pool of objects and then drawing directly from this pool, we can reuse existing, but expired objects to ensure that the garbage collector does not collect these items until we are truly done with them.

This type will allocate a new object on demand (and optionally initialize that new object). When the user is done with the object, they can deallocate it and it will be put back into a free list, which allows us to reuse an object as needed. This puts the responsibility on the user to ensure they deallocate objects they are using, otherwise the benefits provided by this allocator are nullified.

This allocator will never grow beyond its initial size. So care must be taken ahead of time to ensure the pool is large enough.

Constructors

GorgonPool(int, Func<T>)

Initializes a new instance of the GorgonLinearPool<T> class.

Declaration

public GorgonPool(int objectCount, Func<T> allocator)

Parameters

Type	Name	Description
int	objectCount	The number of total objects available to the allocator.
Func<T>	allocator	The allocator used to create an object in the pool.

Remarks

The allocator callback method passed will be executed for each object that has not been initialized in the pool (i.e. the object would be returned as null when allocated). This ensures that the allocator can correctly initialize the object prior to allocation in the pool.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when the objectCount parameter is less than 1.
ArgumentNullException	Thrown when the allocator parameter is null.

Properties

AvailableSlots

Property to return the number of available slots in the pool.

Declaration

public int AvailableSlots { get; }

Property Value

Type	Description
int

Remarks

When this value is 0, then the pool is full and should be reset using the Reset() method.

See Also

Reset()

ItemAllocator

Property to set or return the allocator to use when creating new instances of an object.

Declaration

protected Func<T> ItemAllocator { get; set; }

Property Value

Type	Description
Func<T>

TotalSize

Property to return the number of items available to the allocator.

Declaration

public int TotalSize { get; }

Property Value

Type	Description
int

Methods

Allocate(Action<T>)

Function to allocate a new object from the pool.

Declaration

public T Allocate(Action<T> initializer = null)

Parameters

Type	Name	Description
Action<T>	initializer	[Optional] A function used to initialize the object returned by the allocator.

Returns

Type	Description
T	The newly allocated object.

Remarks

Applications should check to ensure that there is enough free space in the pool to allocate another object by checking the AvailableSlots property prior to calling this method. If there is no more room (i.e. AvailableSlots is 0), then applications should call the Reset() method to reset the pool.

If the initializer parameter is supplied, then this callback method can be used to initialize the new object before returning it from the allocator. If the object returned is null (because an allocator was not supplied to the constructor), then this parameter will be ignored.

Exceptions

Type	Condition
GorgonException	Thrown when the pool is completely full.

See Also

AvailableSlots

Reset()

Deallocate(ref T, Action<T>)

Function to deallocate an item allocated by this pool.

Declaration

public void Deallocate(ref T item, Action<T> finalizer = null)

Parameters

Type	Name	Description
T	item	The item to deallocate.
Action<T>	finalizer	[Optional] A finalizer callback method used to clean up the object before putting it back in the pool.

Remarks

The item parameter will be passed by reference to the method so that it will be set to null upon deallocation. This keeps the end user from using the object after it's been deallocated.

If the finalizer callback method is supplied, then the object will have a chance to be cleaned up prior to putting it back into the pool.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the item parameter is null.
GorgonException	Thrown when there is no more room to add an item to the free list.

Reset()

Function to reset the allocator heap and "free" all previous instances.

Declaration

public void Reset()

Remarks

This method does not actually free any memory in the traditional sense, but merely resets the allocation pointer back to the beginning of the heap to allow re-use of objects.

Implements

IGorgonAllocator<T>

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)