Class ByteArrayMemorySource

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

An in-memory writable image: a private copy of a byte array whose addresses are zero-based indexes.

public sealed class ByteArrayMemorySource : IWritableMemorySource, IMemorySource

Inheritance

object

ByteArrayMemorySource

Implements

IWritableMemorySource

IMemorySource

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This is the simplest source and the one most tests and examples use. It is also a reasonable representation of a small capture that has been loaded entirely into memory. Its addresses are indexes into the owned array; to present those bytes at process addresses, put a MappedMemorySource in front of it.

The constructor copies its input and ToArray() returns a copy, so no caller ever holds a reference to the internal buffer; that is what makes the generation counter trustworthy, because every mutation goes through Write(ulong, ReadOnlySpan<byte>, MemoryAccessContext). Each read or write holds a lock, but two consecutive operations are not one atomic snapshot. The array has a fixed length: a write cannot extend it, and a read past the end returns fewer bytes.

Constructors

ByteArrayMemorySource(string, ReadOnlySpan<byte>)

Copies the supplied bytes into a new independent image.

public ByteArrayMemorySource(string id, ReadOnlySpan<byte> bytes)

Parameters

id string

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

bytes ReadOnlySpan<byte>

Initial contents, copied so later changes to the caller's buffer do not affect the image.

Properties

Generation

Gets the mutation counter: zero at construction, incremented after each successful write.

public long Generation { get; }

Property Value

long

Id

Gets the diagnostic label for this source.

public string Id { get; }

Property Value

string

Length

Gets the size of the image in bytes.

public int Length { get; }

Property Value

int

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.

ToArray()

Returns a snapshot of the current bytes; later writes do not affect the returned array.

public byte[] ToArray()

Returns

byte[]

An independent copy of the image.

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.