Class PooledPixelMemorySource

Namespace

Egami

Assembly

Egami.dll

The default IPixelMemorySource. Small blocks are arrays rented from a shared pool; larger blocks are unmanaged memory aligned to 64 bytes, which stays off the large object heap and suits SIMD. Planes larger than MaxBlockBytes are split into several blocks of whole rows.

public sealed class PooledPixelMemorySource : IPixelMemorySource

Inheritance

object

PooledPixelMemorySource

Implements

IPixelMemorySource

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Every pixel buffer comes from the context's IPixelMemorySource; wrap the pooled one to count what it hands out.
CountingSource counting = new(PooledPixelMemorySource.Shared);
EgamiContext context = EgamiContext.Default with { Memory = counting };
using (Raster<Rgba8> image = Raster.Create<Rgba8>(512, 512, context))
{
    image.Apply(ops => ops.Blur(2));
}

Console.WriteLine($"{counting.Blocks} blocks, {counting.Bytes:N0} bytes");

Remarks

Unmanaged blocks are kept after use, up to MaxRetainedBytes, and reused by later allocations of a similar size, because memory fresh from the operating system is slow the first time it is written. Trim() frees what is kept.

Properties

MaxBlockBytes

Gets the largest block, in bytes, the source hands out in one piece. Planes bigger than this are split into several blocks, each holding whole rows. A single row larger than this still gets one block of its own.

public int MaxBlockBytes { get; init; }

Property Value

int

Remarks

Defaults to 64 MB.

Exceptions

ArgumentOutOfRangeException

The value is less than 1.

MaxRetainedBytes

Gets the most unmanaged memory, in bytes, kept after use for reuse. 0 frees every block as soon as it is disposed. Defaults to 128 MB.

public long MaxRetainedBytes { get; init; }

Property Value

long

Exceptions

ArgumentOutOfRangeException

The value is negative.

RetainedBytes

Gets the bytes currently kept for reuse.

public long RetainedBytes { get; }

Property Value

long

Shared

Gets the shared instance with the default settings.

public static PooledPixelMemorySource Shared { get; }

Property Value

PooledPixelMemorySource

Usage

Gets the counts of blocks handed out and not yet disposed, and the switch for leak tracking.

public PixelMemoryUsage Usage { get; }

Property Value

PixelMemoryUsage

Methods

Allocate(int, ClearMode)

Allocates one contiguous block of memory.

public IMemoryOwner<byte> Allocate(int byteLength, ClearMode clear)

Parameters

byteLength int

The size of the block in bytes. The returned memory has exactly this length.

clear ClearMode

Whether to zero the block.

Returns

IMemoryOwner<byte>

The block. Disposing it returns the memory to the source.

Exceptions

ArgumentOutOfRangeException

byteLength is negative.

Trim()

Frees all unmanaged memory kept for reuse. Memory in use is not affected.

public void Trim()