Class CachedMemorySource

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

A read-only adapter that remembers the bytes of exact requests until the backing source's generation changes.

public sealed class CachedMemorySource : IMemorySource

Inheritance

object

CachedMemorySource

Implements

IMemorySource

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Analyzers read the same few ranges repeatedly: the link field of every list node, the header of every page. When the backing source is a file or a remote transport, answering those repeats from memory is much cheaper. This cache stores the result of each complete read under the key (address, requested length) and returns it for an identical later request.

The design is deliberately simple so its behavior can be predicted. There is no page prefetch and no merging of overlapping ranges, so the cache never reads neighboring bytes that might be unavailable; reading four bytes and then two bytes at the same address are two different entries. Capacity is a retained byte count with first-in, first-out eviction; a hit does not refresh an entry's position. Requests larger than the capacity are answered but not stored, and short reads are not stored because they do not describe the whole range. A hit still charges one request (so loops remain bounded) but charges no backing bytes.

Correctness depends entirely on Generation: the cache empties itself when the backing generation differs from the one it last saw. Use it only over an immutable snapshot or over a source that advances its generation on every change. A live source with unreported changes must not be cached, because stale entries would be returned indefinitely. The adapter is read-only; plan writes through the writable source beneath it, whose generation change then invalidates the cache.

Constructors

CachedMemorySource(string, IMemorySource, int)

Creates an empty cache in front of a caller-owned source.

public CachedMemorySource(string id, IMemorySource source, int capacity = 1048576)

Parameters

id string

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

source IMemorySource

Caller-owned backing source; ownership is not transferred.

capacity int

Maximum number of bytes retained across all entries; larger single requests bypass storage.

Properties

Generation

Gets the backing source's generation; a change is acted on at the next read.

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)

Answers from the cache when the exact range is present; otherwise reads the backing source and stores a complete result.

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

Parameters

address ulong

Unsigned address in the backing source's coordinate system.

destination Span<byte>

Caller-owned destination used only during this call.

context MemoryAccessContext

Shared operation budget and cancellation; a hit charges one request and zero bytes.

Returns

int

The number of bytes copied into the destination.