Class MemoryAccessException

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

A failure of an addressed memory operation, carrying a stable category and the coordinates of the fragment that failed.

public sealed class MemoryAccessException : CStructReadException, ISerializable

Inheritance

object

Exception

CStructException

CStructReadException

MemoryAccessException

Implements

ISerializable

Inherited Members

CStructException.Code

CStructException.Offset

CStructException.Path

CStructException.Member

CStructException.MemberType

CStructException.Message

Exception.GetBaseException()

Exception.ToString()

Exception.GetType()

Exception.TargetSite

Exception.Data

Exception.InnerException

Exception.HelpLink

Exception.Source

Exception.HResult

Exception.StackTrace

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Reading captured memory fails for reasons a caller needs to tell apart: a page was never captured, a file was truncated, a budget ran out, a source changed under a prepared patch. Failure is the stable category for programmatic handling; Message adds detail and InnerException can retain a transport cause. None of these cases is ever reported as a successful zero-filled read.

The class is a CStructReadException, so one handler can catch every CStructSharp read failure. Code is ReadLimitExceeded for BudgetExceeded and ReadFailed for every other category.

The exception carries two coordinate systems on purpose. SourceId, Address, and Length identify the fragment that actually failed, which may be a file offset several mapping layers below the caller's request. SourceId and Address are null when the failure is not tied to a source address, such as a depth limit or the byte budget of serialized output. Path and LogicalRegion are filled in when the failure crosses a MemorySession call and identify what the caller asked for. Show both in a diagnostic; never present a backing offset as if it were the process address.

Invalid arguments, malformed paths (CStructPathException), unencodable values (CStructWriteException), invalid schemas or metadata (CStructLayoutException), and cancellation use other exception types; this class is for operations that were well-formed but could not be completed against the addressed memory.

Constructors

MemoryAccessException(MemoryFailure, string?, ulong?, int, string, Exception?)

Creates a structured failure, prefixing the message with the source label, address, and length when both coordinates are known.

public MemoryAccessException(MemoryFailure failure, string? sourceId, ulong? address, int length, string message, Exception? inner = null)

Parameters

failure MemoryFailure

Stable failure category; BudgetExceeded selects ReadLimitExceeded.

sourceId string

Label of the source in which the failure occurred, or null when the failure is not tied to a source.

address ulong?

Unsigned address of the failing fragment in that source, or null when the failure is not tied to an address.

length int

Byte length of the failing request.

message string

Human-readable detail, appended to the coordinates when they are known.

inner Exception

Underlying transport or commit exception, if any.

Properties

Address

Gets the unsigned address of the failing fragment, in SourceId's coordinate system, or null when the failure is not tied to an address.

public ulong? Address { get; }

Property Value

ulong?

Failure

Gets the stable failure category for programmatic handling.

public MemoryFailure Failure { get; }

Property Value

MemoryFailure

Length

Gets the byte length of the failing request.

public int Length { get; }

Property Value

int

LogicalRegion

Gets the caller's logical root region, set when the failure crossed a session operation; otherwise null.

public MemoryRegion? LogicalRegion { get; }

Property Value

MemoryRegion

SourceId

Gets the label of the source in which the failure occurred, or null when the failure is not tied to a source.

public string? SourceId { get; }

Property Value

string