@scriptc/compiler 0.4.3 → 0.4.5

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

@@ -1,3 +1,4 @@
+import type { TargetCpu } from "../target-cpu.js";
 import { JsIcSites } from "../../ir/js-ic.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";
@@ -7,7 +8,7 @@ import type { IntegerCountedForLoop, IntegerPairedForLoop } from "../../ir/integ
 import { type SplitSpan, type StoredSplitSnapshot } from "./split-loops.js";
 import { type ChunkResult, EmitJournal } from "./emit-journal.js";
 import { type IntegerRange, type IntegerRanges } from "../../ir/integer-ranges.js";
-import { type Int32Slots } from "../../ir/int32-slots.js";
+import { type DynamicFieldStores, Int32Slots } from "../../ir/int32-slots.js";
 import { type FinalFields } from "../../ir/final-fields.js";
 import { type Int32Abi } from "./int32-abi.js";
 import { type Int32Local } from "./int32-locals.js";
@@ -33,7 +34,7 @@ import { ReferenceWrites, type Writes } from "./reference-writes.js";
 import { LlvmDebugInfo } from "./debug-info.js";
 import { StackCallbacks } from "./stack-callbacks.js";
 import { AmbientReceiverReaders } from "./constant-callbacks.js";
-import { type LentStringParameters, type StringSliceSnapshot } from "./string-slices.js";
+import { type LendingFacts, type StringSliceSnapshot } from "./string-slices.js";
 import { LazyCaptures } from "./lazy-captures.js";
 import { StackCaptures } from "./stack-captures.js";
 import { PublishWalkers } from "./publish.js";
@@ -46,6 +47,7 @@ import { LlWalkers } from "./walkers.js";
 import { NullableUnions } from "./nullable-unions.js";
 import { type InlineRcMode, type MapKeyAccess } from "./shapes.js";
 import type { ExprOf, LibCallExpr, LlStreamTypedRefAdapter, LlValue } from "./expr-context.js";
