@scriptc/compiler 0.4.6 → 0.4.8

package/dist/backend/llvm/emitter.d.ts

@@ -3,6 +3,7 @@ import type { FunctionLayout } from "./function-layout.js";
 import type { CompilationTiming } from "../../timing.js";
 import { type FrameEscapes } from "./frame-escapes.js";
 import { JsIcSites } from "../../ir/js-ic.js";
+import type { JsGroup, JsGroupPlan } from "../../ir/js-groups.js";
 import { type ArraySearchKind } from "./array-search.js";
 import type { IrBytesElem, IrExpr, IrFfiCallbackParam, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
 import { type RuntimeFeatures } from "../../ir/runtime-features.js";
@@ -22,6 +23,7 @@ import { type HeapCensus } from "./heap-census.js";
 import { findInitializerBindings } from "../../ir/initializer-bindings.js";
 import { type ConstantNumericTable } from "../../ir/constant-tables.js";
 import { type FfiCallbackAdapter } from "../ffi-callbacks.js";
+import { type CpuCopies } from "./cpu-dispatch.js";
 import { type CallLifetimes } from "./call-lifetimes.js";
 import { type StackObjectField } from "./stack-objects.js";
 import { type LocalUnionStorageProof, type LocalUnionStorage, type UnionSources } from "./local-union-storage.js";
@@ -33,6 +35,7 @@ import { CheckedNarrows } from "./checked-narrows.js";
 import { type ArrayAccess } from "./dense-array-access.js";
 import { type MapReadLifetimes } from "./map-read-lifetimes.js";
 import { type MapEntryFusion } from "./map-entry-fusion.js";
+import { type RecordEntryFusion } from "./record-entry-fusion.js";
 import { type WalkBorrowHost } from "./walk-borrows.js";
 import { IrNodeIndex } from "../../ir/node-index.js";
 import { ReferenceEffects } from "./reference-effects.js";
@@ -50,7 +53,7 @@ import { type LlClassMeta, type LlInlineTail } from "./classes.js";
 import { LifetimeRegions } from "./regions.js";
 import { type ArenaPlan } from "./arenas.js";
 import { type Node } from "./region-ir.js";
-import { LlDyn, type DynHost } from "./dyn.js";
+import { LlDyn, type DynHost, type JsEntryClosure } from "./dyn.js";
 import { LlWalkers } from "./walkers.js";
 import { NullableUnions } from "./nullable-unions.js";
 import { type InlineRcMode, type MapKeyAccess } from "./shapes.js";
@@ -167,10 +170,12 @@ export interface LlvmTargetOptions {
     /** Translated WebAssembly memories check bounds explicitly instead of
      * relying on guard pages (wasm-modules.ts wasmBoundsChecks). */
     wasmBoundsChecks?: boolean;
-    /** The executable can reserve its program-lifetime region below 32 GiB
-     * (lowRegionTarget): fields that refer to compact class instances then
-     * store the instance's address over 8 in 32 bits (classes.ts
-     * compactRefLoadLines). Elsewhere they keep 8-byte pointers. */
+    /** The executable can reserve the allocator's window, which holds its
+     * program-lifetime region, below 32 GiB (lowRegionTarget): compact class
+     * fields that refer to compact class instances, or to arrays, maps, sets
+     * and class instances in the window, then store the object's address over
+     * 8 in 32 bits (classes.ts compactRefLoadLines). Elsewhere they keep 8-byte
+     * pointers. */
     lowRegion?: boolean;
     /** The x86-64 level the program's code may require (`--target-cpu`):
      * every emitted function carries it as its `target-cpu`. Unset, code
@@ -211,6 +216,9 @@ export declare function llStrBytes(text: string): string;
  * to its next suspension, which returns to the caller, and the body's own
  * bookkeeping calls do not suspend it. */
 export declare const SUSPENDS: RegExp;
+/** Whether `text` mentions a SUSPENDS entry point. The regex runs only on
+ * text that holds one of its prefixes, which most function bodies do not. */
+export declare function mentionsSuspension(text: string): boolean;
 /** Captured bindings (boxes a body declares or receives) from which a
  * function compiles without LLVM optimization (see boxSlotCount). */
 export declare const UNOPTIMIZED_BOX_SLOTS = 512;
@@ -236,6 +244,10 @@ export declare class LlEmitter {
     readonly mod: IrModule;
     /** Per-feature state (emitter-state.ts), indexed by each key's slot. */
     readonly moduleStates: unknown[];
+    /** The names of the functions that `versionLoopBoundParameters` versions
+     * for int32 loop bounds: the ones that keep their name and call the copy
+     * and the fallback. Computed on first use. */
+    int32Versioned: Set<string> | null;
     localArrayReads: Map<string, LocalArrayRead>;
     loopArrayBorrows: ReadonlySet<IrStmt>;
     scalarStringSlices: Map<string, {
@@ -316,7 +328,7 @@ export declare class LlEmitter {
     readonly fieldAliasTags: Map<string, number>;
     readonly fieldPointerTags: Map<string, number>;
     /** The field pointers (classFieldPtr) of this function whose fields hold
-     * 32-bit references to compact class instances (LlClassMeta.compressed):
+     * 32-bit references (LlClassMeta.compressed):
      * loadField/loadRef decode them and storeField/storeRef encode them. */
     readonly compressedFieldPtrs: Set<string>;
     /** Compact class instances live in the program-lifetime region below
@@ -324,6 +336,12 @@ export declare class LlEmitter {
      * classes): main reserves it before compiled code runs (scr_plr_init), and
      * fields and arrays of compactRefType hold 32-bit references. */
     compactRegion: boolean;
+    /** A compact class has a field holding an array, a map, a set or a heap
+     * instance (windowRefType), so a reference to it is a 32-bit address of
+     * the allocator's window: main requires the window to serve every
+     * reference block (scr_sa_require_window), and ends the process when it
+     * cannot, rather than hand out an address a field would truncate. */
+    windowRefs: boolean;
     /** Native class fields with different property names cannot occupy the
      * same slot of one object. Inherited views of the same property share a
      * tag. Array storage has its own disjoint categories; untagged runtime
@@ -443,6 +461,9 @@ export declare class LlEmitter {
     readonly sanitizeAttributes: boolean;
     /** LlvmTargetOptions.cpuDispatch, where it applies. */
     readonly cpuDispatch: boolean;
+    /** How the program's functions are copied (cpu-dispatch.ts): for runtime
+     * dispatch, for an x86-64-v3 `targetCpu` ("target"), or not at all. */
+    readonly cpuCopies: CpuCopies | null;
     readonly wasmBoundsChecks: boolean;
     /** Interned string literals: UTF-8 text → { symbol, byte length } —
      * first-use order, the runtime ABI’s determinism discipline. */
@@ -540,6 +561,10 @@ export declare class LlEmitter {
     private readonly rcMode;
     private readonly rcHelpersNoinline;
     readonly fnByName: Map<string, IrFunction>;
+    /** Whether some closure has a jsval body (IrFunction.jsEntry): the
+     * dynamic tier's dynCall and dynInvoke sites then call a function value's
+     * jsval entry when it has one. */
+    jsEntries: boolean;
     /** Empty literals that construct with inline slots (appended-array-literals.ts). */
     appendedArrayLiterals: ReadonlySet<IrExpr>;
     /** Emitted LLVM text of every IR function body, by function name: the
@@ -572,6 +597,8 @@ export declare class LlEmitter {
     }>;
     /** The current function's fused string-key Map get-then-set pairs (map-entry-fusion.ts). */
     mapEntryFusion: MapEntryFusion | null;
+    /** The current function's fused record get-then-set pairs (record-entry-fusion.ts). */
+    recordEntryFusion: RecordEntryFusion | null;
     readonly callLifetimes: CallLifetimes;
     /** The locals whose value never leaves its frame (frame-escapes.ts), for
      * class instances with reference fields in frame storage. */
@@ -659,6 +686,9 @@ export declare class LlEmitter {
     /** Static types whose values can be published (@scriptc/threads): their
      * stores carry the frozen-object guard. Null without publish calls. */
     readonly publishedTypes: PublishedTypes | null;
+    /** Constructor stores that write a field's first value (immutability.ts
+     * computeConstructionFacts): they store without releasing an old value. */
+    readonly freshFieldStores: ReadonlySet<IrStmt>;
     /** Construction-only class and record fields (immutability.ts); null
      * where the facts are disabled. */
     private readonly immutableFields;
@@ -731,6 +761,9 @@ export declare class LlEmitter {
     readonly arraySearchKinds: Set<ArraySearchKind>;
     /** Typed-ref recipe constants by type key (lazy receivers). */
     readonly typedRefRecipes: Map<string, string>;
+    /** The module links narrowed record copies to their sources
+     * (IrModule.recordLinks). */
+    hasRecordLinks(): boolean;
     /** ReadableStream.from adapters keep typed arrays by reference and box
      * one current element per pull. */
     readonly streamFromArrayAdapters: Map<string, string>;
@@ -762,6 +795,21 @@ export declare class LlEmitter {
      * zero-initialized ScrJsIc per site (scr_js.h). */
     jsIcSiteCount: number;
     private jsIcSitesMemo;
+    /** Guard-group records of dynamic-tier functions (js-groups.ts): one
+     * zero-initialized ScrJsGroup per group, and the key arrays the probes
+     * read (scr_js.h). */
+    jsGroupCount: number;
+    private jsGroupKeysCount;
+    private readonly jsGroupKeysByName;
+    private readonly jsGroupKeysByText;
+    /** The guard of each group the function being emitted has entered: the
+     * entry value, and the position of the member that comes next. */
+    readonly groupRuns: Map<JsGroup, {
+        entry: string;
+        next: number;
+    }>;
+    /** The guard groups of the function being emitted (ir/js-groups.ts). */
+    jsGroupPlan: JsGroupPlan | null;
     /** The tier of the function being emitted. */
     currentTier: IrFunction["tier"];
     /** The class graph (buildClassGraph): preorder numbering, hierarchy
@@ -1112,7 +1160,7 @@ export declare class LlEmitter {
     private readonly journaled;
     /** Stack-trace mode: functions no capture can include (no frame push). */
     readonly unframedFunctions: ReadonlySet<string>;
-    constructor(mod: IrModule, options: LlvmTargetOptions, journal?: EmitJournal | null, int32Analysis?: Int32SlotAnalysis | null);
+    constructor(mod: IrModule, options: LlvmTargetOptions, journal?: EmitJournal | null, int32Analysis?: Int32SlotAnalysis | null, previousIndex?: IrNodeIndex);
     /** Computes the int32 slot analysis, or starts it on a forked process.
      * Dev builds read its result only near the end of the constructor
      * (int32Abis is empty with debug info), so for a large module the
@@ -1135,6 +1183,30 @@ export declare class LlEmitter {
     };
     emit(): string;
     emitParts(): string[];
+    /** The entry point and JavaScript name of each named function the
+     * module makes closures of: a declared function's wrapper (its interned
+     * closure's entry) or a lifted function's call target, with its
+     * displayName, else its sourceName. Function boxes without a static name
+     * look the closure's entry up in this table. */
+    private closureNameEntries;
+    private closureNameByEntry;
+    /** The declared functions `closureNames` lists by their wrapper. A scan
+     * sees closures in statements the emitter never reaches (a statement
+     * after a runtimeFence: the fence always jumps), so some of these names
+     * never enter `fnValues`; emitFnValueDefs defines their wrapper anyway,
+     * because the table's entry has to resolve. */
+    private readonly closureWrapperNames;
+    closureNames(): readonly {
+        entry: string;
+        name: string;
+    }[];
+    /** The entry point of a closure of `fnName` (closureNames). */
+    private closureEntry;
+    /** The name the closure-name table gives a closure made of `fnName`
+     * (null when it has none), which lets a box of a closure made at the site
+     * skip the table lookup; undefined for a function the module does not
+     * define. */
+    closureNameOf(fnName: string): string | null | undefined;
     /** The dispose-observer gates the emitted frees and record writers test
      * (alloc.ts): defined after every helper is emitted, because dynCheck
      * builders, JSON schemas and weak collection constructors are requested
@@ -1150,7 +1222,9 @@ export declare class LlEmitter {
     inlineRcTail(flushedDecls: ReadonlySet<string>): string[];
     /** Env-signature wrappers + interned immortal closures for declared
      * functions used as values (the runtime ABI’s sc_w_/sc_fc_ pair): every
-     * mention of `f` yields the same pointer, so `f === f` holds. */
+     * mention of `f` yields the same pointer, so `f === f` holds. The
+     * closure-name table's wrapper entries are included even when their
+     * closure was never emitted (see closureWrapperNames). */
     emitFnValueDefs(): string[];
     emitArgPackAndTrampolinePrologue(fn: IrFunction): LlArgPackAndTrampolinePrologue;
     /** Settles `promise` from a clean async body result `%r` (moved in). */
@@ -1334,6 +1408,10 @@ export declare class LlEmitter {
      * owner (a local or parameter slot, a callee's parameter, a return
      * value, a stack object, another temp). */
     toFrame(v: LlValue): void;
+    /** Whether a value of `type` is an instance of a tree class, whose retain
+     * is a no-op and whose release destroys the subtree: it has exactly one
+     * owner, so it may only be moved. */
+    isTreeValue(type: IrType): boolean;
     /** The retained (+1) read of a refcounted value — type-directed through
      * the `_v` table (immortals skip, exactly the C retain calls). */
     private retainCall;
@@ -1541,6 +1619,14 @@ export declare class LlEmitter {
      * `C | undefined` or `C | null` for a compact class `C`. `C | null |
      * undefined` is not: its null is a sentinel outside the region. */
     compactRefType(t: IrType, isCompact?: (className: string) => boolean): boolean;
+    /** Whether values of `t` are NULL or a refcounted object that lies in the
+     * allocator's window below 32 GiB, so that a compact class field of type
+     * `t` can store it as a 32-bit reference: an array, map or set, or an
+     * instance of a class that is not compact and that the program allocates
+     * (not the runtime's Error hierarchy, whose instances the runtime
+     * allocates), or one of these or `undefined`/`null` (NULL). Strings keep
+     * 8-byte pointers: literals lie in the executable's image. */
+    windowRefType(t: IrType, isCompact: (className: string) => boolean): boolean;
     /** Whether arrays of `elem` hold 32-bit references (SCR_ELEM_CREF). */
     compactArrayElem(elem: IrType): boolean;
     /** Loads the reference a field pointer addresses: a pointer, or the
@@ -1576,6 +1662,30 @@ export declare class LlEmitter {
         type: IrType;
         inline: boolean;
     };
+    /** Whether a value of `shapeId` may lack field `field`: a PARTIAL record
+     * view (record-views.ts) whose viewed record does not declare it. A field
+     * with no value representation (a unit type) keeps its slot lookup. */
+    partialFieldMissing(shapeId: string, field: string): boolean;
+    /** The viewed record's slot for `field` of a partial view, or NULL when
+     * that record does not declare the field. The caller has established that
+     * `obj` is a view. */
+    private partialViewSlot;
+    /** The boxed property a partial view keeps for a field its viewed record
+     * does not declare (NULL until something writes it). */
+    private partialViewExtra;
+    /** Reads field `field` of `obj` (shape `shapeId`) where a PARTIAL view may
+     * lack it. A view's present field reads through the viewed record's slot;
+     * a field that record does not declare reads the property a write left in
+     * the view's extra store, converted back to the field type; a field
+     * nothing wrote stops the program (the frontend's checked read throws its
+     * TypeError first). The answer is owned, like a checked conversion's. */
+    readPartialField(objName: string, shapeId: string, field: string, type: IrType): LlValue;
+    /** Stores `value` into field `field` of `obj` (shape `shapeId`) where a
+     * PARTIAL view may lack it, calling `storeAt` with the address to write.
+     * A field the viewed record does not declare is kept as a boxed property
+     * in the view's extra store, where reflection and a later read see it;
+     * `released` gives up a caller reference the frame does not own. */
+    storePartialField(objName: string, shapeId: string, field: string, type: IrType, value: LlValue, storeAt: (ptr: string) => void, released?: () => void): void;
     /** The overflow map's slot pointer on an index-signature shape. */
     recordOvfPtr(objName: string, shapeId: string): string;
     /** The pointer to ScrMap.flags of an index-signature record's overflow
@@ -1676,6 +1786,10 @@ export declare class LlEmitter {
      * the fiber eagerly to its first suspension and returns the promise);
      * generator bodies via theirs (which only ALLOCATES the suspended
      * fiber and returns the generator object). */
+    private jsEntryClosureList;
+    /** The closures with a jsval body (IrFunction.jsEntry), on targets with
+     * jsval words. */
+    jsEntryClosures(): readonly JsEntryClosure[];
     callTarget(fnName: string): string;
     /** Queue the current wasm coroutine and suspend it. The runtime decides
      * whether the promise waiter list or the ready FIFO owns the continuation;
@@ -2039,7 +2153,7 @@ export declare class LlEmitter {
      * is produced without a union box where the value is a wrap, and as a
      * retained payload of a borrowed box otherwise. Unlink-then-release like
      * every field store. */
-    emitNullableFieldStore(obj: string, className: string, field: string, nullable: NullableRefField, value: IrExpr): void;
+    emitNullableFieldStore(obj: string, className: string, field: string, nullable: NullableRefField, value: IrExpr, fresh: boolean): void;
     /** A union binding whose slot may hold a private stack box: stack locals
      * and projection-only parameters (callers may pass stack boxes). Such a
      * box must only be projected: never retained, released, or stored. */
@@ -2079,6 +2193,11 @@ export declare class LlEmitter {
     /** Group arenas (arenas.ts): the plan, the list slot of each root and
      * call region, and which locals' scopes drop which roots' arenas. */
     arenas: ArenaPlan | null;
+    /** The varRef reads the tree-class plan proved move a node out of its
+     * local (backend/tree-classes.ts). Each one emits its own last-use move:
+     * the source slot is nulled and the value taken without a retain, since
+     * a tree instance has no count to raise. */
+    private treeMoves;
     private arenaSlots;
     /** The frames emitStmtBody opens for whole statements (arenas only). */
     readonly statementFrames: Set<LlValue[]>;
@@ -2124,6 +2243,13 @@ export declare class LlEmitter {
     /** The helper classification of this module's inline-cache sites. */
     get jsIcSites(): JsIcSites;
     jsIcSite(): string;
+    /** A fresh guard-group record (js-groups.ts). */
+    jsGroup(): string;
+    /** The constant key array `keys` (string literal symbols) that a group's
+     * probe reads, shared by every group with the same keys. */
+    jsGroupKeys(keys: readonly string[]): string;
+    /** The key array of each of this module's guard groups, by name. */
+    get jsGroupKeysTable(): ReadonlyMap<string, readonly string[]>;
     /** A fresh read-site cache for one constant-key dyn read. */
     dynReadIcSite(): string;
     /** A fresh speculative loop site: the global that counts its bailing
@@ -2178,6 +2304,12 @@ export declare class LlEmitter {
     fsRenameThunkFor(cbT: IrType & {
         kind: "func";
     }): string;
+    watchNameThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
+    watchErrorThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
     cryptoBytesThunkFor(cbT: IrType & {
         kind: "func";
     }, arrayBuffer?: boolean, valueMode?: BytesThunkValue): string;
@@ -2237,7 +2369,7 @@ export declare class LlEmitter {
     emitRecordKeyGet(e: IrExpr & {
         kind: "recordKeyGet";
     }): LlValue;
-    keyedRecordReadInto(slot: string, join: string, objName: string, keyName: string, shapeId: string, resultType: IrType, overflowOnly: boolean, loc?: SrcLoc, missNaN?: boolean): void;
+    keyedRecordReadInto(slot: string, join: string, objName: string, keyName: string, shapeId: string, resultType: IrType, overflowOnly: boolean, loc?: SrcLoc, missNaN?: boolean, missInto?: (() => void) | null, read?: IrExpr | null): void;
     dynPromiseAdapter(inner: IrType): string;
     streamTypedRefCommitAdapter(t: IrType, snapshot: string): string;
     liveDynRefAdapter(t: IrType): LlStreamTypedRefAdapter;