@scriptc/compiler 0.4.0 → 0.4.2

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

@@ -1,5 +1,7 @@
+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";
+import { type RuntimeFeatures } from "../../ir/runtime-features.js";
 import { type DenseArrayLoop } from "./dense-array-loops.js";
 import { findInitializedByteLoopBindings } from "./byte-windows.js";
 import { matchBytesLoopVersion } from "./bytes-loop-versions.js";
@@ -97,7 +99,18 @@ 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. */
+    lowRegion?: boolean;
 }
+/** LlvmTargetOptions.lowRegion for an executable: Linux targets without
+ * sanitizers, whose address space below 32 GiB is free (ASan keeps its
+ * shadow memory there; other systems map their own images and libraries
+ * there). `platform` is a target platform (`linux`, `darwin`, `win32`,
+ * `wasi`). */
+export declare function lowRegionTarget(platform: string, sanitize: boolean): boolean;
 export declare function emitLlvmModule(input: IrModule, options?: LlvmTargetOptions): string;
 /** Keep large translation units below the host's single-string limit. */
 export declare function emitLlvmModuleSource(input: IrModule, options?: LlvmTargetOptions): string | readonly string[];
@@ -206,6 +219,13 @@ export declare class LlEmitter {
     integerArrayBindings: Set<string>;
     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):