+import { type SpeculationContext, type SpeculativeValue } from "./speculative-integers.js";
 export { LlvmUnsupportedError } from "./unsupported.js";
 export interface LlArgPackAndTrampolinePrologue {
     definitions: string[];
@@ -78,15 +80,20 @@ export interface ForkPrimitives {
 export interface LlvmTargetOptions {
     /** C ABI target; omitted direct emission uses the host ABI. */
     targetTriple?: string;
+    /** Linux (glibc and musl) executables: functions reached only by direct
+     * calls propagate exceptions by unwinding the native stack (unwind-abi.ts). */
+    unwindAbi?: boolean;
+    /** Functions kept on the pending-flag ABI under `unwindAbi`: the ones an
+     * earlier emission found breaking its rules (UnwindAbiViolation). */
+    unwindExcluded?: ReadonlySet<string>;
     /** Emit the function bodies in this many contiguous ranges, each by its
-     * own emitter, and merge them in function order (emit-journal.ts). The
-     * output is the same as one emitter's. Debug builds (`debugSources`)
-     * emit in one emitter. */
+     * own emitter, and merge them in function order (emit-journal.ts, and
+     * debug-info.ts for debug metadata). The output is the same as one
+     * emitter's. */
     functionChunks?: number;
     /** Emit the function bodies of a large module on this many forked worker
      * processes at a time (emit-module.ts), forked with `forkPrimitives`. The
-     * output is the same as one emitter's. Debug builds (`debugSources`)
-     * emit in one emitter. */
+     * output is the same as one emitter's. */
     functionWorkers?: number;
     /** The host's process primitives, where it can fork (the native
      * compiler's). */
@@ -127,6 +134,10 @@ export interface LlvmTargetOptions {
      * store the instance'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
+     * runs on any x86-64 CPU. */
+    targetCpu?: TargetCpu;
 }
 /** LlvmTargetOptions.lowRegion for an executable: Linux targets without
  * sanitizers, whose address space below 32 GiB is free (ASan keeps its
@@ -134,6 +145,16 @@ export interface LlvmTargetOptions {
  * there). `platform` is a target platform (`linux`, `darwin`, `win32`,
  * `wasi`). */
 export declare function lowRegionTarget(platform: string, sanitize: boolean): boolean;
+/** The int32 slot analysis of one module and the inputs it read: the
+ * constructor's own analyses of that module, which LlEmitter takes over
+ * instead of repeating them when it emits the same module. */
+export interface Int32SlotAnalysis {
+    readonly mod: IrModule;
+    readonly nodeIndex: IrNodeIndex;
+    readonly initializerBindings: ReturnType<typeof findInitializerBindings>;
+    readonly dynamicStores: DynamicFieldStores;
+    readonly slots: Int32Slots;
+}
 export declare function emitLlvmModule(input: IrModule, options?: LlvmTargetOptions): string;
 /** emitLlvmModule's text as parts that concatenate to it, without the copy
  * that joining them makes: a large program's text is 150 MB. */
@@ -184,8 +205,9 @@ export declare class LlEmitter {
     readonly stringSlices: Map<string, StringSliceSnapshot>;
     /** Slices written into stack buffers (findScratchStringSlices). */
     scratchStringSlices: ReadonlySet<IrExpr>;
-    /** String parameters a caller may lend scratch slices to. */
-    lentStringParameters: LentStringParameters;
+    /** String parameters, record fields and record producers a caller may
+     * lend scratch slices to. */
+    lendingFacts: LendingFacts;
     localStackUnions: Map<string, {
         kind: "unionWrap";
         unionId: string;
@@ -367,6 +389,7 @@ export declare class LlEmitter {
     readonly emitLibraryIdentity: boolean;
     readonly runtimeAbiMarker: boolean;
     readonly detachedExit: boolean;
+    readonly targetCpu: TargetCpu | undefined;
     readonly wasmBoundsChecks: boolean;
     /** Interned string literals: UTF-8 text → { symbol, byte length } —
      * first-use order, the runtime ABI’s determinism discipline. */
@@ -472,7 +495,18 @@ export declare class LlEmitter {
     readonly checkedNarrows: CheckedNarrows;
     callArrayReads: Map<IrExpr, LocalArrayRead>;
     mapReadLifetimes: MapReadLifetimes;
+    /** Locals of the current function that hold a Map.get result as the
+     * entry's own reference (findMapReadBorrows, borrowableMapGet). */
+    borrowedMapGets: ReadonlySet<string>;
     readNumberMapWrites: ReadonlySet<IrExpr>;
+    /** The integer views of the current function's number Map/Set keys, by
+     * the key's double operand (noteNumberMapKey, map-number-lookup.ts). */
+    numberMapKeyIntegers: Map<string, {
+        name: string;
+        type: "i32" | "i64";
+        signed: boolean;
+        range: IntegerRange;
+    }>;
     /** The current function's fused string-key Map get-then-set pairs (map-entry-fusion.ts). */
     mapEntryFusion: MapEntryFusion | null;
     readonly callLifetimes: CallLifetimes;
@@ -542,6 +576,10 @@ export declare class LlEmitter {
     /** May-throw analysis (computeMayThrow): pending
      * checks are emitted only after calls that can actually raise. */
     readonly mayThrow: Set<string>;
+    /** The functions that propagate exceptions by unwinding (unwind-abi.ts). */
+    readonly unwindAbi: Set<string>;
+    /** Whether the function being emitted is one of unwindAbi. */
+    currentUnwindAbi: boolean;
     readonly indirectMayThrow: boolean;
     /** Worker programs: the functions that poll for termination on entry
      * (workerTerminationPolls); null outside worker programs. */
@@ -580,6 +618,20 @@ export declare class LlEmitter {
     /** Locals whose array literal emitStmts left for the `await Promise.all`
      * that reads them (deferredPromiseAllLocal). */
     private readonly deferredPromiseAllEntries;
+    /** Empty array literals that a capacity hint follows directly
+     * (reservedArrayLength), with that hint. Constructing the literal with
+     * the hinted capacity consumes the hint, which then emits nothing. */
+    readonly reservedArrayLengths: Map<IrExpr, {
+        kind: "arraySetLength";
+        arr: IrExpr;
+        length: IrExpr;
+        loc: SrcLoc;
+        pop?: boolean;
+        reserve?: boolean;
+    } & {
+        kind: "arraySetLength";
+    }>;
+    readonly consumedReserves: Set<IrStmt>;
     /** The promise a `return` emitted past its finally regions already
      * produced for its adopting await (borrowed from the return's parked
      * slot); that await takes it instead of evaluating its operand. */
@@ -647,6 +699,7 @@ export declare class LlEmitter {
      * statics and construct thunks assemble around the bodies. */
     readonly classObjs: Map<string, {
         nameSym: string;
+        baseNameSym: string | null;
     }>;
     private readonly unionFieldReadGroups;
     /** Preorder intervals of the runtime error classes under THIS module's
@@ -718,12 +771,20 @@ export declare class LlEmitter {
     streamingSplitsEnabled: boolean;
     readonly initializerBindings: ReturnType<typeof findInitializerBindings>;
     /** Whole-program int32 storage and parameter/result facts. */
-    readonly int32Slots: Int32Slots;
+    get int32Slots(): Int32Slots;
+    private int32SlotsValue;
+    /** The join of the int32 slot analysis a forked process computes
+     * (startInt32Slots). */
+    private int32SlotsJoin;
     /** The program has no runtime store into a checked-dynamic value
      * (dynamicFieldStores), so live views of classes and records never
      * commit back into their objects. Library builds keep their commits:
      * their values cross a native boundary. */
     readonly liveViewsReadOnly: boolean;
+    /** The program freezes, seals or prevents extensions of untyped values
+     * (IrModule.untypedIntegrity): the commits of class views store the
+     * view's integrity state in the instance's integrity word. */
+    readonly untypedIntegrity: boolean;
     /** Functions whose direct calls use i32 parameters or results. */
     readonly int32Abis: ReadonlyMap<string, Int32Abi>;
     /** Pure number functions with speculative integer clones. */
@@ -764,6 +825,9 @@ export declare class LlEmitter {
     integerTempsEnabled: boolean;
     /** Speculative integer loops (speculative-integers.ts) run in this function. */
     speculativeLoopsEnabled: boolean;
+    /** False inside the copy of a versioned loop that runs when its guard
+     * fails: loops there get no speculative or int32 kind copies. */
+    loopCopiesEnabled: boolean;
     /** The fast copy of a speculative integer loop being emitted: its
      * integer-computed writes and where each resumes in the ordinary copy. */
     speculation: {
@@ -776,6 +840,8 @@ export declare class LlEmitter {
          * integer loop has neither. */
         bails?: string;
         ran?: string;
+        /** Writes that speculate a rewritten value (rewriteSpeculable). */
+        values?: ReadonlyMap<IrStmt, SpeculativeValue>;
     } | null;
     /** Speculative loop sites numbered so far in the module. */
     speculativeLoopSites: number;
@@ -784,6 +850,16 @@ export declare class LlEmitter {
         label: string;
         placed: boolean;
     }> | null;
+    /** The rewritten values of the writes `speculationResume` resumes at. */
+    speculationResumeValues: ReadonlyMap<IrStmt, SpeculativeValue> | null;
+    /** Hoisted speculative leaves numbered so far in the function being
+     * emitted (emitFunction resets it): a function's local names must not
+     * depend on which functions the same emitter emitted before it, since
+     * function workers each emit a share of the module. */
+    speculativeLeaves: number;
+    private readonly inlinableFunctions;
+    /** What speculative loop planning may assume here (SpeculationContext). */
+    speculationContext(): SpeculationContext;
     /** Run once at the top of the next loop copy's header
      * (`enterLoopHeader`): records the ordinary copy's header, or sends the
      * third copy's header there. */
@@ -825,9 +901,23 @@ export declare class LlEmitter {
      * (one-unit tests and switches, charAtUnitRead), with the charAt each
      * stands for: a loop version's proof for the charAt covers its read. */
     readonly charAtUnitReads: Map<IrExpr, IrExpr>;
+    /** String reads a loop version proved in bounds of a string's UTF-16
+     * units, with the units pointer to read (string-unit-versions.ts). */
+    stringUnitReads: ReadonlyMap<IrExpr | IrStmt, string>;
+    /** `length` reads of a loop version's string, with the i64 UTF-16
+     * length its guard took (bytes-loop-versions.ts). */
+    stringLengthReads: ReadonlyMap<IrExpr, string>;
     /** Worker programs: typed-array accesses whose views an enclosing version
      * guard proved thread-owned. */
     bytesOwned: ReadonlySet<IrExpr | IrStmt>;
+    /** The alias-scope attachment of each typed-array element read and write
+     * in the current loop version's fast copy (emitVersionedLoop), and the
+     * one the element access being emitted carries (bytesElementAlias). */
+    bytesAliasScopes: ReadonlyMap<IrExpr | IrStmt, string>;
+    bytesAccessScope: string;
+    /** Loop versions with alias scopes in the current function; it names
+     * their scopes. */
+    aliasScopedVersions: number;
     integerViews: Map<string, string>;
     /** Module globals the current function owns outright (initializer
      * bindings): their function-local slot, which stands in for the global. */
@@ -913,7 +1003,13 @@ 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);
+    constructor(mod: IrModule, options: LlvmTargetOptions, journal?: EmitJournal | null, int32Analysis?: Int32SlotAnalysis | null);
+    /** 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
+     * process computes it while the constructor runs the other analyses. */
+    private startInt32Slots;
+    private joinInt32Slots;
     /** The borrowed parameters of a hierarchy's vtable slot (empty: owned). */
     virtualSlotBorrowed(rootName: string, slotIndex: number): ReadonlySet<number>;
     /** Optimized emission: no debug-info (dev) posture. */
@@ -1201,12 +1297,31 @@ export declare class LlEmitter {
      * predecessors so the caller's remaining instructions stay well-formed;
      * LLVM deletes it. */
     emitAlwaysPendingUnwind(): void;
+    /** Emits `line`, a `call` of `callee`, and reports whether the call
+     * needs no pending check after it: a call of an unwinding-ABI function
+     * becomes an `invoke` whose landing pad runs this frame's unwind (the
+     * same releases and handler as emitPendingCheck's unwind path), and the
+     * normal path continues in a fresh block. Coroutine bodies keep plain
+     * calls (unwindAbiFunctions excludes their callees). */
+    emitDirectCall(line: string, callee: string): boolean;
+    /** Whether emitUnwind runs for a landing pad, whose unwind goes on with
+     * `resume` instead of raising again. */
+    private inLandingPad;
+    /** Whether the function being emitted has a landing pad (its definition
+     * needs the personality). */
+    usesLandingPads: boolean;
     /** A recursive function's entry check: below the running stack's guard,
      * throw Node's RangeError and unwind like any other pending exception. */
     emitStackCheck(): void;
     /** Whether the emitter follows this call with a pending test (the
      * conditions in expr-calls.ts). */
     private callTestsPending;
+    /** Whether `loop` needs a cancellation poll: in a worker program, unless
+     * the loop already runs a pending test on every iteration, which observes
+     * a terminate request itself (a separate poll would only add work). */
+    workerLoopPolls(loop: Extract<IrStmt, {
+        kind: "while" | "doWhile" | "for" | "forOf";
+    }>): boolean;
     workerLoopBudget(loop: Extract<IrStmt, {
         kind: "while" | "doWhile" | "for" | "forOf";
     }>): string | null;
@@ -1237,6 +1352,11 @@ export declare class LlEmitter {
      * the body repeats on every iteration (a typed array's length, for one)
      * stay in the loop. */
     emitWorkerLoopCheck(slot: string | null): void;
+    /** The cancellation poll itself. Calls and throwing operations retain
+     * their own checks. Loops amortize this extra poll across bounded
+     * batches of iterations so scalar work does not cross the runtime ABI on
+     * every iteration. */
+    emitWorkerPoll(): void;
     /** Moves an already-evaluated value into the runtime's exception cell —
      * the `throw` statement's kind dispatch (stmts.ts's), shared with
      * every synthetic thrower. Ownership of a refcounted payload must have
@@ -1252,6 +1372,10 @@ export declare class LlEmitter {
     private truthyOf;
     /** A union value's tag (i32): the box's tag word, or the NULL test of a
      * nullable union's pointer. */
+    /** A box's tag and payload words are written only where the box is
+     * built (runtime constructors and untagged stack stores), so their loads
+     * carry their own alias tags: element and field stores cannot change
+     * them, and loops keep them hoisted. */
     unionTag(uName: string, unionId: string): string;
     /** Guard for helpers that build or read a union's `%ScrUnion` box
      * directly (library-shaped unions with fixed arms): a nullable union
@@ -1278,6 +1402,8 @@ export declare class LlEmitter {
      * the scr_union_new_* dispatch of unionWrap and the wrap-into-join
      * sites (shift). */
     unionNewOwned(unionId: string, tag: number, v: LlValue): string;
+    /** `name` and every class whose membership interval falls in its own. */
+    private classSubtypes;
     classMetaOf(className: string): LlClassMeta;
     /** The field-slot pointer of a class member: rc at 0, the vtable word at
      * 1 on hierarchy members, then the flattened field list. Runtime error
@@ -1357,6 +1483,10 @@ export declare class LlEmitter {
     matchBytesLoopVersion(s: IrStmt & {
         kind: "for" | "while";
     }, counted: IntegerCountedForLoop | null, paired?: IntegerPairedForLoop | null): ReturnType<typeof matchBytesLoopVersion>;
+    private unitSafe;
+    /** The functions a loop over a string's UTF-16 units may call, or null
+     * where emitted reads do not use the runtime's scan receiver. */
+    private unitSafeFunctions;
     /** The alias tag of a whole-slot load of a binding (module globals only). */
     slotAlias(id: string): string;
     binding(id: string): {
@@ -1462,6 +1592,7 @@ export declare class LlEmitter {
      * the range's order, and answers the rename of the range's text to this
      * emitter's numbered helpers. Ranges merge in function order. */
     mergeChunk(chunk: ChunkResult): (text: string) => string;
+    private functionNamed;
     /** Adds a content-named constant a chunk interned. Its symbol is this
      * emitter's own: a digest collision retries in first-use order, which a
      * chunk alone does not know. */
@@ -1895,7 +2026,7 @@ export declare class LlEmitter {
     emitBytesIndex(receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean): string;
     emitBytesData(receiver: string): string;
     emitBytesLength(elem: IrBytesElem, receiver: string, bytes: boolean): LlValue;
-    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean, owned?: boolean): LlValue;
+    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean, owned?: boolean, scope?: string): LlValue;
     emitToUint32(value: string, expr?: IrExpr, uint32?: string): string;
     /** Stores a number into its int32-stored local, when it is one. The
      * value is proven to be in the local's range, so its low 32 bits are the
@@ -1906,7 +2037,7 @@ export declare class LlEmitter {
      * as its incoming double, which is the same number. */
     int32LocalValue(localId: string, bits: string, type: IrType): LlValue;
     storeIntegerView(localId: string, value: LlValue, expr?: IrExpr): void;
-    emitBytesSet(elem: IrBytesElem, receiver: string, index: LlValue, value: LlValue, indexExpr?: IrExpr, expr?: IrExpr, inBounds?: boolean, owned?: boolean): void;
+    emitBytesSet(elem: IrBytesElem, receiver: string, index: LlValue, value: LlValue, indexExpr?: IrExpr, expr?: IrExpr, inBounds?: boolean, owned?: boolean, scope?: string): void;
     emitBytesIntrinsic(e: IrExpr & {
         kind: "bytesIntrinsic";
     }): LlValue;