Class MemorySchema

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

A validated, immutable graph of type definitions with explicit placement, compiled so the core codecs can decode its scalars.

public sealed class MemorySchema

Inheritance

object

MemorySchema

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

A Portable CStruct computes where members go from their declaration order and the layout rules. A memory schema does the opposite: it takes sizes and offsets as given, because they were decided by another platform's compiler and recorded in metadata. The constructor checks that the given placement is internally consistent (references exist, members fit, struct members do not overlap, arrays have the declared extent, no type contains itself by value) and then compiles the pieces the core library needs to decode and encode values. Pointer cycles remain legal because a pointer has a finite size.

Types is the semantic graph: real names, IDs, offsets, bit slices, and provenance, which is what an analyzer should show. The recorded placement is checked directly against these definitions; no layout is compiled for a struct, union, or array. To decode, the schema compiles small core scalar layouts (struct __memory_scalar { T value; }) and one per bitfield slice. Equivalent built-in scalar encodings share a layout within the schema; caller-supplied codecs and declarations compile independently. The APIs reuse these scalar and bitfield codecs instead of a second decoder. Their generated names never appear in results.

Compile once and reuse the schema across many regions and sessions; it holds no source bytes or mutable per-operation state.

Constructors

MemorySchema(IEnumerable<MemoryTypeDefinition>, bool, CStructCompilationOptions?, int, int, int, CancellationToken, bool)

Snapshots, validates, and compiles a type graph. Placement comes from the definitions; nothing is inferred from the host.

public MemorySchema(IEnumerable<MemoryTypeDefinition> types, bool isLittleEndian = true, CStructCompilationOptions? options = null, int maxTypes = 100000, int maxFields = 1000000, int pointerSize = 8, CancellationToken cancellationToken = default, bool bestEffort = false)

Parameters

types IEnumerable<MemoryTypeDefinition>

Definitions to include; every ID they reference must be among them.

isLittleEndian bool

Byte order for scalars that do not specify their own.

options CStructCompilationOptions

Core compilation options, including any fixed custom codecs that scalars may name.

maxTypes int

Maximum number of definitions accepted, bounding work on hostile metadata.

maxFields int

Maximum total number of fields across all definitions.

pointerSize int

Target pointer width in bytes; it describes the analyzed image, not the analyzing process.

cancellationToken CancellationToken

Checked between definitions during validation and compilation.

bestEffort bool

When true, a definition that fails its own validation is demoted to a same-sized RawBytes placeholder and noted in Diagnostics, instead of the whole schema failing; when false (the default), any validation failure throws.

Exceptions

ArgumentNullException

types is null.

ArgumentOutOfRangeException

maxTypes or maxFields is not positive, or pointerSize is not 1, 2, 4, or 8.

CStructLayoutException

The definitions are invalid: they exceed the type or field budget, repeat an ID, reference an unknown ID, place a member outside its container, overlap struct members, disagree with a scalar codec's size, or contain a type by value within itself. In best-effort mode only whole-graph failures (budgets, duplicate IDs, by-value recursion) throw.

OperationCanceledException

cancellationToken was cancelled.

Properties

Diagnostics

Gets one note per definition that best-effort validation demoted to RawBytes, in ordinal order; empty unless the schema was constructed with bestEffort: true.

public IReadOnlyList<string> Diagnostics { get; }

Property Value

IReadOnlyList<string>

IsLittleEndian

Gets the default byte order: true when the least significant byte is stored first.

public bool IsLittleEndian { get; }

Property Value

bool

PointerSize

Gets the target pointer width in bytes, used to compile pointer-width integer aliases.

public int PointerSize { get; }

Property Value

int

Types

Gets the semantic graph: every validated definition keyed by its ID.

public IReadOnlyDictionary<string, MemoryTypeDefinition> Types { get; }

Property Value

IReadOnlyDictionary<string, MemoryTypeDefinition>

Methods

BindBytes(string, string)

Prepares a fixed raw byte-array path without retaining captured storage.

public MemoryByteReader BindBytes(string typeId, string path)

Parameters

typeId string

Root type identity.

path string

Selected array of one-byte scalars.

Returns

MemoryByteReader

Reusable raw reader; text encoding and termination remain explicit caller decisions.

Exceptions

CStructPathException

The path is invalid.

ArgumentException

The field is not a byte array.

Bind<T>(string, string)

Prepares a typed scalar or stored-pointer reader; binding never reads captured bytes or invokes custom decoders.

public MemoryFieldReader<T> Bind<T>(string typeId, string path = "")

Parameters

typeId string

Root type identity.

path string

Relative scalar or pointer path.

Returns

MemoryFieldReader<T>

A reusable reader retaining this schema, not operation state.

Type Parameters

T

The exact result type for built-in 8/16/24/32/64-bit integers, bool, float32/float64, enum results, bit slices or StoredPointer. Other scalar codecs, including custom codecs, bind as object.

Exceptions

CStructPathException

The path is invalid or its result type differs from T.

GetField(string, string)

Finds an immediate member by name; promoted members are resolved by session paths, not here.

public MemoryField GetField(string typeId, string name)

Parameters

typeId string

Stable identity of the containing struct or union.

name string

Member name as declared in the definition.

Returns

MemoryField

The member's field descriptor.

Exceptions

ArgumentNullException

typeId is null.

CStructPathException

No definition has ID typeId, or it has no immediate member named name.

GetType(string)

Looks up a definition by ID; an unknown ID is an error, never a guessed type.

public MemoryTypeDefinition GetType(string id)

Parameters

id string

Stable identity of the definition.

Returns

MemoryTypeDefinition

The definition with that ID.

Exceptions

ArgumentNullException

id is null.

CStructPathException

No definition has that ID.

Select(string, string)

Prepares a path without accessing memory, including paths that require pointer reads when applied.

public MemoryPath Select(string typeId, string path = "")

Parameters

typeId string

Root type identity.

path string

Relative member/index/pointer path; empty selects the root.

Returns

MemoryPath

The immutable plan, including its constant offset when one exists.

Exceptions

CStructPathException

The type or path cannot be selected.

TryBind<T>(string, string, out MemoryFieldReader<T>?, out MemoryReadFailure?)

Prepares a typed reader, returning absence, ambiguity and incompatible managed types as structured outcomes.

public bool TryBind<T>(string typeId, string path, out MemoryFieldReader<T>? reader, out MemoryReadFailure? failure)

Parameters

typeId string

Root type identity.

path string

Relative selected path.

reader MemoryFieldReader<T>

Prepared reader on success; null otherwise.

failure MemoryReadFailure

Structured binding failure on false.

Returns

bool

Whether a reader was created.

Type Parameters

T

Exact scalar result type, StoredPointer for pointers, or object for arbitrary codecs.

TrySelect(string, string, out MemoryPath?, out MemoryReadFailure?)

Prepares a schema path without throwing for absent or ambiguous members or invalid traversal.

public bool TrySelect(string typeId, string path, out MemoryPath? selection, out MemoryReadFailure? failure)

Parameters

typeId string

Root type identity.

path string

Relative path.

selection MemoryPath

Prepared plan on success; null otherwise.

failure MemoryReadFailure

Structured explanation on failure; null otherwise.

Returns

bool

Whether the schema defines this selection.