Class StreamMemorySource

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

A read-only source over a caller-owned seekable stream, typically a capture file, whose addresses are file offsets.

public sealed class StreamMemorySource : IMemorySource

Inheritance

object

StreamMemorySource

Implements

IMemorySource

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This adapter lets a large capture be analyzed without loading it into memory. Its addresses are positions in the stream, so they must fit a signed Position; a MappedMemorySource above it can still expose those bytes at addresses beyond MaxValue, because translation happens before the stream is touched.

Each read seeks to the requested offset and restores the previous position in a finally block, so code that shares the stream for other purposes sees it unchanged. The adapter's lock serializes calls made through this object only; direct use of the stream by other code still needs the caller's own synchronization.

The adapter cannot observe changes made to the file by other programs, so Generation is a constant supplied at construction rather than a real change counter. Keep the file stable while analyzing or caching it, and dispose the stream yourself after every non-owning view has finished with it.

Constructors

StreamMemorySource(string, Stream, long)

Wraps a readable, seekable stream without taking ownership of it.

public StreamMemorySource(string id, Stream stream, long generation = 0)

Parameters

id string

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

stream Stream

Caller-owned stream that supports reading and seeking.

generation long

Constant snapshot label reported as the generation; the adapter cannot detect external changes.

Properties

Generation

Gets the constant snapshot label supplied at construction; external file changes are not detected.

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.