Interface IMemorySource

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

A caller-owned unsigned address space: the object that can answer "which bytes are at this address?".

public interface IMemorySource

Remarks

This is the lowest layer of the memory APIs. Everything above it (regions, sessions, walkers, patches) works in terms of a source and an unsigned address, and never cares whether the bytes come from an array, a file, a mapping table, or a debugger connection. Implementing this interface is how an application plugs in a transport the library does not know.

An address has meaning only together with its source. Address 0x1000 in two processes can select different bytes, so the library distinguishes address spaces by object identity, not by the Id label. Two sources with the same label are still two spaces; keep and reuse one source object while following addresses within one space.

The contract an implementation must honor: return the number of bytes actually copied, which may be fewer than requested (a positive short read); return zero only when no bytes are available at that address; never turn a hole or a transport error into zero-filled success, because a fabricated zero is indistinguishable from a real one; call Charge(string?, ulong?, int) before performing a leaf read; and forward the same context through any adapter so one operation keeps one budget. Generation is a change counter that lets caches and patches notice that bytes changed; it is not a lock or a snapshot, so a source that cannot observe its own changes must report a constant value and document that the caller keeps it stable.

Properties

Generation

Gets a change counter that advances on every observable mutation, or a constant when consistency is guaranteed externally.

long Generation { get; }

Property Value

long

Id

Gets a stable label for diagnostics and error messages. Object identity, not this label, distinguishes address spaces.

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.

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.