Class MemoryAllocator

Namespace

SixLabors.ImageSharp.Memory

Assembly

SixLabors.ImageSharp.dll

Memory managers are used to allocate memory for image processing operations.

public abstract class MemoryAllocator

Inheritance

object

MemoryAllocator

Derived

SimpleGcMemoryAllocator

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

MemoryAllocatorExtensions.Allocate2D<T>(MemoryAllocator, Size, AllocationOptions)

MemoryAllocatorExtensions.Allocate2D<T>(MemoryAllocator, Size, bool, AllocationOptions)

MemoryAllocatorExtensions.Allocate2D<T>(MemoryAllocator, int, int, AllocationOptions)

MemoryAllocatorExtensions.Allocate2D<T>(MemoryAllocator, int, int, bool, AllocationOptions)

Properties

AccumulativeAllocationLimitBytes

Gets or sets the maximum accumulative size, in bytes, of all active allocations made through this allocator instance.

public long AccumulativeAllocationLimitBytes { get; protected set; }

Property Value

long

Remarks

Defaults to MaxValue, effectively imposing no limit on the accumulative total. When set, this provides a safeguard against excessive memory consumption by capping the combined size of outstanding allocations issued by this instance.
When the accumulative size of active allocations exceeds this limit, an InvalidMemoryOperationException will be thrown to prevent further allocations and signal that the limit has been breached. The setter is available to derived allocators and requires a positive value.

Exceptions

ArgumentOutOfRangeException

The value is not greater than zero.

Default

Gets the default platform-specific global MemoryAllocator instance that serves as the default value for MemoryAllocator.

This is a get-only property, you should set Default's MemoryAllocator to change the default allocator used by Image and it's operations.

public static MemoryAllocator Default { get; }

Property Value

MemoryAllocator

MemoryGroupAllocationLimitBytes

Gets or sets the maximum number of bytes that can be allocated by a memory group. A memory group backs the pixel buffer of a single image, so this limits the total image size.

public long MemoryGroupAllocationLimitBytes { get; protected set; }

Property Value

long

Remarks

The default limit is determined by the process architecture: 4 GB for 64-bit processes and 1 GB for 32-bit processes. The setter is available to derived allocators and requires a positive value.

Exceptions

ArgumentOutOfRangeException

The value is not greater than zero.

SingleBufferAllocationLimitBytes

Gets or sets the maximum size, in bytes, that can be allocated for a single contiguous buffer. This limit applies to Allocate<T>(int, AllocationOptions) and to contiguous image buffers requested through PreferContiguousImageBuffers.

public int SingleBufferAllocationLimitBytes { get; protected set; }

Property Value

int

Remarks

The single buffer allocation limit is set to 1 GB by default. A single contiguous buffer can never exceed MaxValue bytes; larger images are backed by discontiguous memory groups limited by MemoryGroupAllocationLimitBytes. The setter is available to derived allocators and requires a positive value.

Exceptions

ArgumentOutOfRangeException

The value is not greater than zero.

Methods

AllocateCore<T>(int, AllocationOptions)

Allocates a tracked memory owner for Allocate<T>(int, AllocationOptions).

protected abstract AllocationTrackedMemoryManager<T> AllocateCore<T>(int length, AllocationOptions options = AllocationOptions.None) where T : struct

Parameters

length int

Size of the buffer to allocate.

options AllocationOptions

The allocation options.

Returns

AllocationTrackedMemoryManager<T>

A tracked memory owner of values of type T.

Type Parameters

T

Type of the data stored in the buffer.

Remarks

Implementations should only allocate and initialize the concrete owner. The base allocator reserves bytes, attaches tracking to the returned owner, and releases the reservation if allocation fails.

Allocate<T>(int, AllocationOptions)

Allocates an IMemoryOwner<T>, holding a Memory<T> of length length.

public IMemoryOwner<T> Allocate<T>(int length, AllocationOptions options = AllocationOptions.None) where T : struct

Parameters

length int

Size of the buffer to allocate.

options AllocationOptions

The allocation options.

Returns

IMemoryOwner<T>

A buffer of values of type T.

Type Parameters

T

Type of the data stored in the buffer.

Exceptions

InvalidMemoryOperationException

When length is negative or over the capacity of the allocator.

ApplyOptions(MemoryAllocatorOptions)

Applies the supplied MemoryAllocatorOptions to this instance. Derived allocators can call this from their constructors to accept user configuration.

protected void ApplyOptions(MemoryAllocatorOptions options)

Parameters

options MemoryAllocatorOptions

The options to apply. Properties left as null are ignored.

Remarks

The applied single buffer limit is capped to MemoryGroupAllocationLimitBytes, because a single contiguous buffer can never be larger than the total allocation limit.

Create()

Creates a default instance of a MemoryAllocator optimized for the executing platform.

public static MemoryAllocator Create()

Returns

MemoryAllocator

The MemoryAllocator.

Create(MemoryAllocatorOptions)

Creates the default MemoryAllocator using the provided options.

public static MemoryAllocator Create(MemoryAllocatorOptions options)

Parameters

options MemoryAllocatorOptions

The MemoryAllocatorOptions.

Returns

MemoryAllocator

The MemoryAllocator.

GetBufferCapacityInBytes()

Gets the length of the largest contiguous buffer that can be handled by this allocator instance in bytes.

protected abstract int GetBufferCapacityInBytes()

Returns

int

The length of the largest contiguous buffer that can be handled by this allocator instance.

ReleaseRetainedResources()

Releases all retained resources not being in use. Eg: by resetting array pools and letting GC to free the arrays.

public virtual void ReleaseRetainedResources()

Remarks

This does not dispose active allocations; callers are responsible for disposing all IMemoryOwner<T> instances to release memory.