Class SqliteNcResultReader

Namespace

Hi.SqliteUtils

Assembly

HiNc.dll

Internal Use Only. The reader of one result file (the NC play result recording's P2), opened read-only by OpenRead(string): the file's Meta and NC source files, read once; a step's narrow row without its chunk (TryGetStepRow(int, out NcResultStepRow)), a step's whole record (TryGetMachiningStep(int, out MachiningStepRecord)) or a window of them (FindMachiningSteps(int, int, bool)), a step's briefs (TryGetStepBrief(int, out StepBrief), FindStepBriefs(int, int)), the strip positions in order (EnumerateClStripPositions(int, int)), a piece by its id (TryGetSyntaxPiece(int, out SyntaxPieceRecord)), the pieces of a source line by path (FindPieceIds(string, int)) or by file index (FindPieceIds(int, int); FindPieceAddresses(int, int, int) for a range of lines), a step's block text (TryGetStepBlockText(int, out string)), and the finished stock's node map whole (ReadNodeAttachments(), schema version 2).

A record is read by locating its chunk (StepIndex / 1024 for the step-indexed kinds, the index row for a piece) and decompressing the chunk; the reader keeps the last LruChunks decoded chunks of each kind, so a step next to the last one read costs a slice, a step far from it a decompression (a millisecond or so for a step chunk, under a millisecond for a piece chunk). A window of steps or briefs decodes each chunk it crosses once. Everything a call returns is a copy or an object of its own: nothing aliases the reader's buffers. The sentence snapshots of a piece chunk are kept with the chunk and nowhere else, so the records of one piece -- its steps' and its own -- share one snapshot object while the chunk is cached; once the chunk has left the cache, the snapshot is rebuilt as another object, equal in every value it carries. The file path of every snapshot is the one string the reader keeps for that path (the paths of NcFiles first), as a live play's sentences share theirs.

A file that was not completed reads as far as it was committed: a step or piece row whose chunk never reached the file reads as no record (TryGetStepRow(int, out NcResultStepRow) true and TryGetMachiningStep(int, out MachiningStepRecord) false, a step's Sentence null, a piece absent, a window skipping the chunk). A chunk that is in the file but not a chunk this build reads -- another codec, a layout version, a slot pointing outside its payloads, a payload the wire formats refuse, cut short or with a bad string length -- throws InvalidDataException; a failure of SQLite itself comes out as SqliteException. Any thread may call the reader, one call at a time: every method, Dispose() included, runs under the reader's lock and waits there for a call in progress, and an enumeration of positions holds the lock only while it decodes one chunk. After Dispose(), every method but Dispose() throws ObjectDisposedException, an empty window included (a null path of FindPieceIds(string, int) is refused first), while DatabasePath, Meta and NcFiles stay readable.

public sealed class SqliteNcResultReader : IDisposable

Inheritance

object

SqliteNcResultReader

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DuplicateUtil.TryDuplicate<TSelf>(TSelf, params object[])

InvokeUtil.SelfInvoke<TSrc>(TSrc, Action<TSrc>)

InvokeUtil.SelfInvoke<TSrc, TDst>(TSrc, Func<TSrc, TDst>)

ColorUtil.GetGloomyColor(object, double, double)

KindNameUtil.KindName(object)

NameUtil.GetSelectionName(object)

StringUtil.GetPropertyStringIfToStringNotOverloaded(object, bool, bool)

LockUtil.Lock(object)

Properties

DatabasePath

The full path of the result file.

public string DatabasePath { get; }

Property Value

string

Meta

The file's metadata, read once when the file was opened: what the writer wrote at the file's creation and, for a completed file, at its completion (NcResultMeta says when a member is null), the times in UTC.

public NcResultMeta Meta { get; }

Property Value

NcResultMeta

NcFiles

The file's NC source files, read once when the file was opened, by file index: a row a file index, with the first path recorded for it.

public IReadOnlyList<NcResultSourceFile> NcFiles { get; }

Property Value

IReadOnlyList<NcResultSourceFile>

StepIndexRange

Internal Use Only (the NC play result review). The smallest and the largest step index of the file's step rows (MachiningStep: the narrow rows, chunk or no chunk), read once when the file was opened; null for a file without a step row. A recording begun in the middle of a mission starts above 0, and a crashed recording's Meta holds no counts: this is what a walk over the steps of any file bounds its windows by. The strip positions and the briefs are not counted here (their walks read their own chunk tables).

public (int First, int Last)? StepIndexRange { get; }

Property Value

(int First, int Last)?

Methods

Dispose()

Closes the file and drops the cached chunks and buffers; waits for a call in progress on another thread. Idempotent.

public void Dispose()

EnumerateClStripPositions(int, int)

Enumerates the strip positions whose index is in [beginIndex, endIndex), by index, lazily: the reader is held while one position chunk is decoded and its positions copied, released while they are yielded; a position never stored is skipped, a chunk the file does not hold skipped whole. (0, int.MaxValue) is the whole strip, one chunk decoded at a time through the reader's cache. Nothing is read, and nothing checked, before the first MoveNext. The enumerator is not thread-safe; a reader disposed mid-way makes the next step of the enumeration throw.

public IEnumerable<ClStripPosRecord> EnumerateClStripPositions(int beginIndex, int endIndex)

Parameters

beginIndex int

The first index (inclusive); a negative one counts as 0.

endIndex int

The index past the last (exclusive); at or below the first, the enumeration is empty.

Returns

IEnumerable<ClStripPosRecord>

The positions, by index.

Exceptions

InvalidDataException

A position chunk is not what this build reads: thrown by the step of the enumeration that decodes it.

ObjectDisposedException

The reader was disposed: thrown by the first step of the enumeration, an empty one included, or by the step after the disposal.

FindMachiningSteps(int, int, bool)

Reads the records of the steps whose index is in [beginIndex, endIndex), by index, each as TryGetMachiningStep(int, out MachiningStepRecord) reads it; a step without a row or a payload is skipped. Each step chunk the window crosses is decoded once. The list holds the whole window: a scan over a play reads it a window at a time, not step by step.

public List<MachiningStepRecord> FindMachiningSteps(int beginIndex, int endIndex, bool withSentences = true)

Parameters

beginIndex int

The first index (inclusive); a negative one counts as 0.

endIndex int

The index past the last (exclusive); at or below the first, the window is empty.

withSentences bool

Whether to rebuild the steps' sentence snapshots – one range query of the piece index rows between the window's smallest and largest piece id, then the piece chunks those rows name, each decoded once; false leaves every Sentence null and reads no piece row, for a window that wants the motions alone.

Returns

List<MachiningStepRecord>

The records, by step index.

Exceptions

InvalidDataException

A chunk, payload or pooled matrix the window reads is not what this build reads.

ObjectDisposedException

The reader was disposed, the window empty or not.

FindMachiningSteps(int, int, bool, out List<NcResultStepRow>)

Internal Use Only (the NC play result review). FindMachiningSteps(int, int, bool), handing out the window's narrow rows as well – every row of the window, as FindStepRows(int, int) reads them, a row whose payload is missing included – off the one range query the records are read by: a walk that pairs the rows' scalars (the piece id above all) with the records reads the window once.

public List<MachiningStepRecord> FindMachiningSteps(int beginIndex, int endIndex, bool withSentences, out List<NcResultStepRow> rows)

Parameters

beginIndex int

The first index (inclusive); a negative one counts as 0.

endIndex int

The index past the last (exclusive); at or below the first, the window is empty.

withSentences bool

Whether to rebuild the steps' sentence snapshots (FindMachiningSteps(int, int, bool)).

rows List<NcResultStepRow>

The narrow rows of the window, by step index; empty for an empty window.

Returns

List<MachiningStepRecord>

The records, by step index.

Exceptions

InvalidDataException

A chunk, payload or pooled matrix the window reads is not what this build reads.

ObjectDisposedException

The reader was disposed, the window empty or not.

FindPieceAddresses(int, int, int)

Internal Use Only (the NC play result review). Finds the pieces whose sentence begins in one file index (as FindPieceIds(int, int) takes it) at a line of [lineBegin, lineEnd): the page of line marks a source panel shows, read in one query on the address index instead of one a line, each piece's sentence index off its index row, no chunk decoded. The addresses come by line, then by piece id (a line with several pieces – a loop, a recording that went on across a reset – answers several), and only of pieces whose chunk the file holds; empty for a file index or a range the file does not know.

public List<NcResultPieceAddress> FindPieceAddresses(int fileIndex, int lineBegin, int lineEnd)

Parameters

fileIndex int

The file index.

lineBegin int

The first 0-based line index (inclusive); a negative one counts as 0.

lineEnd int

The line index past the last (exclusive); at or below the first, the range is empty.

Returns

List<NcResultPieceAddress>

The pieces' addresses, by line then by id.

Exceptions

ObjectDisposedException

The reader was disposed, the range empty or not.

FindPieceIds(int, int)

Internal Use Only (the NC play result review). Finds the ids of the pieces whose sentence begins at a line of one file index (one entry or control-flow jump into a source file, as NcFiles lists them), the 0-based line index: the address the host's source panels key their pieces by. The ids come by id, and only of pieces whose chunk the file holds; empty for an address the file does not know. One query on the address index.

public List<int> FindPieceIds(int fileIndex, int lineIndex)

Parameters

fileIndex int

The file index.

lineIndex int

The 0-based line index.

Returns

List<int>

The piece ids, ascending.

Exceptions

ObjectDisposedException

The reader was disposed.

FindPieceIds(string, int)

Finds the ids of the pieces whose sentence begins at a line of a source file: the file's path as the sentences record it (compared ordinally, not normalised), the 0-based line index. A path has a file index for every entry and every control-flow jump into it, so a line can answer several pieces (a loop, a subprogram); the ids come by id, and only of pieces whose chunk the file holds. Empty for a path or a line the file does not know. One query, whose cost grows with the path's file indices; a piece is found under the path first recorded for its file index (NcFiles).

public List<int> FindPieceIds(string filePath, int lineIndex)

Parameters

filePath string

The source file's path.

lineIndex int

The 0-based line index.

Returns

List<int>

The piece ids, ascending.

Exceptions

ArgumentNullException

filePath is null.

ObjectDisposedException

The reader was disposed.

FindStepBriefs(int, int)

Reads the briefs of the steps whose index is in [beginIndex, endIndex), by index, each as TryGetStepBrief(int, out StepBrief) reads it; a step without a brief record is skipped, a brief chunk the file does not hold skipped whole. Each brief chunk the window crosses is decoded once. The list holds the whole window: a scan reads a window at a time.

public List<StepBrief> FindStepBriefs(int beginIndex, int endIndex)

Parameters

beginIndex int

The first index (inclusive); a negative one counts as 0.

endIndex int

The index past the last (exclusive); at or below the first, the window is empty.

Returns

List<StepBrief>

The briefs, by step index.

Exceptions

InvalidDataException

A brief chunk or record in the window is not what this build reads.

ObjectDisposedException

The reader was disposed, the window empty or not.

FindStepRows(int, int)

Internal Use Only (the NC play result review). Reads the narrow rows of the steps whose index is in [beginIndex, endIndex), by index, without decoding a chunk – one range query, each row as TryGetStepRow(int, out NcResultStepRow) reads it; a step without a row is skipped. A walk that wants the rows and the records of one window reads both in one query with FindMachiningSteps(int, int, bool, out List<NcResultStepRow>).

public List<NcResultStepRow> FindStepRows(int beginIndex, int endIndex)

Parameters

beginIndex int

The first index (inclusive); a negative one counts as 0.

endIndex int

The index past the last (exclusive); at or below the first, the window is empty.

Returns

List<NcResultStepRow>

The rows, by step index.

Exceptions

ObjectDisposedException

The reader was disposed, the window empty or not.

ReadNodeAttachments()

Internal Use Only (the NC play result review, P5). The finished stock's node map, whole: index i holds the native attachment pointer the stock's nodes carry for strip position i in the finish.wct (AddNodeAttachments(ReadOnlySpan<long>)), 0 for a position without one; the array ends at the last position with a key. Null for a file that holds no map: a schema version-1 file, a recording without a stock, one whose map could not be written, or one with no strip position and no step (its keys could pair with nothing). Read chunk by chunk outside the reader's caches (a one-time read at a review's open), under the reader's lock.

public long[] ReadNodeAttachments()

Returns

long[]

The keys by strip position index, or null.

Exceptions

InvalidDataException

A node attachment chunk is not what this build reads, or a slot's payload is short, or the chunks reach past the int range or more than one bin past the last strip position or step the file holds.

ObjectDisposedException

The reader was disposed.

TryGetMachiningStep(int, out MachiningStepRecord)

Reads a step's record: its narrow row and its payload in the step chunk, rebuilt as the record the recorder took – the motion (MachineMotionStep(BinaryReader, ProgramZeroLegs, in mat4d_t, in mat4d_t)) on the program-zero holder of its two pooled matrices (steps of the same two matrices share the holder) with the pair the payload carries, or none, and a McValues array of its own; the removal scalars, the collided pairs, the measured time when the payload has one, and the snapshot of its sentence from the piece chunk when the row names a piece the file holds. The sentence is null when the step has no sentence, when the piece was never stored (a HardNc piece the recorder skips, one not written yet) or when its chunk never reached the file; the record's SentenceIndex is then -1, while the row's column still reads through TryGetStepRow(int, out NcResultStepRow). The snapshot is the object the piece's other records carry while its chunk is cached, and another object, equal in data, once the chunk has been evicted.

public bool TryGetMachiningStep(int stepIndex, out MachiningStepRecord step)

Parameters

stepIndex int

The step's index.

step MachiningStepRecord

The record; null when the file has no row for the step or no chunk for the row.

Returns

bool

True when the file holds the step's row and its payload.

Exceptions

InvalidDataException

The step's chunk or payload, its piece's chunk or entry, or a pooled matrix its row names is not what this build reads.

ObjectDisposedException

The reader was disposed.

TryGetStepBlockText(int, out string)

Reads the block text of a step's sentence off its piece's index row, without decoding a chunk (a piece whose chunk never reached the file still answers): false when the file has no row for the step or the step names no piece the file holds a row for; true with a null text when the sentence had none.

public bool TryGetStepBlockText(int stepIndex, out string blockText)

Parameters

stepIndex int

The step's index.

blockText string

The block text; null when the sentence had none or the answer is false.

Returns

bool

True when the file holds the step's row and its piece's row.

Exceptions

ObjectDisposedException

The reader was disposed.

TryGetStepBrief(int, out StepBrief)

Reads a step's two briefs from the brief chunk: the force brief (null for the null record, the physics not run on the step) and the sequential physics state. The briefs are recorded apart from the step, so a step the file holds may have none: briefs the recorder never added, or a brief chunk that never reached the file.

public bool TryGetStepBrief(int stepIndex, out StepBrief brief)

Parameters

stepIndex int

The step's index.

brief StepBrief

The briefs; null when the file holds no brief record for the step.

Returns

bool

True when the file holds the step's brief record; false for a negative index too.

Exceptions

InvalidDataException

The brief chunk or the record is not what this build reads.

ObjectDisposedException

The reader was disposed.

TryGetStepRow(int, out NcResultStepRow)

Reads a step's narrow row: its queryable scalars, without decoding its chunk (the piece id and the sentence index -1 where the column is NULL; NcResultStepRow says what each holds). A row may be committed before its chunk, so true here does not promise a record from TryGetMachiningStep(int, out MachiningStepRecord).

public bool TryGetStepRow(int stepIndex, out NcResultStepRow row)

Parameters

stepIndex int

The step's index.

row NcResultStepRow

The row; default when the file has no row for the step.

Returns

bool

True when the file holds the step's row.

Exceptions

ObjectDisposedException

The reader was disposed.

TryGetSyntaxPiece(int, out SyntaxPieceRecord)

Reads a piece's record: the snapshot of its sentence (the object the piece's steps carry while the piece chunk is cached) and a copy of its compact JSON (empty, with HasJson false, for a piece stored without one).

public bool TryGetSyntaxPiece(int pieceId, out SyntaxPieceRecord piece)

Parameters

pieceId int

The piece's id.

piece SyntaxPieceRecord

The record; null when the file has no row for the id or no chunk for the row.

Returns

bool

True when the file holds the piece.

Exceptions

InvalidDataException

The piece chunk or the entry is not what this build reads.

ObjectDisposedException

The reader was disposed.