@scriptc/compiler 0.4.6 → 0.4.7

package/dist/frontend/lowering/unit-journal.d.ts

@@ -1,9 +1,26 @@
 import type { IrFunction } from "../../ir/ir.js";
-/** A function as records hold it, or null when it does not encode. Every
- * function a record holds goes through this pair. */
+/** A function as table entries hold it, or null when it does not encode.
+ * Every function an entry holds goes through this pair. */
 export declare function encodeUnitFunction(fn: IrFunction): string | null;
-/** A function from its record encoding (encodeUnitFunction). */
+/** A function from its entry encoding (encodeUnitFunction). */
 export declare function decodeUnitFunction(text: string): IrFunction;
+/** A unit's function as its record holds it: the binary IR encoding, or
+ * JSON (encodeUnitFunction) when an object in it would not read back with
+ * its own key order, which frontend passes and the IR's text depend on. */
+export type RecordFunction = string | Uint8Array;
+/** `fn` as a record holds it, or null when it does not encode. A binary
+ * encoding comes with its strings and the files its fields named `file`
+ * hold (encodeFunctionStrings). */
+export declare function encodeRecordFunction(fn: IrFunction): {
+    readonly fn: RecordFunction;
+    readonly strings: readonly string[] | null;
+    readonly files: readonly string[] | null;
+} | null;
+/** A function from its record encoding (encodeRecordFunction). */
+export declare function decodeRecordFunction(fn: RecordFunction): IrFunction;
+/** `record` as a JSON line, with a binary function in base64, marked when
+ * it was `applied` from an earlier build's store. */
+export declare function recordLine(record: UnitRecord, applied?: boolean): string;
 /** A call a unit made while it lowered, which applying its record makes
  * again. */
 export interface JournalEvent {
@@ -20,9 +37,9 @@ export interface JournalEvent {
 /** One unit's record. */
 export interface UnitRecord {
     readonly name: string;
-    /** The unit's function in the compact IR encoding, or null when the unit
+    /** The unit's function (encodeRecordFunction), or null when the unit
      * lowered to nothing. */
-    readonly fn: string | null;
+    readonly fn: RecordFunction | null;
     /** True when the unit's lowering ended in a poison: its diagnostics and
      * the edges it fired before poisoning stay, and it has no function. */
     readonly poisoned: boolean;
@@ -48,6 +65,12 @@ export interface JournalTable {
     readonly entries?: (from: number) => string[] | null;
     /** Adds the encoded entries whose keys this process's table lacks. */
     readonly apply?: (entries: readonly string[]) => void;
+    /** Whether every encoded entry whose key this process's table holds
+     * holds the same value there. */
+    readonly agrees?: (entries: readonly string[]) => boolean;
+    /** Whether this process's table holds an entry under the encoded entry's
+     * key. */
+    readonly holds?: (entry: string) => boolean;
     /** A digest of the content of the entry under `key`, when the table
      * holds one before position `before`; null otherwise. */
     readonly digest?: (key: string, before: number) => string | null;
@@ -70,10 +93,12 @@ export interface HeldContents {
 }
 /** A digest of `text`: its length and two 32-bit FNV-1a hashes. */
 export declare function contentDigest(text: string): string;
-/** The names quoted in JSON `texts`, unescaped only as far as their
- * delimiting quotes: the strings that start with `%` (helper, lifted and
- * IR data names) and union ids (`u` and 12 hex digits), which the tables
- * a unit reads and changes are keyed by. */
+/** Adds to `out` the names among `strings`: the strings that start with `%`
+ * (helper, lifted and IR data names) and union ids (`u` and 12 hex digits),
+ * which the tables a unit reads and changes are keyed by. */
+export declare function namedStrings(strings: Iterable<string>, out: Set<string>): void;
+/** The names (namedStrings) quoted in JSON `texts`, unescaped only as far
+ * as their delimiting quotes. */
 export declare function quotedStrings(texts: readonly string[]): Set<string>;
 /** A field a unit's lowering must leave as it found it (fixedScalar), or a
  * flag it may set, which applying its record sets too (flagScalar). */
@@ -122,6 +147,10 @@ export interface WaveHost {
     };
     /** Whether `event` names something this process holds. */
     resolves(event: JournalEvent): boolean;
+    /** Keeps a unit's function from its record and makes the record's events
+     * again, under the unit's generic demand owner and declared-order
+     * priority. */
+    keep(name: string, fn: IrFunction | null, events: readonly JournalEvent[]): void;
 }
 /** Whether reachable emit records its units (SCRIPTC_LOWER_JOURNAL=serial,
  * or a SCRIPTC_LOWER_JOURNAL_DUMP directory). */
@@ -141,8 +170,42 @@ export interface WaveStats {
     unrecorded: number;
     /** Per table, field or check, the units it left without a record. */
     reasons: Record<string, number>;
+    /** Units whose stored record applied in place of lowering them
+     * (unit-reuse.ts). */
+    applied: number;
+    /** Time taking and checking the tables' contents, finding stored records,
+     * applying them, and lowering and recording units, in milliseconds. */
+    holdMs: number;
+    storedMs: number;
+    applyMs: number;
+    recordMs: number;
+    /** Of recordMs, the time the units' lowering took, and the time a
+     * recorded unit's results took to be replaced by its record's. */
+    lowerMs: number;
+    replaceMs: number;
 }
 export declare function waveStats(): WaveStats;
+/** A wave's use of the records an earlier build stored (unit-reuse.ts). */
+/** A record an earlier build stored, with its function, which the store
+ * can keep apart from the record (`record.fn` is null then). */
+export interface StoredRecord {
+    readonly record: UnitRecord;
+    fn(): IrFunction | null;
+}
+export interface WaveReuse {
+    /** The stored record of `name`, when the unit can apply it. */
+    stored(name: string): StoredRecord | null;
+    /** Whether units with a stored record lower and are checked against it
+     * instead (SCRIPTC_INCR_VERIFY=1). */
+    readonly verify: boolean;
+    /** Checks the record a unit lowered to against its stored one, whose
+     * entries the tables did not hold yet at the unit's turn are `pending`. */
+    check(name: string, stored: StoredRecord, pending: Readonly<Record<string, readonly string[]>>, unit: RecordedUnit): void;
+    /** Notes the record a unit lowered to, with the files its binary
+     * function names (RecordedUnit.files), or the stored record it applied
+     * (`files` null). */
+    note(name: string, record: UnitRecord | null, applied: boolean, files: readonly string[] | null): void;
+}
 /** What lowering one unit with its events recording produced. */
 export interface RecordedUnit {
     /** The unit's record, or null when the unit has none. */
@@ -153,6 +216,11 @@ export interface RecordedUnit {
     readonly fn: IrFunction | null;
     /** Each table's size before the unit. */
     readonly before: readonly number[];
+    /** The time the unit's lowering took. */
+    readonly lowerMs: number;
+    /** The files the fields named `file` in the record's function hold, when
+     * the function is binary. */
+    readonly files: readonly string[] | null;
 }
 /** Lowers `name` with its events recording, and makes its record. The unit
  * has a record when every table that grew is appendable and holds the
@@ -160,15 +228,55 @@ export interface RecordedUnit {
  * statement totals grew by the recorded statements alone, no diagnostic was
  * emitted, every event resolves and the function encodes. */
 export declare function recordUnit(host: WaveHost, name: string, contents?: readonly (HeldContents | null)[] | null): RecordedUnit;
-/** Lowers `wave` with every unit recorded. A unit with a record keeps the
- * results its record carries: the entries it added are taken out of their
- * tables and added again from the record, and its function is the one
- * decoded from the record. A unit without one keeps what lowering made.
+/** Lowers `wave` with every unit recorded. Without `reuse`, a unit with a
+ * record keeps the results its record carries: the entries it added are
+ * taken out of their tables and added again from the record, and its
+ * function is the one decoded from the record. Otherwise, and for a unit
+ * without a record, a unit keeps what lowering made.
  * Throws an InternalCompilerError when a unit changed the content of an
  * entry a table held when the unit started (JournalTable.contents), which
  * no record carries.
- * `lines`, when given, receives each unit's record as a JSON line. */
-export declare function lowerWaveRecorded(host: WaveHost, wave: readonly string[], stats: WaveStats, lines?: string[] | null): void;
+ * `lines`, when given, receives each unit's record as a JSON line. A unit
+ * whose stored record `reuse` gives applies it, and lowers when it does not
+ * apply. With `held`, the wave continues the content the waves before it
+ * left (HeldTables), and the check waits for HeldTables.check. */
+export declare function lowerWaveRecorded(host: WaveHost, wave: readonly string[], stats: WaveStats, lines?: string[] | null, reuse?: WaveReuse | null, held?: HeldTables | null): void;
+/** The content of the tables' entries that recorded units start from
+ * (JournalTable.contents): units keep the content of the entries the
+ * tables held when they started, since a record carries a unit's new
+ * entries, not changes to others. Applying a stored record only adds
+ * entries, so the content is taken when the first unit lowers, and not at
+ * all when none does. Consecutive waves with nothing but checker prefetches
+ * between them share one: the content a wave leaves, as the check finds it,
+ * is the content the next one starts with. */
+export declare class HeldTables {
+    private readonly tables;
+    private readonly stats;
+    private contents;
+    constructor(tables: readonly JournalTable[], stats: WaveStats);
+    /** The held content, taken now when it was not yet. */
+    take(): (HeldContents | null)[];
+    /** Adds the entries past the held ones, when the content is taken. */
+    extendTaken(): void;
+    /** Throws an InternalCompilerError when an entry a table held changed in
+     * place since the content was taken, other than by the units that keep
+     * their changes (HeldContents.refresh). */
+    check(): void;
+}
+/** Applies `record` in place of lowering its unit, at the unit's turn, or
+ * returns why the unit has to lower instead. A record applies when every
+ * entry it adds agrees with what the tables hold, it names only known
+ * tables, every event resolves and every entry it reads is held with the
+ * same content. Applying adds its entries, keeps its function (`stored`'s,
+ * when the store keeps it apart from the record) and makes its events
+ * again. */
+export declare function applyRecord(host: WaveHost, record: UnitRecord, stored?: () => IrFunction | null): string[];
+/** The entries `record` adds that the tables do not hold yet, by table
+ * name: what applying it would add at its unit's turn. */
+export declare function pendingEntries(host: WaveHost, record: UnitRecord): Record<string, readonly string[]>;
+/** Why `record` does not apply at its unit's turn (applyRecord), or no
+ * reasons when it does. */
+export declare function recordApplies(host: WaveHost, record: UnitRecord): string[];
 /** An appendable table over a Map from strings to strings, such as helper
  * names by key. */
 export declare function mapTable(name: string, map: Map<string, string>): JournalTable;
@@ -181,8 +289,11 @@ export declare function irDataTable<V>(name: string, map: Map<string, V>): Journ
 /** An appendable table over a Map from strings to values that `encode`
  * writes, or answers null for, and `decode` reads back. An entry is its key
  * as a JSON string, a line break and its value: a JSON string holds no line
- * break. A value that does not encode leaves its unit without a record. */
-export declare function codecTable<V>(name: string, map: Map<string, V>, encode: (value: V) => string | null, decode: (text: string) => V, nameOf?: ((value: V) => string) | null): JournalTable;
+ * break. A value that does not encode leaves its unit without a record.
+ * `content` is what held contents compare (JournalTable.contents): the
+ * encoding, or the value itself for a table of strings or numbers, which
+ * only change by being replaced. */
+export declare function codecTable<V>(name: string, map: Map<string, V>, encode: (value: V) => string | null, decode: (text: string) => V, nameOf?: ((value: V) => string) | null, content?: (value: V) => string | number | null): JournalTable;
 /** An appendable table over a Set of strings. */
 export declare function setTable(name: string, set: Set<string>): JournalTable;
 /** An appendable list of functions this process holds one of per name. A