@scriptc/compiler 0.3.0 → 0.3.1

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

@@ -2,6 +2,8 @@ import type { IrBytesElem, IrExpr, IrFfiImport, IrFunction, IrLocal, IrModule, I
 import { type SplitSpan } from "./split-loops.js";
 import { type IntegerRanges } from "../../ir/integer-ranges.js";
 import { type Int32Slots } from "../../ir/int32-slots.js";
+import { type Int32Abi } from "./int32-abi.js";
+import { type Int32Local } from "./int32-locals.js";
 import { type ConstantNumericTable } from "../../ir/constant-tables.js";
 import { type FfiCallbackAdapter } from "../ffi-callbacks.js";
 import { type CallLifetimes } from "./call-lifetimes.js";
@@ -83,6 +85,14 @@ export declare class LlEmitter {
      * indices; see ShapeHost.nextCycKind). */
     private cycKinds;
     readonly wasi: boolean;
+    /** Synchronous generator bodies compile to LLVM switched coroutines (a
+     * heap frame resumed by an ordinary call) instead of running on a fiber
+     * stack. Worker programs keep fibers (context shutdown unwinds suspended
+     * generator stacks) and so do debug builds (the debugger reads locals
+     * from the native frame). */
+    private stacklessGenerators;
+    /** Some function in the module is lowered as a coroutine. */
+    private usesCoroutines;
     /** The target lacks a rounding instruction at its baseline CPU (x86-64
      * before SSE4.1), so `llvm.trunc` would lower to a libm call: emit
      * truncation inline through an integer round trip instead. */
@@ -102,6 +112,10 @@ export declare class LlEmitter {
     /** Interned string literals: UTF-8 text → { symbol, byte length } —
      * first-use order, the runtime ABI’s determinism discipline. */
     private readonly literals;
+    /** Literal equality helpers: literal text → helper symbol (literalEquals). */
+    private readonly literalEqualities;
+    /** Interned bigint literals: hex magnitude with sign → { symbol, value }. */
+    private readonly bigintLiterals;
     /** Symbols of interned constant data, named by content (contentSymbol). */
     private readonly contentSymbols;
     /** Interned unit-armed union instances: "unionId:tag" → symbol — one
@@ -110,6 +124,10 @@ export declare class LlEmitter {
     private readonly unitInstances;
     /** unionId → symbol of the union's immortal ABSENT field-slot instance. */
     private readonly absentInstances;
+    /** 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. */
+    private readonly retypeGuards;
     /** The nullable-union ABSENT sentinel was referenced (absentInstanceRef). */
     private needsNullableAbsent;
     private readonly immortalValues;
@@ -122,6 +140,8 @@ export declare class LlEmitter {
         sym: string;
         src: string;
         fl: string;
+        pattern: string;
+        flags: string;
     }>;
     /** Interned tagged-template strings objects: per-site key → { symbol,
      * interned cooked-literal refs }. One immortal ScrArr of string slots
@@ -182,6 +202,9 @@ export declare class LlEmitter {
     private readonly lazyCaptureBoxes;
     private readonly lazyStackBoxes;
     private borrowedParameters;
+    /** Captures of the current closure body that its environment holds
+     * unchanged for the closure's whole life (LazyCaptures.stableCaptures). */
+    private stableCaptureIds;
     /** Parameters proven projection-only: callers may pass stack boxes. */
     private projectedParameters;
     private stableCallBindings;
@@ -237,6 +260,17 @@ export declare class LlEmitter {
     /** Method names with at least one may-throw implementation — the
      * virtualCall pending check's key. */
     readonly mayThrowMethods: Set<string>;
+    /** Async functions awaited directly at some `await f(...)` site; each
+     * gets an await-call entry (emitAsyncAwaitCall). */
+    readonly awaitCallees: Set<string>;
+    /** Async functions returned directly at some `return f(...)` site of an
+     * async function; each gets an adopting entry (emitAsyncAwaitCall). */
+    readonly adoptCallees: Set<string>;
+    /** 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. */
+    private adoptedOperand;
+    takeAdoptedOperand(): LlValue | null;
     /** setTimeout and friends appeared somewhere: main must run the event
      * loop even in programs with no async functions. */
     usesTimers: boolean;
@@ -309,6 +343,8 @@ export declare class LlEmitter {
     private readonly initializerBindings;
     /** Whole-program int32 storage and parameter/result facts. */
     readonly int32Slots: Int32Slots;
+    /** Functions whose direct calls use i32 parameters or results. */
+    readonly int32Abis: ReadonlyMap<string, Int32Abi>;
     /** Immutable module constants (contract types) whose graphs become
      * immortal once initialized: their reads need no reference counting. */
     readonly immortalGlobals: ReadonlySet<string>;
@@ -334,10 +370,17 @@ export declare class LlEmitter {
      * not a constructor (where they change), not async or a generator. */
     private finalFieldBorrows;
     integerRanges: IntegerRanges;
+    /** Sums whose result only feeds 32-bit conversions (wrapping-sums.ts). */
+    wrappingSums: Set<IrExpr>;
     private byteWindowsEnabled;
     private byteWindowEntries;
     bytesBounds: ReadonlySet<IrExpr | IrStmt>;
     integerViews: Map<string, string>;
+    /** Number locals of the current function stored only as an i32
+     * (int32-locals.ts); their slots are `alloca i32`. */
+    int32Locals: Map<string, Int32Local>;
+    /** The written values (and `++`/`--` nodes) the int32 proof covers. */
+    int32LocalWrites: ReadonlySet<IrExpr>;
     /** Enclosing try-with-FINALLY regions, innermost last: a `return`
      * inside one runs every crossed finally (innermost first) before the
      * actual ret — the runtime ABI’s pending-return path, with the finally
@@ -357,9 +400,12 @@ export declare class LlEmitter {
     /** Return type of the function being emitted — the unwind path returns
      * a dummy of this type (never read: callers check the flag first). */
     private currentReturnType;
-    /** Active only while emitting a wasm32 async body lowered with LLVM's
-     * switched-coroutine intrinsics. */
-    currentWasiCoro: {
+    /** The current body returns its number result as i32. */
+    private currentInt32Result;
+    /** Active only while emitting a body lowered with LLVM's
+     * switched-coroutine intrinsics (wasm32 async bodies and generators,
+     * native synchronous generators; see coroLowered). */
+    currentCoro: {
         kind: "async" | "generator";
         id: string;
         handle: string;
@@ -445,6 +491,24 @@ export declare class LlEmitter {
      * fresh promise from its outcome — the fiber trampoline's epilogue,
      * without the fiber. */
     private emitFiberlessAsyncSpawn;
+    /** Whether `await f(...)` may enter f through its await-call entry. The
+     * entry's result is the awaited value of f's own body type; direct calls
+     * never carry a lifted environment. */
+    awaitCallEligible(fnName: string): boolean;
+    /** The await-call entry of an async function (`sc_aw_*`): one direct
+     * `await f(...)` as a call returning the awaited value, so the call site
+     * needs no promise of its own. A fiberless body runs on the caller's
+     * stack as in its spawn wrapper; a clean result then takes the await's
+     * one microtask turn (scr_await_hop) and is returned without ever
+     * materializing the promise, which nothing else could observe. A throw
+     * builds the rejected promise exactly as the spawn wrapper would and
+     * awaits it, so the rejection reaches the awaiter on the same turn. Other
+     * bodies pack their arguments as the spawn wrapper does and enter
+     * scr_async_spawn_await_*, which parks the caller on the promise as soon
+     * as the body first suspends. The adopting entry (`sc_ad_*`, for
+     * `return f(...)` in an async function) adds the turn of the then job
+     * that adopts the returned promise, before the await proper. */
+    private emitAsyncAwaitCall;
     /** Per-async-function machinery — async.ts's scaffolding, .ll
      * flavored: an argument-pack struct type, a fiber trampoline (unpacks,
      * frees the pack, runs the ordinary compiled body, settles the
@@ -453,6 +517,9 @@ export declare class LlEmitter {
      * closures enter through (packs the args +1, scr_async_spawn runs the
      * fiber eagerly to its first suspension and returns the promise). */
     private emitAsyncScaffolding;
+    /** Whether `fn`'s body is emitted as an LLVM switched coroutine: every
+     * wasm32 async or generator body, and native synchronous generators. */
+    private coroLowered;
     /** Per-generator-function machinery — the async scaffolding's lazy
      * sibling (async.ts's emitGenScaffolding): the same argument pack,
      * a fiber trampoline whose epilogue stores the COMPLETION value (or
@@ -467,6 +534,14 @@ export declare class LlEmitter {
      * collision retries with a counter, still in first-use order. */
     private contentSymbol;
     internLiteral(text: string): string;
+    /** The inline equality test against one string literal (an
+     * `i1 (ptr)` helper LLVM inlines at each site), by literal symbol. */
+    literalEquals(text: string): string;
+    /** `@`-ref of an immortal ScrBigInt holding `value`, or null when the
+     * text is not a valid StringToBigInt input (the runtime parse then
+     * throws as usual). BigInt here is the same StringToBigInt as the
+     * program's, so every accepted spelling folds to the value Node gives. */
+    internBigIntLiteral(text: string): string | null;
     /** Interned NUL-terminated C-string constant (the scr_jb_puts /
      * stringify-indent currency) — `@`-ref, first-use order. */
     cstr(text: string): string;
@@ -476,6 +551,9 @@ export declare class LlEmitter {
      * emission initializes undefined-admitting fields through it
      * (ClassHost). */
     unitInstanceRef(unionId: string, tag: number): string;
+    /** The i8 flag that a checked-dynamic cast sets before caching one of
+     * this tagged union's boxes (unionRetype rebuilds once it is set). */
+    retypeGuardRef(unionId: string): string;
     /** The immortal ABSENT state of an undefined-armed record field slot
      * (IR fieldAbsent). */
     absentInstanceRef(unionId: string): string;
@@ -699,6 +777,11 @@ export declare class LlEmitter {
     /** Declaration stores initialize an empty TDZ box. Later stores check
      * it after the RHS and update scalar cells in place. References move in. */
     writeBindingBox(box: string, local: IrLocal, value: string, initializes?: boolean, borrowed?: boolean): void;
+    /** True when `fnName`'s borrowing body lends every reference parameter
+     * and returns an owned result: a closure over it then carries that body
+     * as its borrowing entry (ScrClosure.fn_borrowed), which callers that
+     * keep their arguments alive across the call may enter instead of `fn`. */
+    lendsEveryArgument(fnName: string): boolean;
     /** The LLVM symbol a direct call or closure enters a function through:
      * async bodies are entered via their emitted spawn wrapper (which runs
      * the fiber eagerly to its first suspension and returns the promise);
@@ -711,13 +794,25 @@ export declare class LlEmitter {
     emitWasiSuspend(promise: string | null): void;
     /** Suspend after a target-specific runtime helper already queued the
      * continuation (used by module awaits, which skip the hop when settled). */
-    emitWasiSuspendPrepared(): void;
+    emitCoroSuspendPrepared(): void;
     /** Move a clean async return value into the current fiber's promise. */
     private emitWasiFulfill;
     private emitFunction;
+    /** The double-ABI entry of a function with an i32 entry: every caller
+     * that is not a direct call (closures, dispatch, adapters, the runtime)
+     * enters here. A pending exception passes through to its caller. */
+    private emitInt32AbiWrapper;
+    /** 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. */
+    int32Argument(value: LlValue, expr: IrExpr): string;
+    /** A direct call's i32 result as a number, with the i32 as its integer
+     * and ToUint32 forms. */
+    int32Result(bits: string, type: IrType): LlValue;
     /** Keep the ordinary owned ABI for closures, virtual dispatch, generated
-     * runtime adapters and library exports. Only direct IR calls select the
-     * borrowing body. Ownership of other parameters moves into that body;
+     * runtime adapters and library exports. Only direct IR calls, calls of a
+     * known closure body and borrowing closure entries (fn_borrowed) select
+     * the borrowing body. Ownership of other parameters moves into that body;
      * borrowed parameters are released here on normal and exceptional exits.
      * The pending exception remains for the adapter's caller to handle. */
     /** With `kept`, the virtual adapter of a borrowing slot instead: the
@@ -751,6 +846,14 @@ export declare class LlEmitter {
      * borrow the element when the callee and later arguments (`writes`)
      * write no array element and nothing keeping the array alive. */
     unwrittenCallArrayRead(read: LocalArrayRead, writes: Writes): boolean;
+    /** `return p` of a promise inside try regions of an async function. JS
+     * completes the return first: p is evaluated, every crossed finally runs,
+     * and only then does the function's promise adopt p's settlement (a then
+     * job, then p's reaction). So the promise parks in a slot through the
+     * finally copies, like any pending return value, and the adopting await
+     * runs afterwards with no handler in scope: a rejection settles the
+     * function's promise instead of reaching its own catch clauses. */
+    private emitAdoptingReturn;
     /** `return x` of a local whose slot is an owned scope entry of the same
      * type: the return can take over the local's reference. */
     private movableReturn;
@@ -851,6 +954,9 @@ export declare class LlEmitter {
     private emitMovedSelfConcat;
     emitContainerExpr(e: ExprOf<"arrayLit" | "arrayNewLen" | "arrayGet" | "arrayHas" | "arrayState" | "arrIntrinsic" | "bytesNew" | "bytesIntrinsic" | "mapNew" | "mapIntrinsic" | "setIntrinsic" | "setNew">): LlValue;
     emitCallExpr(e: ExprOf<"call" | "ffiCall" | "closure" | "callValue" | "selfRef" | "new" | "classRef" | "newValue" | "instanceOfValue" | "promiseVoidWiden" | "upcast" | "downcast" | "instanceOf" | "virtualCall">): LlValue;
+    /** A direct async call an enclosing `await` consumes whole: emitted
+     * through the callee's await-call entry, yielding the awaited value. */
+    emitAwaitedCall(e: ExprOf<"call">, adopt?: boolean): LlValue;
     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;
@@ -1032,6 +1138,14 @@ export declare class LlEmitter {
     emitBytesLength(elem: IrBytesElem, receiver: string, bytes: boolean): LlValue;
     emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean): 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
+     * exact value. */
+    storeInt32Local(localId: string, value: LlValue, expr?: IrExpr): boolean;
+    /** The number of an int32-stored local's i32, with the i32 as its
+     * integer and ToUint32 forms. A parameter the body never writes reads
+     * 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;
     private emitBytesSet;
     emitBytesIntrinsic(e: IrExpr & {