@scriptc/compiler 0.3.2 → 0.3.4

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

@@ -1,3 +1,4 @@
+import { type ArraySearchKind } from "./array-search.js";
 import type { IrBytesElem, IrExpr, IrFfiImport, IrFunction, IrLocal, IrModule, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
 import { type SplitSpan } from "./split-loops.js";
 import { type IntegerRanges } from "../../ir/integer-ranges.js";
@@ -10,6 +11,7 @@ import { type CallLifetimes } from "./call-lifetimes.js";
 import { type UnionSources } from "./local-union-storage.js";
 import { BlockBuilder } from "./blocks.js";
 import { NullableRefFields, type NullableRefField } from "./nullable-fields.js";
+import { InlineUnionFields } from "./inline-unions.js";
 import { OptionalArrayReads, type LocalArrayRead } from "./local-array-reads.js";
 import { CheckedNarrows } from "./checked-narrows.js";
 import { type MapReadLifetimes } from "./map-read-lifetimes.js";
@@ -19,11 +21,12 @@ import { StackCallbacks } from "./stack-callbacks.js";
 import { AmbientReceiverReaders } from "./constant-callbacks.js";
 import { type StringSliceSnapshot } from "./string-slices.js";
 import { type PublishedTypes } from "../publication.js";
+import { type BytesThunkValue } from "./expr-stream-callbacks.js";
 import { type LlClassMeta } from "./classes.js";
 import { LlDyn, type DynHost } from "./dyn.js";
 import { LlWalkers } from "./walkers.js";
 import { NullableUnions } from "./nullable-unions.js";
-import { type MapKeyAccess } from "./shapes.js";
+import { type InlineRcMode, type MapKeyAccess } from "./shapes.js";
 import type { ExprOf, LibCallExpr, LlStreamTypedRefAdapter, LlValue } from "./expr-context.js";
 export { LlvmUnsupportedError } from "./unsupported.js";
 export interface LlvmTargetOptions {
@@ -39,16 +42,20 @@ export interface LlvmTargetOptions {
      * separate translation unit. Public/direct emission keeps them by default. */
     emitLibraryIdentity?: boolean;
     /** Program objects carry a strong reference to the matching runtime ABI
-     * marker so manual links against an incompatible runtime fail loudly. */
+     * marker so a manual link against an incompatible runtime fails. */
     runtimeAbiMarker?: boolean;
     /** Emit live-object audit notes in emitted new/free helpers. Only the
      * sanitized lane's SCR_RC_AUDIT runtime counts them; production plain
      * builds pass false so release/dev objects carry no empty calls.
      * Defaults to true for direct emission. */
     objectAudit?: boolean;
-    /** Emit retain/release fast paths inline (the `speed` posture). Off, every
-     * retain and release is a runtime call. */
-    inlineRc?: boolean;
+    /** Emit retain/release fast paths inline: `speed` for every family with a
+     * fast path, `release` for the string retain and the dyn retain and
+     * release (shapes.ts InlineRcMode). Off, every retain and release is a
+     * runtime call. */
+    inlineRc?: InlineRcMode;
+    /** Define the inline RC fast-path helpers `noinline` (sanitized builds). */
+    rcHelpersNoinline?: boolean;
     /** Define `scr_detached_exit` so the Linux runtime hands the address-space
      * teardown after `process.exit` to a helper process (`--detached-exit`).
      * Executables only; the runtime's weak default keeps it off. */
@@ -134,6 +141,8 @@ export declare class LlEmitter {
     private readonly unitInstances;
     /** unionId → symbol of the union's immortal ABSENT field-slot instance. */
     private readonly absentInstances;
+    /** The zeroed box an inline store reads for a NULL union dummy. */
+    private needsUnionNone;
     /** unionId → symbol of a flag set once a checked-dynamic cast caches one
      * of the union's boxes. A cached box is refreshed in place, possibly with
      * a tag that another union numbers apart, so it is never shared. */
@@ -185,6 +194,8 @@ export declare class LlEmitter {
     /** Inline RC fast-path helpers requested by call sites (shapes.ts); null
      * when inline RC is off. */
     private readonly rcHelpers;
+    private readonly rcMode;
+    private readonly rcHelpersNoinline;
     readonly fnByName: Map<string, IrFunction>;
     /** Empty literals that construct with inline slots (appended-array-literals.ts). */
     appendedArrayLiterals: ReadonlySet<IrExpr>;
@@ -204,6 +215,7 @@ export declare class LlEmitter {
     readonly checkedNarrows: CheckedNarrows;
     callArrayReads: Map<IrExpr, LocalArrayRead>;
     mapReadLifetimes: MapReadLifetimes;
+    readNumberMapWrites: ReadonlySet<IrExpr>;
     readonly callLifetimes: CallLifetimes;
     readonly constantCallbacks: Map<string, Map<string, string>>;
     currentConstantCallbacks: ReadonlyMap<string, string>;
@@ -292,6 +304,8 @@ export declare class LlEmitter {
      * typeKey → thunk symbol. */
     readonly resolveThunks: Map<string, string>;
     readonly resolveThunkDefs: string[];
+    /** Inline array searches used by the module (array-search.ts). */
+    readonly arraySearchKinds: Set<ArraySearchKind>;
     /** Typed-ref recipe constants by type key (lazy receivers). */
     readonly typedRefRecipes: Map<string, string>;
     /** ReadableStream.from adapters keep typed arrays by reference and box
@@ -305,6 +319,7 @@ export declare class LlEmitter {
     readonly dynPromiseAdapters: Map<string, string>;
     readonly unionsById: Map<string, IrUnionDef>;
     readonly nullableFields: NullableRefFields;
+    readonly inlineUnions: InlineUnionFields;
     /** Unions whose values are nullable arm pointers (nullable-unions.ts). */
     readonly nullableUnions: NullableUnions;
     /** The union table without nullable unions: the stack-box analyses. */
@@ -504,7 +519,7 @@ export declare class LlEmitter {
      * programs keep fibers too: their fiber epilogue owns context
      * termination (a stopping worker rejects and observes the promise), which
      * the fiberless wrapper does not reproduce. A missed suspension still
-     * cannot reorder silently: the runtime traps when a context parks while a
+     * cannot reorder execution undetected: the runtime traps when a context parks while a
      * fiberless body is on its stack. */
     private fiberlessAsyncFunctions;
     /** The spawn wrapper of a fiberless async function: runs the body on the
@@ -588,7 +603,7 @@ export declare class LlEmitter {
      * holding the ABSENT state surfaces as the ordinary undefined arm, so
      * absence never travels beyond its slot (a later `{ f: r.f }` is an
      * explicit, present property). */
-    loadRecordField(ptr: string, t: IrType): string;
+    loadRecordField(ptr: string, t: IrType, inline: boolean): string;
     declare(decl: string): void;
     needOom(): void;
     private currentFrame;
@@ -673,6 +688,11 @@ export declare class LlEmitter {
      * conditions in expr-calls.ts). */
     private callTestsPending;
     private workerLoopBudget;
+    /** The amortized cancellation poll, emitted on the loop's back edge (the
+     * continue target), after the body. A poll in the header would be a loop
+     * exit ahead of the body; LLVM then cannot rotate the loop, so loads that
+     * the body repeats on every iteration (a typed array's length, for one)
+     * stay in the loop. */
     private emitWorkerLoopCheck;
     /** Moves an already-evaluated value into the runtime's exception cell —
      * the `throw` statement's kind dispatch (stmts.ts's), shared with
@@ -692,7 +712,7 @@ export declare class LlEmitter {
     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
-     * reaching one is an emitter bug, never a silent miscompile. */
+     * reaching one is an emitter bug and throws InternalCompilerError. */
     requireBoxedUnion(unionId: string): void;
     /** The BORROWED payload pointer of a ref arm (scr_union_peek inlined —
      * the runtime's is a static inline); a nullable union is its payload. */
@@ -723,6 +743,7 @@ export declare class LlEmitter {
     classFieldPtr(objName: string, className: string, field: string): {
         ptr: string;
         type: IrType;
+        inline: boolean;
     };
     /** `o->vt->pre` — the dynamic class's preorder number (borrowed object;
      * the static class names which struct spelling carries the vt word). */
@@ -736,17 +757,35 @@ export declare class LlEmitter {
      * same offset on every target. Share one field-read block per matching
      * prefix; class variants retain their own concrete layout dispatch. */
     unionFieldGroups(def: IrUnionDef, field: string): number[][];
-    /** The field-slot pointer of a record member (rc header at index 0). */
+    /** The zeroed `%ScrUnion` constant (inline-unions.ts unionBoxBits). */
+    unionNoneRef(): string;
+    /** The field-slot pointer of a record member (rc header at index 0).
+     * `inline`: the slot stores a scalar union's tag and bits. */
     recordFieldPtr(objName: string, shapeId: string, field: string): {
         ptr: string;
         type: IrType;
+        inline: boolean;
     };
     /** The overflow map's slot pointer on an index-signature shape. */
     recordOvfPtr(objName: string, shapeId: string): string;
-    /** Loads a record field (i8-stored bools trunc to i1). */
-    loadField(ptr: string, t: IrType): string;
-    /** Stores a record field (i1 zext to the i8 storage). */
-    storeField(ptr: string, t: IrType, value: string): void;
+    /** Loads a record field (i8-stored bools trunc to i1). An inline union
+     * field answers a private stack box with the slot's own bits, ABSENT
+     * included: it may only be borrowed. */
+    loadField(ptr: string, t: IrType, inline: boolean): string;
+    /** A record field of this shape stores its scalar union inline. */
+    recordFieldInline(shapeId: string, field: string): boolean;
+    /** The value a field store writes: an inline union slot copies the tag
+     * and bits of a borrowed projection, so no box is built for it. */
+    emitFieldValue(value: IrExpr, inline: boolean): LlValue;
+    /** Overwrites a field with `v` (from emitFieldValue). A reference moves
+     * in, and the old value is released AFTER the field is overwritten. */
+    replaceField(ptr: string, type: IrType, inline: boolean, v: LlValue): void;
+    /** Stores `v` (from emitFieldValue) into a fresh field slot. */
+    initField(ptr: string, type: IrType, inline: boolean, v: LlValue): void;
+    /** Stores a record field (i1 zext to the i8 storage). An inline union
+     * field copies the tag and bits of the union value, which its owner
+     * keeps. */
+    storeField(ptr: string, t: IrType, value: string, inline: boolean): void;
     /** Reads an int32-specialized class field: the i32 slot is the value,
      * and its widening is the exact double every program observation sees. */
     loadInt32Field(ptr: string, type: IrType): LlValue;
@@ -832,6 +871,12 @@ export declare class LlEmitter {
     /** A fresh heap box (+1) for a SCALAR_UNION_RESULT pair of `type`; the
      * exception dummy (tag -1) answers NULL. */
     boxScalarUnion(pair: string, type: IrType): string;
+    /** A fresh heap box (+1) for an inline union field's value; the ABSENT
+     * state reads as the undefined arm. */
+    inlineFieldUnion(ptr: string, type: IrType): string;
+    /** boxScalarUnion over a separate tag and payload bits. Unit arms answer
+     * their immortal instances whatever the bits. */
+    boxScalarUnionBits(tag: string, bits: string, type: IrType): string;
     /** The i32 bits of a number proven an int32 (a direct call's i32
      * argument or an i32 result): its exact integer when the value carries
      * one, else the conversion the proof makes exact. */
@@ -979,6 +1024,10 @@ export declare class LlEmitter {
      * value, making the snapshot unique unless a real observable alias exists.
      */
     emitStringSelfConcatAssign(localId: string, left: IrExpr, suffix: IrExpr, retainForYield: boolean): LlValue;
+    /** The code of a one-argument `String.fromCharCode(c)` suffix, emitted, so
+     * `s += String.fromCharCode(c)` appends the character without building
+     * the one-character string; null for any other suffix. */
+    private emitSingleCharCode;
     /** `local = local + suffix` when the suffix cannot read or write the
      * local (an unboxed binding is only reachable through this function's own
      * expressions): reading the binding after the suffix gives the value the
@@ -993,6 +1042,12 @@ export declare class LlEmitter {
     emitRecordExpr(e: ExprOf<"fieldGet" | "recordGet" | "recordLit" | "recordClone" | "recordKeyGet" | "recordOvfKeys" | "recordOvfHas" | "recordHas" | "fieldAbsent">): LlValue;
     emitDynamicExpr(e: ExprOf<"dynFrom" | "dynCall" | "dynInvoke" | "dynArrLit" | "dynObjLit" | "unionWrap" | "unionNarrow" | "unionDisc" | "unionKeyGet" | "unionIsTag" | "dynKeyGet" | "dynHasKey" | "dynScalarEq" | "dynTest" | "unionEq" | "unionFuncEq" | "caughtTest" | "caughtCheck" | "caughtNarrow" | "caughtToDyn">): LlValue;
     emitIntrinsicExpr(e: ExprOf<"intrinsic">): LlValue;
+    /** InternTable's runtime calls (scr_itable.c). Table and entry handles
+     * are f64 values carrying pointer bits; entry values are 64-bit slots
+     * (double bits, a bool, or a pointer to an immortal value) that the
+     * table neither retains nor releases. Lookups and inserts of array keys
+     * throw a TypeError for keys longer than a table accepts. */
+    private emitInternTableIntrinsic;
     /** Lifetime regions in modules with lifetimeRegions (llvm/regions.ts).
      * Created with the class graph; null elsewhere. */
     private regions;
@@ -1039,6 +1094,9 @@ export declare class LlEmitter {
     /** True for union sources that emitReadReceiver can produce as a private
      * stack box with an independently owned payload (no heap union). */
     isStackUnionSource(e: IrExpr): boolean;
+    /** A read of a record or class field that stores its scalar union
+     * inline. */
+    inlineFieldGet(e: IrExpr): boolean;
     /** The nullable-pointer representation behind a union-typed class field
      * read, or null for every other expression. */
     nullableFieldGet(e: IrExpr): NullableRefField | null;
@@ -1074,6 +1132,8 @@ export declare class LlEmitter {
      * and projection-only parameters (callers may pass stack boxes). Such a
      * box must only be projected: never retained, released, or stored. */
     isStackUnionLocal(localId: string): boolean;
+    /** The instance of a capsule known to hold exactly this class (borrowed). */
+    emitExactCapsuleObject(value: IrExpr, type: IrType): LlValue;
     canBorrowReceiver(e: IrExpr): boolean;
     /** A reference held as one plain pointer that emitReadReceiver can read
      * without owning: class instances, records, arrays, strings and
@@ -1144,7 +1204,10 @@ export declare class LlEmitter {
     }): string;
     cryptoBytesThunkFor(cbT: IrType & {
         kind: "func";
-    }, arrayBuffer?: boolean): string;
+    }, arrayBuffer?: boolean, valueMode?: BytesThunkValue): string;
+    cryptoIntThunkFor(cbT: IrType & {
+        kind: "func";
+    }): string;
     zlibBytesThunkFor(cbT: IrType & {
         kind: "func";
     }): string;