Class GorgonRingPool<T>

A memory allocation strategy that uses a circular buffer to perform memory allocations.

Inheritance

object

GorgonRingPool<T>

GorgonDrawCallPoolAllocator<T>

GorgonStateBuilderPoolAllocator<T>

GorgonStreamOutCallPoolAllocator

Gorgon2DBatchStatePoolAllocator

Gorgon2DShaderStatePoolAllocator<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 GorgonRingPool<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 allocator will allocate objects up until its total size, and then start over from the beginning if this value is exceeded. Objects returned will be reused.

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

GorgonRingPool(int, Func<T>)

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

Declaration

public GorgonRingPool(int objectCount, Func<T> allocator = null)

Parameters

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

Remarks

If the allocator parameter is not null, then the 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. If this parameter is omitted, then it is up to the user to create the object if the allocator returns null.

Exceptions

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

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(bool) method.

See Also

Reset(bool)

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	A reference to the object in the pool.

Remarks

This method returns the object from the pool.

Applications can 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, then the allocator will wrap around to the beginning of the pool and return objects from there.

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.

See Also

AvailableSlots

Reset(bool)

Reset(bool)

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

Declaration

public void Reset(bool dispose = false)

Parameters

Type	Name	Description
bool	dispose	[Optional] true to force objects that implement IDisposable to call their Dispose methods and reset the pool, or false to just reset the pool.

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.

If the dispose parameter is true, and the objects in the pool implement IDisposable, then all objects will be traversed and their dispose methods will be called. This may cause performance issues and should be used sparingly and the ideal is to not store IDisposable objects in the pool.

Implements

IGorgonAllocator<T>

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)