Class OverlayMemorySource

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

A copy-on-write layer: reads come from an unchanged backing snapshot except where this overlay holds replacement bytes.

public sealed class OverlayMemorySource : IWritableMemorySource, IMemorySource

Inheritance

object

OverlayMemorySource

Implements

IWritableMemorySource

IMemorySource

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Editing a capture in place is risky and often impossible (the file may be read-only or gigabytes large). An overlay solves both problems: it forwards every read to the backing source and then substitutes the bytes it has recorded, so the original is never modified and the memory cost is proportional to the edit rather than to the image. Discarding the overlay discards the experiment. This is the recommended target for MemoryPatch commits when the original must survive.

Changed bytes are kept in a dictionary keyed by address. Only distinct changed addresses count against maxChangedBytes; rewriting an address replaces its entry. A write first verifies that the backing source can supply every byte in the range, so an overlay cannot create bytes where its backing has a hole and cannot extend an image. The backing generation is checked before and after each operation, because an overlay over a snapshot that silently changed would mix two states.

Where the overlay sits in a stack matters for previews: below a MappedMemorySource, patch fragments identify physical image offsets; above it, they identify logical addresses. Export a chosen finite range through OpenRead(MemoryAccessContext?); there is no whole-address-space export.

Constructors

OverlayMemorySource(string, IMemorySource, int)

Creates an empty overlay over a caller-owned backing source, remembering its current generation as the snapshot.

public OverlayMemorySource(string id, IMemorySource backing, int maxChangedBytes = 1048576)

Parameters

id string

Diagnostic label; source objects, not labels, distinguish address spaces.

backing IMemorySource

Caller-owned snapshot that must not change while the overlay is in use.

maxChangedBytes int

Maximum number of distinct addresses the overlay will retain.

Properties

Generation

Gets the overlay's own mutation counter, advanced by each overlay write; backing stability is checked separately.

public long Generation { get; }

Property Value

long

Id

Gets the diagnostic label for this source.

public string Id { get; }

Property Value

string

Methods

Read(ulong, Span<byte>, MemoryAccessContext)

Copies up to destination.Length bytes starting at address and returns the count copied.

public int Read(ulong address, Span<byte> destination, MemoryAccessContext context)

Parameters

address ulong

Unsigned address in this source's own coordinate system (file offset, virtual address, or whatever the source defines).

destination Span<byte>

Caller-owned buffer, valid only for the duration of the call.

context MemoryAccessContext

Shared operation budget; leaf sources charge bytes, translation adapters charge zero-byte requests.

Returns

int

The number of bytes copied, never greater than the buffer length.

Remarks

Zero means the bytes are unavailable; a finite view turns that into a MissingBytes failure rather than treating it as end of file. An implementation may also throw a structured MemoryAccessException, for example Unmapped for a hole it can name.

Write(ulong, ReadOnlySpan<byte>, MemoryAccessContext)

Replaces bytes starting at address. The range must already exist; writing never extends a source.

public void Write(ulong address, ReadOnlySpan<byte> bytes, MemoryAccessContext context)

Parameters

address ulong

Unsigned start address in this source's own coordinate system.

bytes ReadOnlySpan<byte>

Replacement bytes; the source copies them and does not retain the span.

context MemoryAccessContext

Shared budget and cancellation for the operation; the write charges its byte count.

Exceptions

MemoryAccessException

The range is outside the source, the budget is exhausted, or the source state prevents the write.

OperationCanceledException

Cancellation was requested before the write.