+     * loadField/loadRef decode them and storeField/storeRef encode them. */
+    readonly compressedFieldPtrs: Set<string>;
+    /** Whether a class has compressed fields: main reserves the region before
+     * compiled code runs (scr_plr_init). */
+    usesCompactRefs: 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
@@ -215,10 +235,6 @@ export declare class LlEmitter {
     /** The alias tag of a runtime word that emitted code reads and writes
      * outside every field (the lifetime-region count, owner and cursors). */
     memoryAliasAttachment(category: string): string;
-    /** The `!range` attachment of an array length load: a length is at most
-     * 2^32 - 1 (the runtime's SCR_ARR_MAX_LENGTH), so conversions to double
-     * and back fold. 32-bit targets load the full range anyway. */
-    get arrayLengthRange(): string;
     /** Whether an element access at `index` of `arr` lies in the hole-free
      * prefix: the counter of a dense array loop's fast copy indexing one of
      * the arrays its entry test covered. */
@@ -373,6 +389,12 @@ export declare class LlEmitter {
     readonly callLifetimes: CallLifetimes;
     readonly constantCallbacks: Map<string, Map<string, string>>;
     currentConstantCallbacks: ReadonlyMap<string, string>;
+    /** Callback bindings whose closures an enclosing callback loop version
+     * proved to hold their known function: calls take the direct entry with
+     * no fallback (emitCallbackVersionedLoop). */
+    knownCallbacks: Set<string>;
+    readonly callbackVersioning: Set<IrStmt>;
+    callbackVersionsEnabled: boolean;
     readonly stackCallbacks: StackCallbacks;
     readonly receiverReaders: AmbientReceiverReaders;
     readonly stackCaptures: StackCaptures;
@@ -454,9 +476,15 @@ export declare class LlEmitter {
     /** Fiberless async functions a stackless coroutine body awaits directly;
      * each gets an inline await entry (emitCoroInlineAwait). */
     readonly inlineAwaitCallees: Set<string>;
+    /** Stackless async functions some coroutine body awaits directly: each
+     * gets a direct spawn entry (emitCoroDirectAwait). */
+    readonly directAwaitCallees: Set<string>;
     /** The async functions whose bodies never suspend and that a direct
      * await may enter in place (selectStacklessAsync). */
     private inlineAwaitable;
+    /** Locals whose array literal emitStmts left for the `await Promise.all`
+     * that reads them (deferredPromiseAllLocal). */
+    private readonly deferredPromiseAllEntries;
     /** 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. */
@@ -468,7 +496,10 @@ export declare class LlEmitter {
     /** The program calls mock.timers members (moduleUsesMockTimers): timer
      * calls emit scr_test.c's mock-aware entry points. */
     readonly mockTimers: boolean;
-    private schedulesInContextValue;
+    private runtimeFeaturesValue;
+    /** The module's runtime features (moduleRuntimeFeatures), found with one
+     * walk of the module the first time any of them is read. */
+    get runtimeFeatures(): RuntimeFeatures;
     /** Whether timer and tick scheduling goes through the *_als entry
      * points (RuntimeFeatures asyncContext). */
     get schedulesInContext(): boolean;
@@ -486,7 +517,6 @@ export declare class LlEmitter {
     /** Identity-preserving static→dyn capsules for program classes and Web
      * APIs whose values remain directly observable. */
     readonly liveDynRefAdapters: Map<string, LlStreamTypedRefAdapter>;
-    private dynBuiltinStreamUse;
     /** See moduleUsesDynBuiltinStream. */
     get usesDynBuiltinStream(): boolean;
     /** Runtime-arm dispatchers for live union values. */
@@ -503,6 +533,12 @@ export declare class LlEmitter {
     readonly recordCloneShapes: Set<string>;
     readonly tracedShapes: Set<string>;
     readonly tracedUnions: Set<string>;
+    /** Inline-cache sites of dynamic-tier functions (js-ic.ts): one
+     * zero-initialized ScrJsIc per site (scr_js.h). */
+    jsIcSiteCount: number;
+    private jsIcSitesMemo;
+    /** The tier of the function being emitted. */
+    currentTier: IrFunction["tier"];
     /** The class graph (buildClassGraph): preorder numbering, hierarchy
      * membership, virtual slot lists. */
     readonly classMeta: Map<string, LlClassMeta>;
@@ -623,6 +659,19 @@ export declare class LlEmitter {
             max: number;
         };
     }>;
+    /** Constant number locals whose latest emitted declaration stored an
+     * exact integer beside the double, such as `const j = i * 4` in a
+     * typed-array loop version: an i64 slot and the integer's range. */
+    integerTemps: Map<string, {
+        slot: string;
+        type: "i64";
+        signed: true;
+        range: IntegerRange;
+    }>;
+    /** Integer temps are kept only in optimized synchronous functions: an
+     * async or generator body resumes with its locals in its frame, which
+     * an entry alloca is not part of. */
+    integerTempsEnabled: boolean;
     countedLoopsEnabled: boolean;
     /** Speculative integer loops (speculative-integers.ts) run in this function. */
     speculativeLoopsEnabled: boolean;
@@ -633,12 +682,23 @@ export declare class LlEmitter {
         resume: Map<IrStmt, string>;
         /** Globals whose double is written back only when the copy is left. */
         deferred: Set<string>;
+        /** The loop site's count of bailing entries in a row (a global), and
+         * whether this entry completed a speculated write (a slot). A proven
+         * integer loop has neither. */
+        bails?: string;
+        ran?: string;
     } | null;
+    /** Speculative loop sites numbered so far in the module. */
+    speculativeLoopSites: number;
     /** The ordinary copy being emitted: resume labels still to place. */
     speculationResume: Map<IrStmt, {
         label: string;
         placed: boolean;
     }> | null;
+    /** 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. */
+    speculationHeader: ((header: string) => void) | null;
     /** The function being emitted, for speculative globals. */
     speculativeFunction: string;
     /** Every function that writes each number global (computed on demand). */
@@ -649,6 +709,8 @@ export declare class LlEmitter {
      * not a constructor (where they change), not async or a generator. */
     finalFieldBorrows: boolean;
     integerRanges: IntegerRanges;
+    /** The current function's bounded for-loop cursors (integer-ranges.ts). */
+    integerLoopRanges: ReadonlyMap<IrStmt, ReadonlyMap<string, IntegerRange>>;
     /** Number arrays of the current function whose every present element is
      * an int32 (Int32[] contracts), or null when the module has none. */
     int32Elements: ((arr: IrExpr) => boolean) | null;
@@ -668,6 +730,9 @@ export declare class LlEmitter {
      * guard already passed. */
     readonly provenCountedGuards: Set<IrStmt>;
     bytesBounds: ReadonlySet<IrExpr | IrStmt>;
+    /** Worker programs: typed-array accesses whose views an enclosing version
+     * guard proved thread-owned. */
+    bytesOwned: ReadonlySet<IrExpr | IrStmt>;
     integerViews: Map<string, string>;
     /** Module globals the current function owns outright (initializer
      * bindings): their function-local slot, which stands in for the global. */
@@ -803,10 +868,19 @@ export declare class LlEmitter {
      * fiberless, and module evaluation bodies and `dyn` results keep fibers
      * as they do there. The runtime traps if a stackless body ever parks. */
     selectStacklessAsync(fnDefs: string[]): void;
+    /** Whether a fiberless body running on its caller's stack needs the
+     * frame scr_async_inline_enter/exit keep: it isolates the Error.stack
+     * frame chain, which only stack-observing programs push, as a fresh fiber
+     * would. Other programs run the body with a plain call. The body runs in
+     * its caller's AsyncLocalStorage context either way, as Node runs an async
+     * body up to its first await. The frame also counts the bodies running on
+     * a fiber's stack for the runtime's trap on a fiberless body that
+     * suspends. */
+    get fiberlessFrames(): boolean;
     /** The spawn wrapper of a fiberless async function: runs the body on the
-     * caller's stack between scr_async_inline_enter/leave and settles the
-     * fresh promise from its outcome — the fiber trampoline's epilogue,
-     * without the fiber. */
+     * caller's stack (between scr_async_inline_enter/leave when
+     * fiberlessFrames) and settles a fresh promise from its outcome — the
+     * fiber trampoline's epilogue, without the fiber. */
     emitFiberlessAsyncSpawn(fn: IrFunction, spawnParams: string[]): string[];
     /** 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
@@ -816,10 +890,23 @@ export declare class LlEmitter {
      * place (emitCoroInlineAwait): f never suspends, and its direct call is
      * one an await-call entry could take. */
     inlineAwaitEligible(fnName: string): boolean;
+    /** Whether a stackless coroutine body's `await f(...)` may await f's
+     * fiber record instead of its promise (emitCoroDirectAwait): f is a
+     * stackless async function whose direct call an await-call entry could
+     * take. The await consumes the promise, so nothing else can observe it.
+     * Worker programs keep the promise for their stop checkpoint. */
+    directAwaitEligible(fnName: string): boolean;
+    /** A stackless coroutine body's `await f(...)` of a stackless f, without
+     * f's promise object: f's prefix runs as the spawn of a fiber record that
+     * keeps the promise inside. A body still running wakes this coroutine
+     * when it finishes, where its promise's settlement would wake its one
+     * waiter; a finished one takes the settled await's turn. The result (or
+     * the rejection, re-thrown) comes out of the record, which goes. */
+    emitCoroDirectAwait(call: ExprOf<"call">, type: IrType): LlValue;
     /** The inline await entry of a fiberless async function (`sc_ai_*`): its
-     * body on the caller's stack between scr_async_inline_enter/exit, as in
-     * its spawn wrapper, returning the result and leaving a throw pending for
-     * the awaiting coroutine (emitCoroInlineAwait). */
+     * body on the caller's stack (between scr_async_inline_enter/exit when
+     * fiberlessFrames), as in its spawn wrapper, returning the result and
+     * leaving a throw pending for the awaiting coroutine (emitCoroInlineAwait). */
     emitAsyncInlineAwaitCall(fn: IrFunction): string[];
     /** A stackless coroutine body's `await f(...)` of a fiberless f, the
      * await-call entry's turns without its promise: the body runs in place,
@@ -828,6 +915,32 @@ export declare class LlEmitter {
      * the spawn wrapper's promise would. An adopting await (`return f(...)`)
      * first takes the adoption's then-job turn either way. */
     emitCoroInlineAwait(call: ExprOf<"call">, adopt: boolean): LlValue;
+    /** The entries of `Promise.all(arg)` that a stackless coroutine body's
+     * await may run in place (emitCoroInlinePromiseAll): `arg` is a non-empty
+     * array literal, or the local whose declaration emitStmts deferred to this
+     * await (deferredPromiseAllEntries), whose every entry is a call to a
+     * never-suspending async function, and the result is an array. Null
+     * otherwise. Consumes a deferred local's entries. */
+    inlinePromiseAllEntries(all: ExprOf<"intrinsic">): ExprOf<"arrayLit"> | null;
+    /** Whether every entry of `entries` is a call an await could run in place
+     * (inlineAwaitEligible) that yields its promise's inner type. */
+    private promiseAllInlineable;
+    /** Whether `stmts[i]` declares a local holding an array literal that only
+     * `stmts[i + 1]` reads, as the operand of `await Promise.all(local)` that
+     * runs first in that statement and may run its entries in place. Nothing
+     * runs between the literal and the await, so the await evaluates the
+     * literal itself (inlinePromiseAllEntries). Debug builds keep the local. */
+    deferredPromiseAllLocal(stmts: readonly IrStmt[], i: number): ExprOf<"arrayLit"> | null;
+    /** A stackless coroutine body's `await Promise.all([f(...), ...])` of
+     * never-suspending calls, with Promise.all's turns and without its
+     * promises: the entries run in place in order and their values fill the
+     * result array. Promise.all queues one reaction job per entry, back to
+     * back, and the last of them settles the result, whose await then takes a
+     * turn: here one turn stands for the entries' jobs and a second for the
+     * await. A throwing entry becomes the rejection the await re-throws from
+     * its turn; the remaining entries still run, and later throws are handled
+     * rejections, as Promise.all's subscriptions make them. */
+    emitCoroInlinePromiseAll(entries: ExprOf<"arrayLit">, type: IrType): LlValue;
     emitAsyncAwaitCall(fn: IrFunction, argPackLines: string[] | null, adopt?: boolean): string[];
     emitAsyncScaffolding(): string[];
     /** Whether `fn`'s body is emitted as an LLVM switched coroutine: every
@@ -970,11 +1083,13 @@ export declare class LlEmitter {
      * releases the dummy (NULL for refcounted kinds) harmlessly. A scalar
      * call result of the function's return type may be passed as the unwind's
      * dummy value (see emitUnwind). `poll` marks a worker termination poll
-     * (function entry or loop budget), whose test must stay ordered. */
+     * (function entry or loop budget), whose test must stay ordered. A
+     * `guard` (an i1) limits the test to the paths where it is true: false
+     * where the joined call could not have left anything pending. */
     emitPendingCheck(passThrough?: {
         name: string;
         type: IrType;
-    }, poll?: boolean): void;
+    }, poll?: boolean, guard?: string): void;
     /** After a runtime call that ALWAYS leaves an exception pending (the
      * compiler-resolved Node throws): the pending test would always answer
      * true, so unwind unconditionally. Emission continues in a block with no
@@ -993,7 +1108,8 @@ export declare class LlEmitter {
     emitLoopCopies(loop: Extract<IrStmt, {
         kind: "while" | "doWhile" | "for";
     }>, allowed: boolean, exit: string, emitCopy: (exit: string) => void): void;
-    writeBackSpeculativeGlobals(deferred: Set<string>): void;
+    /** Store the double of each deferred shadow back to its binding. */
+    writeBackDeferred(deferred: Set<string>): void;
     /** A number local whose only storage is its own double slot, so an i64
      * shadow beside it can stand for it within one loop. */
     speculativeLocal(id: string): boolean;
@@ -1062,13 +1178,21 @@ export declare class LlEmitter {
      * 1 on hierarchy members, then the flattened field list. Runtime error
      * classes GEP through %ScrError (their structs live in the runtime; the
      * def's [name, message, %code, %cause] order matches the layout). */
-    classFieldPtr(objName: string, className: string, field: string): {
+    classFieldPtr(objName: string, className: string, field: string, refs?: "pointer" | "compressed"): {
         ptr: string;
         type: IrType;
         inline: boolean;
+        compressed: boolean;
     };
-    /** `o->vt->pre` — the dynamic class's preorder number (borrowed object;
-     * the static class names which struct spelling carries the vt word). */
+    /** Loads the reference a field pointer addresses: a pointer, or the
+     * decoded 32-bit reference of a compressed field (compressedFieldPtrs).
+     * `tagged`: the load carries the field's alias tags. */
+    loadRef(ptr: string, tagged?: boolean): string;
+    /** Stores `value` (a pointer) through a field pointer: as is, or encoded
+     * as the 32-bit reference of a compressed field. */
+    storeRef(ptr: string, value: string): void;
+    /** The dynamic class's preorder number (borrowed object; the static class
+     * names the struct spelling and where the number is, classPreLines). */
     loadVtPre(objName: string, staticClassName: string): string;
     /** The class object's static symbol (classes as values), registering it
      * for assembly on first use and interning the .name literal while the
@@ -1133,6 +1257,13 @@ export declare class LlEmitter {
     emitDebugLocal(local: IrLocal, slot: string, arg?: number, captured?: boolean): void;
     /** Loads a boxed binding's box pointer out of its slot. */
     loadBox(slot: string): string;
+    /** The function a call through `callee` is known to reach (a literal
+     * closure, or a binding the constant-callback census resolves) and the
+     * entry it calls directly. Async and generator functions stay indirect. */
+    knownCallbackTarget(callee: IrExpr): {
+        known: IrFunction;
+        direct: string;
+    } | undefined;
     /** The payload slot of a capture box (ScrBox.slot, field 5). */
     boxSlot(box: string): string;
     boxGet(box: string, t: IrType): string;
@@ -1446,8 +1577,11 @@ export declare class LlEmitter {
      * immutable (scr_publish with the static type's walker) and answers the
      * same value. Throws (pending) when a dyn part is unpublishable. */
     private emitPublish;
-    /** Branches on "`obj` is published" (rc == SIZE_MAX); leaves the builder
-     * in the cold block and answers the continuation label. */
+    /** Branches on "`obj` is published" (rc == SIZE_MAX, or a count of
+     * UINT32_MAX in the low half for `count` i32: classes.ts
+     * LlClassMeta.idInRc, or the top bit of a compact header word for
+     * "compact": classes.ts COMPACT_PUBLISHED); leaves the builder in the cold
+     * block and answers the continuation label. */
     private emitPublishedTest;
     private publishedNamesSym;
     /** The class-name table the hierarchy field guards index by preorder. */
@@ -1534,6 +1668,9 @@ export declare class LlEmitter {
     borrowableNullableWrap(e: IrExpr): "unit" | "ref" | null;
     materializeSplitLocal(localId: string): void;
     emitExpr(e: IrExpr): LlValue;
+    /** The helper classification of this module's inline-cache sites. */
+    get jsIcSites(): JsIcSites;
+    jsIcSite(): string;
     /** A fresh read-site cache for one constant-key dyn read. */
     dynReadIcSite(): string;
     dynKind(d: string): string;
@@ -1619,7 +1756,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): LlValue;
+    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean, owned?: 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
@@ -1630,7 +1767,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): void;
+    emitBytesSet(elem: IrBytesElem, receiver: string, index: LlValue, value: LlValue, indexExpr?: IrExpr, expr?: IrExpr, inBounds?: boolean, owned?: boolean): void;
     emitBytesIntrinsic(e: IrExpr & {
         kind: "bytesIntrinsic";
     }): LlValue;